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
}