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
- 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 | Data type | Description |
---|---|---|
Content [optional] | String | The SMS message body. For example, Hello %%FIRST NAME%%!! Happy birthday! |
contentId [optional] | String | The ID of the published message to be sent; if both content and contentId are provided, contentId will override content. |
contacts | Array | List of contacts. Phone number must include country code). You can include a maximum of 1000 contacts. |
channelQualifier | String | The SMS Program ID. |
personalizationDefaults [optional] | Map | Map of key-value pairs for personalization. |
source [optional] | String | Attribute returned to Campaign as part of the UB. For example, transactionId=1234. |
characterSwapEnabled [optional] | Boolean | Replace characters specified in SMS Character Mapping. Supported only for SMPP. |
ttlInMinutes [optional] | Long | Time 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
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
}
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
Scenario | Code | Message |
---|---|---|
Status not yet returned | 200 | Transaction 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 field | Data type | Description |
---|---|---|
totalContacts | Numeric | Total number of contacts specified in the original sends request |
contactsProcessed | Numeric | The number of contacts to whom we attempted to send |
errors | String | Send 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. |
contactStatus | Array | Array of contact specific status |
contactID or contactLookup | Numeric | The recipientId or contactLookup value(s) processed |
smsSent | Boolean | Flag indicating if the SMS was sent to the contact |
message | String | (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:
For example, here's the link for Pod 1 organizations that use a US data center:
Updated over 1 year ago