Overview

This article covers how to import SMS contacts into Cordial using a CSV file or with the API or UI.

Before you can send messages with Cordial, you need to import your contacts. While you can add contacts one at a time, you'll most likely import them using a CSV (comma-separated values) file.

• Visit our Import contacts: prerequisites article to learn about creating your data file and completing the other necessary steps before you can import contacts into Cordial.

Prerequisites

• When importing subscribed SMS contacts with a CSV file, the program keyword and suppress double opt-in (suppressDOI) values are required. When importing subscribed SMS contacts with the API, the suppressDOI values are optional.

  If set to true, the suppressDOI prevents a double opt-in message from being sent to your contacts. This is useful for contacts who are already subscribed to your messaging.

  The suppressDOI is very powerful. If used incorrectly, it could result in non-compliance by automatically subscribing contacts who haven't opted into your messaging, which is against the code of conduct for mobile carriers.

  • Program keyword: must contain an existing program keyword set on the Cordial account.
  • suppressDOI: must contain true or false.
    • If true = the contact is added with subscribed status, and we don't send the opt-in message.
    • If false = the contact is added with pendingDOI status, and the opt-in message is sent.

  When using the suppressDOI with an existing contact who tries to subscribe again or send a double opt-in message, these actions won't take effect.

  Other notes on importing address and subscribeStatus are always required in all cases.

• When importing unsubscribed SMS contacts (or those with a status of none), the program keyword and suppressDOI values are optional.

  • The program keyword can be empty for these statuses.
  • The suppressDOI will default to false if it's empty or missing.

Add or update contacts via CSV file

To import SMS contacts into Cordial via the UI, API, or ETL, include the following fields on the CSV file and import map:

• address
• keyword
• subscribedAt
• subscribeStatus
• suppressDOI

Your CSV file should look similar to this:

Add or update contacts via API

You can add or update SMS contacts using these methods:

• POST /v2/contacts
• PUT /v2/contacts/{primary_key} 

When sending an API request, the suppressDOI is optional.

• If true = the contact is added with subscribed status, and we don't send the opt-in message.
• If false = contact is added with pendingDOI status, and the opt-in message is sent.

{
   "channels": {
       "sms": {
          "address": "1920123456",
          "programs": {
              "cordialthreads": {
                 "keyword": "join",
                 "subscribeStatus": "subscribed",
                 "suppressDOI":true } } } } }

Add or update contacts via the UI

1. Log in to Cordial and navigate to Contacts > Contact Profile. Provide the required information or select the contact you want to update. 

2. From the Contact Profile page, select Edit in the Channels pane and update the contact as needed.

When contacts are set to Subscribed in the UI, the double opt-in messages will automatically be sent and the contacts' status will change to pendingDOI. To suppress the double opt-in message from triggering, contact your CSM. If the status is set to unsubscribed in the UI, no message will be sent, and the contact's status will change to unsubscribed.