Send transactional SMS messages

How It Works

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.

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

Your Acoustic Campaign org must have SMS enabled by provisioning.
A database in your Acoustic Campaign org must have SMS enabled.
The user making the API call must be enabled for SMS.
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

Attribute	Description	Example
Content [required]	SMS message body, string.	Hello %%FIRST NAME%%!! Happy birthday!
--- Contacts [required]	--- List of contacts who will be sent the SMS message (max 1000 contacts per call), array.	--- Use Contact ID or Contact Lookup.
--- Contact ID [optional]	--- SMS phone number for the contact (must include country code), long.	--- 19495001234
--- Contact Lookup [optional]	--- Provide a field name, value and channel to lookup the contact, array.	--- Mobile number, 12015557778, SMS
--- Personalization	--- Map of key value pairs for personalization, map.	--- Tracking: Z12A34567
--- Channel Qualifier [required]	--- SMS program ID. See How to find SMS program ID. string	--- 12345
--- Personalization Defaults [optional]	--- Value to return if personalization data is not found for a contact., map,	--- FIRST NAME: Valued Customer
--- Source [optional]	--- Attribute returned as part of the Universal Behavior event., string,	--- Transaction ID 1234

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

Scenario	Code	Message
Success	202	Response body includes API response location and Response ID
Personalization tag does not match DB field name	400	Wrong personalization tags {personalization tag}
Improper JSON format	400	Bad request
Invalid SMS program ID	400	SMS Program is inactive or not found with identifier {SMS Program ID}.
SMS program is inactive	400	SMS Program is inactive or not found with identifier {SMS Program ID}.
SMS program is empty	400	Channel qualifier should be present
SMS content exceeds 800 characters	400	The message exceeded the maximum 800 character limit.
SMS content is empty	400	SMS content should be present
Contact array has more than 1000 contacts	400	Contacts must contain at least 1 contact and cannot exceed more than 1000 contacts.
API call does not include a Contact ID or Contact Lookup	400	Contact information is empty. Please provide contact identifier or lookup keys.
Expired access token	401	The access token has expired. Token provided was: {Token}
SMS is not enabled for Org, database or user	403	Forbidden

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
}

How It Works

Use cases

Requirements to use this API

📘Note:

Parameters

Sample Payloads

Response Codes

📘
Note: