When you set up a shared file location and cadence, Attentive processes CSVs that you add to that location. This allows Attentive to map CSV rows to the following APIs:
- Messages: Map the CSV file to the Messages API to send SMS or MMS messages to subscribers.
- Custom attributes: Map the CSV file to the custom attributes endpoint to update subscriber attributes with information from the file.
Use this guide to format your files for Attentive to map to the endpoints. For basics on formatting a CSV file, see How to format a CSV file.
Note: You should work with an Attentive TAM/CSM/White Glove professional to set this up.
Attentive source requirements
In order for Attentive to effectively process and map your CSV file, the associated file location should be an S3 source or an SFTP source. The following table lists required information for both supported file locations. This applies to file-triggered message (FTM) jobs and custom attributes.
| S3 sources | SFTP sources |
| Bucket name: shared bucket between you and Attentive |
Host, Username and Password Port: optional; defaults to 22 if unspecified |
| Key name: comprised of the directory (/attentive) and a filename | File name: comprised of the directory and a file name |
| Encryption: optional; information to decrypt the file (if applicable) | Encryption: optional; information to decrypt the file (if applicable) |
File-triggered message jobs
A file-triggered message (FTM) job reads your CSV file and sends SMS/MMS messages according to information within the file. You can upload CSV files one time or on a recurring basis and schedule the FTM job accordingly. After the job reads the file location, your messages are downloaded, processed, and sent as outlined in the file and job specifications.
File formatting requirements
Each FTM job must include the following fields and the associated formatting:
| Field | Example formats | Description |
| Header |
Phone Number, Message, FirstName, External Id |
The first line of the file must be defined as the header. Attentive doesn’t enforce specific columns; however, any column referenced in the payload_mapping must exist in the file. |
| Phone number |
|
Subscriber’s phone number. This must be a specific column in the CSV file. Country codes and + are acceptable. There are no column name restrictions as long as the name is specified in the payload_mapping. |
| Message body | Hi |
The message copy that subscribers will receive. This field must be one of the columns on the CSV file. There are no column name restrictions as long as the name is specified in the payload_mapping. If you use an inline macro, make sure the referenced data exists in another column within that row. |
| File location | Upload/Attentive/Attentive_hourly_[[YYYYMMDDHH]].csv |
S3 location or SFTP directory |
| Sending time | 11am - 5pm ET every weekday. |
Include the recurring schedule or time when you want to send the message. If you only include one specific time, the job only runs once. |
| File name |
Attentive_hourly_[[YYYYMMDDHH]].csv<&US/Eastern&> |
Attentive accepts CSVs with any format and wildcard matching with dates. This way, Attentive can retrieve files based on a DateTime formatter. |
Column names aren’t fixed; you can name each column whatever you want as long as it matches the reference names in the payload_mapping. The message body and header columns must be outlined in the payload_mapping.
If you incorporate macros in the CSV or payload_mapping, make sure to include the reference values in a separate column. For example, using the {{subscriber.firstName}} macro requires the file to contain another column named “FirstName.”
Payload mapping requirements
Each FTM job is defined by a job mapping. Payload_mapping houses information regarding how to interpret the CSV file and data sent to our Tactical Messaging Service. In order for the job to run successfully, your FTM job file must include the following information:
| Field | Example formats | Description |
| to |
{{PhoneNumber}} |
Subscriber’s phone number. This must be a specific column in the CSV file. |
| body | {{SMSBodyText}} |
Message body that is sent to subscribers. This must be a specific column in the CSV file. |
| skipFatigue |
True |
Determines whether messages should ignore smart sending. The final value must be True or False. This value may be provided as a column and filled in with a macro. |
| useShortLinks |
True |
Determines whether Attentive should shorten links in sent messages. The final value must be True or False, but it can be provided as a column. |
| subscriptionType |
TRANSACTIONAL |
Indicates the type of SMS message being sent. This can be formatted as a column. |
| messageName |
ClientMarketing_batch_3 TriggeredMessage_Attn |
Identifies the sending message for reporting purposes. This can be formatted as a column. Header_mapping is important for associating the request with the correct company. |
Custom attributes
Attentive reads, processes, and updates segment attributes from a shared file location and schedule that you provide.
If you incorporate macros in the CSV, make sure to include the reference values in a separate column. For example, using the {{subscriber.firstName}} macro requires the file to contain another column named “FirstName.”
File formatting requirements
Each custom attribute must include the following fields and their associated formatting:
| Field | Formats | Description |
| File location | Upload/Attentive/Attentive_hourly_[[YYYYMMDDHH]].csv |
S3 location or SFTP directory |
| File name |
Attentive_hourly_[[YYYYMMDDHH]].csv<&US/Eastern&> |
Attentive accepts CSVs with any format and wildcard matching with dates. This way, Attentive can retrieve files based on a DateTime formatter. |
| Header | first_name, last_name, phone, birth_year |
The first line of the file must be defined as the header. Attentive doesn’t enforce specific columns; however, any column referenced in the payload_mapping must exist in the file. |
| Phone number |
15551234567 |
Subscriber’s phone number. This must be a specific column in the CSV file. Country codes and + are acceptable. There are no column name restrictions as long as the name is specified in the payload_mapping. |
When you’re naming columns, there are no formatting restrictions as long as you keep consistent names between the file columns and the columns referenced in the payload_mapping.
Payload mapping requirements
Each custom attributes job is defined by a job mapping. The key mapping, payload_mapping, defines how Attentive processes the information within the CSV file and sends it to the custom attributes endpoint. In order for the job to run successfully, your payload mapping must include the following fields; these are the same requirements as the endpoint.
| Field | Formats | Description |
| Properties |
|
Key-value mapping of your attributes to their associated values. Each key is a string, and values can be any type of value. Keys and strings are case-sensitive. |
| User | "user": {"phone": "+15551234567" } |
Subscriber who initiated the action. |
| Phone number | { "phone": "+15551234567" } |
Subscriber’s phone number (if known). This is required if you don’t have their email address. |
{ "email": "name@gmail.com" } |
Subscriber’s email address (if known). This is required if you don’t have their phone number. |