You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Add or Update Profiles and Traits with a CSV
3
3
plan: engage-premier
4
4
---
5
-
Use the CSV Uploader to add or update user profiles and set subscription states.
5
+
You can use the Profiles CSV Uploader to add or update user profiles and traits. This page contains guidelines for your CSV upload and explains how to upload a CSV file to Engage.
6
6
7
-
When you upload a CSV file, Engage adds new profiles and updates existing user profiles. Each CSV row corresponds to a user profile and columns to an identifier in your [identity resolution configuration](/docs/unify/identity-resolution/identity-resolution-settings/).
7
+
## CSV file upload guidelines
8
8
9
-
You can also [set subscription states](#set-user-subscriptions) for each email and phone number that you upload in the CSV. Subscription states help you track which email addresses and numbers you have permission to market to.
10
-
11
-
> warning ""
12
-
> Uploading a CSV creates new profiles and updates existing profiles. These profile updates may lead to users entering existing audiences or message campaigns.
13
-
14
-
> info ""
15
-
> Using the CSV Uploader to upload user profiles to Engage will **not** increase your MTUs count. [Learn more](/docs/guides/usage-and-billing/mtus-and-throughput/#mtus-and-engage) about MTUs and Engage.
9
+
Keep the following guidelines in mind as you upload CSV files to Twilio Engage:
16
10
11
+
- You can only upload `.csv` files.
12
+
- Files can't be empty and must have at least one header and one row.
13
+
- You can't have multiple columns with the same header.
- CSV files cannot exceed 1 million rows (plus one header row), 299 columns, or 100 MB in file size.
16
+
- You can only upload one file at a time.
17
+
- Add an identifier column or `anonymous_id` in your identity resolution configuration.
18
+
- Leave any unknown values blank to avoid bad data. Engage can create a user profile from a single identifier in your CSV.
19
+
- The template won't include duplicate custom traits, traits with trailing, leading, or multiple consecutive spaces between characters, or [unallowed characters](#allowed-csv-file-characters).
20
+
- Custom traits column headers are case-sensitive. For example, `first Name`, `FIRST Name`, and `First Name` would all be different traits in the template.
21
+
- Trailing, leading, or multiple consecutive spaces between characters are not allowed.
22
+
- The CSV uploader shares [Unify product limits](/docs/unify/product-limits/).
17
23
18
24
## Upload a CSV file
19
25
20
26
Use the **Upload CSV** page to upload a CSV file in your Segment space:
27
+
21
28
1. Navigate to **Unify > Profile explorer** or **Engage > Audiences > Profile explorer**.
22
29
2. Click **+Add Profiles**.
23
30
3. Download and fill out the CSV template.
24
31
4. Upload your CSV file.
25
32
26
33
### 1. Download your CSV template
27
34
28
-
Click **Download Template** to download a CSV template with identifier columns from your identity resolution configuration. Engage adds subscription columns next to email and SMS identifiers, where you can update subscription states for email addresses and phone numbers.
29
-
30
-
> info ""
31
-
> CSV files can only have a single **email** and **phone** identifier column. Include any additional email addresses or phone numbers for a user profile as a separate row.
32
-
33
-
Navigate to **Unify > Unify settings** and select the **Identity resolution** tab to view or add identifiers in your Segment workspace.
35
+
Click **Download Template** to download a CSV template with identifier columns from your identity resolution configuration.
34
36
35
37
### 2. Fill out your CSV file
36
38
37
-
Enter values for the identifiers in your CSV file. You can also [set email, phone, and WhatsApp subscriptions](#set-user-subscriptions) using the `email_subscription_status`, `sms_subscription_status`, and `whatsapp_subscription_status` columns.
38
-
39
-
A few guidelines to keep in mind as you fill out your CSV:
40
-
41
-
- Leave any unknown values blank to avoid bad data. Engage can create a user profile from a single identifier in your CSV.
42
-
- Enter phone numbers in your CSV in a format that's consistent with your Segment space. For example, if existing profiles in your workspace are in E.164 format `+15555550123`, enter numbers in your CSV using the same format `+##########`.
43
-
- The template won't include duplicate custom traits, traits with trailing, leading, or multiple consecutive spaces between characters, or [unallowed characters](#allowed-csv-file-characters).
44
-
- Custom traits column headers are case-sensitive. For example, `first Name`, `FIRST Name`, and `First Name` would all be different traits in the template.
45
-
- Trailing, leading, or multiple consecutive spaces between characters are not allowed.
46
-
- Make sure you've added an identifier column or `anonymous_id` in your identity resolution configuration.
47
-
39
+
Enter values for the identifiers in your CSV file.
48
40
49
41
### 3. Upload your CSV file
50
42
51
43
Upload a CSV file to Twilio Engage in two ways:
52
44
- Drag and drop the CSV file in the dropzone.
53
45
- Click **Browse** to locate the CSV file.
54
46
55
-
Engage processes CSV rows sequentially. Column values, except for a blank subscription status, override previous values for a user profile.
56
-
57
-
A blank subscription status in the CSV doesn't overwrite current **email** or **phone**[subscription states](/docs/engage/user-subscriptions/subscription-states/) in your Segment space.
58
-
59
47
### 4. Name your custom trait
60
48
61
49
Every time you upload a file, you have the option to add a custom trait to user profiles in the CSV. Use custom traits to help you [create audiences](/docs/engage/audiences/#building-an-audience) or send messages to a specific group of users. You can also add an existing custom trait name from your Segment workspace to the list of users in the CSV file.
@@ -91,7 +79,6 @@ To view the Update History page:
91
79
92
80
Select links to view CSV files and any associated [error reports](#error-reports). View the status of the file upload and the custom trait name added to user profiles in the CSV upload.
93
81
94
-
95
82
### Error reports
96
83
97
84
Use error reports to fix invalid rows and quickly re-upload data.
@@ -103,18 +90,9 @@ From the Update History page:
103
90
3. Remove any extra columns such as `row_number`, `error_message`, and `error_code`.
104
91
3. Click **Update subscription statuses**, and select **Upload a CSV** to re-upload the file.
105
92
106
-
Engage uses the following error codes on the report:
| INVALID_EMAIL | The email address isn't formatted correctly. |
111
-
| INVALID_PHONE | The phone number is invalid. |
112
-
| INVALID_SUBSCRIPTION_STATUS | The subscription status is invalid. Check the status or leave it blank. |
113
-
| CONFIGURATION_ERROR | Your SendGrid settings are not configured correctly. [Contact Segment support](https://app.segment.com/workspaces?contact=1){:target="_blank"} for help. |
114
-
| SYSTEM_ERROR | Something went wrong. Please try again. |
115
-
| UNABLE_TO_SUBSCRIBE | You can't update the subscription status for this phone number because the user unsubscribed by replying `STOP`. The user must reply `START` to resubscribe. |
93
+
### Validation errors
116
94
117
-
You may also encounter the following validation errors:
95
+
The following table lists validation errors you may run into with your profiles and traits CSV upload:
@@ -124,52 +102,9 @@ You may also encounter the following validation errors:
124
102
| Unexpected/fallback | Something went wrong. Try again later. |
125
103
| Empty header row | This file contains empty header(s). Remove the empty header(s), then try again. |
126
104
| File exceeds one million rows | Too many rows. You can upload up to 1000000 rows. |
127
-
| File exceeds 1000 columns | Your CSV file is exceeding the limit of 1000 columns. |
105
+
| File exceeds 299 columns | Your CSV file is exceeding the limit of 299 columns. |
128
106
| File exceeds 100 MB | Files can be up to 100 MB. |
129
107
| File contains a header with unallowed spaces | This file contains leading, trailing or consecutive spaces. Remove leading, trailing or consecutive spaces, then try again. |
130
108
| File contains duplicate headers | This file contains duplicate header(s). Remove duplicate header(s), then try again. |
131
109
| File contains invalid characters | This file contains invalid character(s). Remove invalid character(s), then try again. |
132
-
| Unconfigured `anonymous_id` or missing Identifier column | This file is missing an identifier column and does not have `anonymous_id` configured. Add an identifier column or add `anonymous_id` in your identity resolution configuration, then try again. |
133
-
134
-
135
-
136
-
137
-
## Set user subscriptions
138
-
139
-
Use the CSV Uploader to set subscription states for user email addresses and phone numbers.
140
-
141
-
> info ""
142
-
> Each user profile in a Segment workspace can have multiple email addresses and phone numbers, all with different subscription states.
143
-
144
-
For each CSV file, Engage adds:
145
-
- An `email_subscription_status` column next to the **Email** column.
146
-
- `whatsapp_subscription_status` and `sms_subscription_status` columns next to the **Phone** column.
147
-
148
-
In the `email_subscription_status`, `sms_subscription_status`, and `whatsapp_subscription_status` columns, set subscription states for email and phone numbers with the following values:
149
-
150
-
- `subscribed`: The user has actively subscribed.
151
-
- `unsubscribed`: The user has actively unsubscribed.
152
-
- `did-not-subscribe`: The user has provided their contact information but didn't actively subscribe or unsubscribe.
153
-
- **No subscription status (blank value)**: The user's profile exists in Segment, but they haven't explicitly provided their contact information, and no subscription information is available.
154
-
155
-
Engage accepts both uppercase and lowercase subscription status values.
156
-
157
-
> success ""
158
-
> Only contact users that subscribe to your communications. View [User Subscription States](/docs/engage/user-subscriptions/subscription-states/) to learn more.
159
-
160
-
## CSV upload guidelines
161
-
162
-
Please note the following limits as you upload CSV files to Twilio Engage:
163
-
- You can only upload `.csv` files.
164
-
- Files can't be empty and must have at least one header and one row.
165
-
- You can't have multiple columns with the same header.
- CSV files cannot exceed 1 million rows (plus one header row), 1000 columns, or 100 MB in file size.
168
-
- You can only upload one file at a time.
169
-
- If you upload the same email or phone number with different subscription states in a single CSV file, Engage doesn't guarantee the subscription status result.
170
-
171
-
- Add an identifier column or `anonymous_id` in your identity resolution configuration.
172
-
173
-
## Message consent
174
-
175
-
Segment recommends sending to subscribed users. If a recipient deletes or flags an unwanted message as spam, inbox providers might start to filter your messages straight to spam folders. View more SendGrid delivery [Best Practices](https://sendgrid.com/blog/why-are-my-emails-going-to-spam/){:target="_blank"} to prevent email from going to spam.
110
+
| Unconfigured `anonymous_id` or missing Identifier column | This file is missing an identifier column and does not have `anonymous_id` configured. Add an identifier column or add `anonymous_id` in your identity resolution configuration, then try again. |
Copy file name to clipboardExpand all lines: src/engage/user-subscriptions/csv-upload.md
+7-2Lines changed: 7 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,8 @@
1
1
---
2
-
title: Update Audiences with a CSV
2
+
title: Update Subscriptions with a CSV
3
3
plan: engage-premier
4
4
---
5
-
Use the CSV Uploader to add or update user profiles and set subscription states.
5
+
Use the CSV Uploader to add or update user subscription states.
6
6
7
7
When you upload a CSV file, Engage adds new profiles and updates existing user profiles. Each CSV row corresponds to a user profile and columns to an identifier in your [identity resolution configuration](/docs/unify/identity-resolution/identity-resolution-settings/).
8
8
@@ -14,6 +14,11 @@ You can also [set subscription states](#set-user-subscriptions) for each email a
14
14
> info ""
15
15
> Using the CSV Uploader to upload user profiles to Engage will **not** increase your MTUs count. [Learn more](/docs/guides/usage-and-billing/mtus-and-throughput/#mtus-and-engage) about MTUs and Engage.
0 commit comments