Transactional SMS REST API

Use cases

• Send an SMS message containing a PIN code in response to a contact’s request to update their password.
• Send an SMS message with a tracking number to a customer when their order is shipped.
• Send an SMS message to remind clients of their appointment time.

Requirements to use this API

1. Your Acoustic Campaign org must have SMS enabled by provisioning.
2. A database in your Acoustic Campaign org must have SMS enabled.
3. The user making the API call must be enabled for SMS.
4. The user making the API call must have valid Oauth credentials.

📘

Note:

Up to 10 concurrent requests are allowed to our API servers at any given time when using the OAuth method for authentication.

End Point
/channels/sms/sends

Parameters

Sample payloads

Use Case: Use a lookup key field to specify the contact who will be sent the SMS message.

{
“content”: “Your order has been received. We’ll send the tracking # when it ships.”,
“channelQualifier”: “148372”
“contacts”: [
{
“contactLookup”: [
{
“name”: “accountNumber”,
“value”: “123456789”,
“channel”: “SMS”
}
]}
]}

Use Case: Use Contact ID to specify the contact who will be sent the SMS message.

{
“content”: “Hello, we’ve received your order.”,
“contacts”: [
{
“contactId”: “12015557778”
}
],
“channelQualifier”: “148372”
}

Use Case: Specify SMS personalization for each contact in the payload (inline personalization).

{
“content”: “Hello, your order has shipped. Your tracking number is %%Tracking%%”,
“channelQualifier”: “148372”,
“contacts”: [
{
“contactId”: “12015557882”,
“personalization”: {
“Tracking”:”Z12A34567″
}
}
]}

Use Case: Send an SMS message with DB personalization and specify the default value to use if this DB field does not contain data. For example, if there’s no value in the “FirstName” field then the word “Customer” will be used.

{
“content”: “Hello %%FirstName%%, your order has shipped.”,
“contacts”: [
{
“contactId”: “19492319304”
}
],
“channelQualifier”: “148372”,
“personalizationDefaults”: {“FirstName”: “Customer”}
}

Response Codes

Sample Response Body – Success

{
  “meta”: {
    “attributes”: {},
    “generalErrors”: [],
    “fieldErrors”: {},
    “links”: [],
    “nextPageUrl”: null
  },
  “data”: {
    “location”: “https://engage-qa1-api.adm01.com/rest/channels/sms/sends/b9e79eb-16269cd0c8a-fe154a13e7aff661200edcf73a623cd6/status”,
    “id”: “b9e79eb-16269cd0c8a-fe154a13e7aff661200edcf73a623cd6”
  }
}

Sample Response Body – Failure – General Error

{  “meta”: {   
     “attributes”: {},   
     “generalErrors”: [     
        “Bad Request”   
      ],   
      “fieldErrors”: {},   
      “links”: [],   
      “nextPageUrl”: null 
    }, 
    “data”: null
}

Sample Response Body – Failure – Field Error

{  “meta”: {   
      “attributes”: {},   
      “generalErrors”: [],   
      “fieldErrors”: {   
        “channelQualifier”: “Channel qualifier should be present”
      },   
      “links”: [],   
      “nextPageUrl”: null 
    }, 
    “data”: null
}

Check Status of SMS Sent using the Transactional SMS API

SMS messages sent using the Transactional SMS API will not appear in the Acoustic Campaign user interface. However, you can view send status in the SMS Campaign Manager user interface by selecting Messages.

To check the status of the SMS send, you’ll need the transaction ID returned in the Transactional SMS API response body. Provide this transaction ID in the Get SMS Status API call to return the send status for contact(s) included in the API call.

Endpoint
/channels/sms/sends/{transactionId}/status

Parameters

Attribute: transactionId
Description: A transaction id returned by POST /channels/sms/sends, string, required
Example: ae70ea-162877c3e4d-2b052f2fd757abaa295b8c317ca481e9

Response Codes

If status is available, the response will return the following:

Sample Response Body – Get SMS Status API

{
  “meta”: {
    “attributes”: {},
    “generalErrors”: [],
    “fieldErrors”: {},
    “links”: [],
    “nextPageUrl”: null
  },
  “data”: {
    “totalContacts”: 2,
    “contactsProcessed”: 2,
    “contactStatus”: [
      {
        “contactLookup”: [
          {
            “channel”: “SMS”,
            “value”: “19492319305”
          }
        ],
        “smsSent”: false,
        “message”: “No consent found for 19492319305 in program 148078”
      },
      {
        “contactId”: 2354186872,
        “smsSent”: true
      }
    ],
    “errors”: []  }
}

Test your API call

Use Swagger to test your API call. To access the Swagger environment for your organization, replace {POD#} with the Pod where your organization exists:

For example, here's the link for Pod 1 organizations that use a US data center: