Overview

You can use the contacts API collection to retrieve, add, and update the SMS object using the appropriate JSON body.

Example SMS object

SMS object retrieved using the GET method:

{
  "channels": {
    "sms": {
      "address": "12225555151",
      "programs": {
        "cordialthreads": {
          "keyword": "join",
          "subscribedAt": "2020-04-16T20:52:21+0000",
          "unsubscribedAt": "",
          "subscribeStatus": "subscribed"
        }
      }
    }
  }
}

Parameter details

The SMS channel key may differ depending on your account configuration.

SMS subscribe status

SMS contact subscribe status can be none, pendingDOI, subscribed, or unsubscribed.

Create a new SMS record

You can create a new SMS record using the POST method and the appropriate JSON body.

Request to create a new SMS record (minimum requirements)

{
  "channels": {
    "sms": {
      "address": "12225555151"
    }
  }
}

The resulting record is given the subscribe status of none at the SMS channel level. The DOI signup process will not be triggered.

Request to create and subscribe an SMS contact via the API

{
  "channels": {
    "sms": {
      "address": "12225555151",
      "programs": {
        "cordialthreads": {
          "keyword": "join",
          "subscribeStatus": "subscribed"
        }
      }
    }
  }
}

When subscribing a contact, the SMS programName, keyword and subscribeStatus values are required. This POST will trigger the DOI signup process and the opt-in message will be sent to the contact's SMS channel address. The resulting contact's subscribe status is set to pendingDOI at the SMS program level. When the contact confirms their intent (completes the DOI signup process), the subscription status will change to subscribed.

Request to create and subscribe an SMS contact via JavaScript Listener v2

{
crdl("contact", {"sms": "12225555151"}, {
        "channels": {
                "sms": {
                        "address": "12225555151",
                        "programs": {
                                "cordialthreads": {
                                        "keyword": "join",
                                        "subscribeStatus": "subscribed"
                                }
                        }
                }
        }
})
}

Attempts to subscribe a contact without the SMS program name and keyword values will result in an error.

Update an existing SMS record

You can update existing SMS records using the PUT method and the appropriate JSON body.

Request to unsubscribe an existing SMS contact

{
  "channels": {
    "sms": {
      "address": "12225555151",
      "programs": {
        "cordialthreads": {
          "subscribeStatus": "unsubscribed"
        }
      }
    }
  }
}

The SMS program keyword is not required in order to unsubscribe the contact. This PUT will immediately set the contact's SMS program subscription status to unsubscribed and the contact will be sent the default stop message.

Resubscribe an existing SMS contact

• The most recent subscribedAt and unsubscribedAt timestamps remain in the unsubscribed contact record. This is an example SMS record after being unsubscribed from the SMS marketing program.

  {
    "channels": {
      "sms": {
        "address": "12225555151",
        "programs": {
          "cordialthreads": {
            "keyword": "join",
            "subscribedAt": "2020-07-23T00:36:16+0000",
            "unsubscribedAt": "2020-07-24T00:38:51+0000",
            "subscribeStatus": "unsubscribed"
          }
        }
      }
    }
  }

• The same SMS channel address can be resubscribed using the PUT method and the appropriate JSON body.

  {
    "channels": {
      "sms": {
        "address": "12225555151",
        "programs": {
          "cordialthreads": {
            "keyword": "join",
            "subscribeStatus": "subscribed"
          }
        }
      }
    }
  }

• The subscribeStatus will be set to pendingDOI and updated to subscribed after contact completes the DOI signup process. The subscribedAt timestamp will also be updated to reflect the most recent subscription date and time, and the previous unsubscribedAt timestamp will not be retained.

  {
    "channels": {
      "sms": {
        "address": "12225555151",
        "programs": {
          "cordialthreads": {
            "keyword": "join",
            "subscribedAt": "2020-07-23T00:36:16+0000",
            "subscribeStatus": "pendingDOI"
          }
        }
      }
    }
  }