Transactional SMS REST API

Use this API to send an SMS message to contact(s) you specify by providing the SMS phone number or a lookup key. SMS messages will only be sent to contacts whose consent status in Acoustic Campaign is 'opted-in'. You can use this REST API with all Acoustic SMS partners, including mGage, Karix, Infobip, and Celmedia.

This API allows you to personalize the message using a database field or by specifying the personalization value in the API payload (inline personalization). Each call is limited to a maximum of 1,000 contacts but there is no limit on the number of times per day this API can be called.

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

AttributeData typeDescription
Content [optional]StringThe SMS message body. For example, Hello %%FIRST NAME%%!! Happy birthday!
contentId [optional]StringThe ID of the published message to be sent; if both content and contentId are provided, contentId will override content.
contactsArrayList of contacts. Phone number must include country code). You can include a maximum of 1000 contacts.
channelQualifierStringThe SMS Program ID.
personalizationDefaults [optional]MapMap of key-value pairs for personalization.
source [optional]StringAttribute returned to Campaign as part of the UB. For example, transactionId=1234.
characterSwapEnabled [optional]BooleanReplace characters specified in SMS Character Mapping. Supported only for SMPP.
ttlInMinutes [optional]LongTime in minutes after which this message should be discarded if it has not been sent yet.

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

ScenarioCodeMessage
Success202Response body includes API response location and Response ID
Personalization tag does not match DB field name400Wrong personalization tags {personalization tag}
Improper JSON format400Bad request
Invalid SMS program ID400SMS Program is inactive or not found with identifier {SMS Program ID}.
SMS program is inactive400SMS Program is inactive or not found with identifier {SMS Program ID}.
SMS program is empty400Channel qualifier should be present
SMS content exceeds 800 characters400The message exceeded the maximum 800 character limit.
SMS content is empty400SMS content should be present
Contact array has more than 1000 contacts400Contacts must contain at least 1 contact and cannot exceed more than 1000 contacts.
API call does not include a Contact ID or Contact Lookup400Contact information is empty. Please provide contact identifier or lookup keys.
Expired access token401The access token has expired. Token provided was: {Token}
SMS is not enabled for Org, database or user403Forbidden

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

ScenarioCodeMessage
Status not yet returned200Transaction status not found. Please try your request again in a few minutes.
Note: Use of invalid transaction IDs will return this message.

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

Response fieldData typeDescription
totalContactsNumericTotal number of contacts specified in the original sends request
contactsProcessedNumericThe number of contacts to whom we attempted to send
errorsStringSend error that happened. This could indicate an invalid program (channelQualifier), invalid phone number, or SMS provider not available.
Note: Transactional SMS API also checks for consent.
contactStatusArrayArray of contact specific status
contactID or contactLookupNumericThe recipientId or contactLookup value(s) processed
smsSentBooleanFlag indicating if the SMS was sent to the contact
messageString(optional) Error message is specified when the SMS was not sent to this contact

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:

https://api-campaign-{data center}-{POD#}.goacoustic.com/channels/sms_to_contacts_post_1

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

https://api-campaign-us-1.goacoustic.com/channels/sms_to_contacts_post_1