Merge pull request #448 from segmentio/repo-sync

repo sync

Author: bot-docsteam

src/engage/profiles/user-subscriptions/index.md

@@ -4,28 +4,28 @@ layout: engage
 engage: true
 ---
 
-Segment associates [subscription states](/docs/engage/profiles/user-subscriptions/set-user-subscriptions/) with contact vectors in your audiences. These states indicate the level of consent end users have given to receive your marketing campaigns.
+Segment associates [subscription states](/docs/engage/profiles/user-subscriptions/set-user-subscriptions/) with each email address and phone number in your audiences. Subscription states indicate the level of consent end users have given to receive your marketing campaigns.
 
 Knowledge of subscription states will help you understand which users can and cannot receive your campaigns. This page provides an overview of user subscriptions.
 
 ## The Four Subscription states
 
-Contact vectors in your audience have one of the four following user subscription states:
+Email addresses and phone numbers in your audience have one of the four following user subscription states:
 
-- **Subscribed**; users who opted in to your marketing campaigns
-- **Unsubscribed**; users who unsubscribed from your marketing campaigns
-- **Did not subscribe**; users who are neither subscribed nor unsubscribed
-- **No subscription status**; users for whom Segment has no subscription information
+- `subscribed`; users who opted in to your marketing campaigns
+- `unsubscribed`; users who unsubscribed from your marketing campaigns
+- `did-not-subscribe`; users who are neither subscribed nor unsubscribed
+- **No subscription status**; users who never gave Segment the email or phone number in your audience
 
 > warning "User Consent"
-> You can only send Engage campaigns to subscribed users.
+> You can only send Engage campaigns to users with a `subscribed` status.
 
 To learn how Segment determines user subscription states, read the [User Subscription State documentation](/docs/engage/profiles/user-subscriptions/subscription-states/).
 
 ## Setting User Subscriptions
 
 You can set user subscriptions manually when you upload contacts [using Engage’s CSV uploader](/docs/engage/profiles/csv-upload/). You can also use a CSV upload to correct contacts with outdated subscription states.
 
-Most user subscriptions are updated programmatically, using Segment APIs. The Public API and the `track` call handle subscription state changes made when users sign up to or change their subscription status to your marketing materials with online forms or within notification centers.
+Most user subscriptions update programmatically, using Segment APIs. The Public API and the Identify call handle subscription state changes made when users sign up to or change their subscription status to your marketing materials with online forms or within notification centers.
 
 View the [Setting User Subscriptions](/docs/engage/profiles/user-subscriptions/set-user-subscriptions/) page to learn more about user subscription changes.

src/engage/profiles/user-subscriptions/set-user-subscriptions.md

@@ -4,7 +4,7 @@ layout: engage
 engage: true
 ---
 
-Segment associates a [user subscription state](/docs/engage/profiles/user-subscriptions/subscription-states/) with each contact vector in your Engage audiences. Subscription states give you insight into the level of consent a user has given you to receive your Engage campaigns.
+Segment associates a [user subscription state](/docs/engage/profiles/user-subscriptions/subscription-states/) with each email address and phone number in your Engage audiences. Subscription states give you insight into the level of consent a user has given you to receive your Engage campaigns.
 
 You can set a user’s subscription state using a CSV file or, programmatically, using Segment’s APIs. On this page, you’ll learn how and when to use both processes.
 
@@ -18,7 +18,7 @@ For example, you may want to add contacts to Segment using an audience list sour
 
 To learn how to upload a CSV file to Segment, view the [Engage CSV Uploader page](/docs/engage/profiles/csv-upload/).
 
-To change a user’s email or SMS subscription status with a CSV file, include at least one of the following user subscription columns next to the contact column:
+To change the subscription status of an email or phone number with a CSV file, include at least one of the following user subscription columns next to the contact column:
 
 - `email_subscription_status`
 - `sms_subscription_status`
@@ -28,7 +28,7 @@ These columns take the following values:
 - `subscribed`; for users who opted in to your marketing campaigns
 - `unsubscribed`; for users who have unsubscribed from your marketing campaigns
 - `did-not-subscribe`; for users who have neither subscribed nor unsubscribed from your marketing campaigns
-- Blank; for profiles that have no subscription information
+- Blank; for email addresses or phone numbers that Segment collected without the user explicitly providing them
 
 Refer to the [User Subscription States documentation](/docs/engage/profiles/user-subscriptions/subscription-states/) for detailed explanations of each subscription state.
 
@@ -51,33 +51,51 @@ For example, a user might reach out to you after accidentally unsubscribing to y
 
 With Segment's APIs, you can manage user subscriptions programmatically on a real-time basis. Use the APIs for ongoing subscription status updates, like when users subscribe to your marketing campaigns on a website form or modify their subscription from within a notification center.
 
-### The Track call compared to the Public API Identify call
+### Choosing between the Identify call and the Public API
 
-To update Engage user subscriptions with Segment's APIs, first choose between a [standard Track call](/docs/connections/spec/track/), for non-critical subscription updates, or the [Public API Identify call](https://api.segmentapis.com/docs/){:target="_blank"}, for critical updates that require immediate confirmation, like unsubscribes.
+To update Engage user subscriptions with Segment's APIs, first choose between [the Identify call](/docs/connections/spec/identify/), for non-critical subscription updates, or the [Public API](https://api.segmentapis.com/docs/spaces/#replace-messaging-subscriptions-in-spaces){:target="_blank"}, for critical updates that require immediate confirmation, like unsubscribes.
 
-When you use the Track call, Segment replies with a standard HTTP `200 OK` status response code if it successfully received the request. Because the Track call updates user traits asynchronously, though, the `200 OK` code indicates that Segment has received, but not yet processed, the request. As a result, use the Track call for non-critical subscription updates, like form signups on your website or adding a subscription from within the user's notification center.
+When you use the Identify call, Segment replies with a standard HTTP `200 OK` status response code if it successfully received the request. Because the Identify call updates user traits asynchronously, though, the `200 OK` code indicates that Segment has received, but not yet processed, the request. As a result, use the Identify call for non-critical subscription updates, like form signups on your website or adding a subscription from within the user's notification center.
 
-When you make Identify calls to Segment's Public API, however, you'll get an immediate response that confirms that Segment both received and processed the request. Use the Public API, then, for unsubscribes, so users immediately find out if their subscription updated.
+When you update user subscriptions with Segment's Public API, however, you'll get an immediate response that confirms that Segment both received and processed the request. Use the Public API, then, for unsubscribes, so users immediately find out if their subscription updated.
 
 ### Format the Identify call payload
 
-For Segment to process the subscription status request, your Identify call payload must include at least one object with a subscription contact vector, the subscription type, and the subscription status.
+For Segment to process the subscription status request, your Identify call payload must include at least one object that contains an email address or phone number, its subscription type, and its subscription status.
 
-The following array contains example objects that update both SMS and email subscription statuses:
+The following example payload shows an Identify call with a `context` object, which you'll add to the Identify call to update user subscriptions. The `context` object contains a `messaging_subscriptions` array with two objects that update both SMS and email subscription statuses:
 
 ```json
-"messaging_subscriptions": [
+{
+  "userId": "12aBCDeFg4hIjKlM5OPq67RS8Tu",
+  "context": {
+    "messaging_subscriptions": [
       {
         "key": "(123) 555-5555",
         "type": "SMS",
         "status": “SUBSCRIBED” | “UNSUBSCRIBED”| “DID_NOT_SUBSCRIBE”
       },
       {
-        "key": "example@example.com",
+        "key": "test@example.com",
         "type": "EMAIL",
         "status": “SUBSCRIBED” | “UNSUBSCRIBED”| “DID_NOT_SUBSCRIBE”
       }
-    ]
+    ],
+    "externalIds": [
+      {
+        "id": "(123) 555-5555",
+        "type": "phone",
+        "collection": "users",
+        "encoding": "none"
+      }
+    ],
+    "traits": {
+       "email": "[email protected]"
+    }
+  },
+  "integrations": {},
+  "traits": {}
+}
 ```
 
 For successful requests, Segment instantly updates subscription states in your workspace. You can then display successful updates or error messages with users in your notification center.

src/engage/profiles/user-subscriptions/subscription-states.md

@@ -18,10 +18,10 @@ The following table displays the four subscription states:
 
 | subscription states    | description                                                                                                 | example                                                                                                                            |
 | ---------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| Subscribed             | A user has given you their contact information and consented to receive marketing campaigns.                | Users that have signed up for a weekly newsletter                                                                                 |
-| Unsubscribed           | A user has given you their contact information but doesn't want to receive campaigns.                       | Users that subscribed, then unsubscribed, from a weekly newsletter                                                                |
-| Did not subscribe      | A user gave you their contact information but made no decision about receiving marketing campaigns.         | A user provided their email address or phone number in an online transaction, but didn't sign up to receive your weekly newsletter. |
-| No subscription status | A user did not give you their contact information and made no decision about receiving marketing campaigns. | Segment collected the contact vector through identity resolution, but the user has not made a subscription decision.               |
+| `subscribed`             | A user has given you their contact information and consented to receive marketing campaigns.                | Users that have signed up for a weekly newsletter                                                                                 |
+| `unsubscribed`           | A user has given you their contact information but doesn't want to receive campaigns.                       | Users that subscribed, then unsubscribed, from a weekly newsletter                                                                |
+| `did-not-subscribe`      | A user gave you their contact information but made no decision about receiving marketing campaigns.         | A user provided their email address or phone number in an online transaction, but didn't sign up to receive your weekly newsletter. |
+| No subscription status | A user did not give you their contact information and made no decision about receiving marketing campaigns. | Segment collected an email or phone number through identity resolution. No user actively provided the email or phone number.               |
 
 > warning "Sending Permissions"
 > You can only send Engage campaigns to contacts with a subscribed user state.
@@ -58,14 +58,14 @@ You must include an unsubscribe option in all Engage email and SMS campaigns.
 
 ### Did not subscribe
 
-Users with **did not subscribe** contact vectors have provided you with their email address or phone number but have not given explicit permission to send them marketing materials.
+Users with the `did-not-subscribe` state associated with their email address or phone number gave you their contact information without explicitly agreeing to receive your marketing materials.
 
-The following scenarios often lead to user profiles who **did not subscribe**:
+The following scenarios often lead to an email or phone number with the `did-not-subscribe` subscription state:
 
-- A user provides their email or phone number during an online transaction, but doesn’t opt in to your marketing materials.
+- A user provides their email or phone number during an online transaction but doesn’t opt in to your marketing materials.
 - The user’s email address was obtained from a support request.
 
-Contact vectors with a `did not subscribe` status will not receive your marketing campaigns.
+Emails or phone numbers with a `did-not-subscribe` status won't receive your marketing campaigns.
 
 ### No subscription status