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 Watson Campaign Automation 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

  1. Your Watson Campaign Automation org must have SMS enabled by provisioning.
  2. A database in your Watson Campaign Automation 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

Attribute: Content

Description: SMS message body, string, required

Example: Hello %%FIRST NAME%%!! Happy birthday!

Attribute: Contacts

Description: List of contacts who will be sent the SMS message (max 1000 contacts per call), array, required

Example: Use Contact ID or Contact Lookup

Attribute: Contact ID

Description: SMS phone number for the contact (must include country code), long, optional

Example: 19495001234

Attribute: Contact Lookup

Description: Provide a field name, value and channel to lookup the contact, array, optional

Example: Mobile number, 12015557778, SMS

Attribute: Personalization

Description: Map of key value pairs for personalization, map, optional

Example: Tracking: Z12A34567

Attribute: Channel Qualifier

Description: SMS program ID. See How to find SMS program ID., string, required

Example: 12345

Attribute: Personalization Defaults

Description: Value to return if personalization data is not found for a contact., map, optional

Example: FIRST NAME: Valued Customer

Attribute: Source

Description: Attribute returned as part of the Universal Behavior event., string, optional

Example: 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
}

Check Status of SMS Sent using the Transactional SMS API

SMS messages sent using the Transactional SMS API will not appear in the Watson Campaign Automation 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 Org, replace {POD#} with the Pod where your Org exists:

https://api{POD#}.silverpop.com/restdoc/#!/channels/sms_to_contacts_post_1

 

For example, here’s the link to use if your Org is on Pod 1:

https://api1.silverpop.com/restdoc/#!/channels/sms_to_contacts_post_1

Join The Discussion

Your email address will not be published. Required fields are marked *