SMS external consent REST API

The SMS External Consent REST API allows the user to send transactional SMS messages to contacts who might or might not be in the Acoustic Campaign SMS database.

This REST API allows sending transactional SMS messages to contacts and who might or might not have SMS consent in the SMS database. In this type of situation, consent is managed externally to the SMS database. Typical usage of this API, for example, sending a one-time security code for a password change to the user or air flight gate change.

Requirements to use this API

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

📘

Note:

This API supports inline personalization and does not check for consent nor does it resend if the SMS send fails.

Items of note

  • Contact does not have to be in the SMS database.
  • SMS phone number is added to the database. Adding the Contact to the Acoustic Campaign database allows to send Universal Behaviors, which enable Reporting.
  • Contacts can be cleared from the database by using the Purge feature. Run a Query on the CREATED_FROM field to identify contacts that are added by the SMS External Consent API.

Endpoint
/channels/sms/externalconsentsends

Parameters for SmsExternalConsentSendPayload

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.

Parameters for SmsExternalConsentContact

Attribute: Phone Number
Description: Phone Number with Country Code of the Contact from List, string, required
Example: 19495001234

Attribute: Personalization
Description: Map of key value pairs for personalization, map, optional
Example: Tracking: Z12A34567

Sample Payload

{ “content”:”Hello. Here is the PIN you requested %%PIN%%.”, “contacts”:[ { “phoneNumber”:”19492319304″, “personalization”:{ “PIN”:”1234″ } } ], “channelQualifier”:”129856″, “source”:”” }

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

Check Status of SMS Sent using the SMS External Consent API

SMS messages sent using the External Consent API will not appear in the Acoustic 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 External Consent 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: ID generated from the Response Body of the SMS External Consent REST API call
Description: A transaction id returned by POST /channels/sms/sends, string, required
Example: 6adb75b2-158df6e11e8-fe154a13e7aff661200edcf73

Sample Response Body

{
  “meta”: {
    “attributes”: {},
    “generalErrors”: [],
    “fieldErrors”: {},
    “links”: [],
    “nextPageUrl”: null
  },
  “data”: {
    “totalContacts”: 2,
    “contactsProcessed”: 2,
    “contactStatus”: [
      {
        “smsSent”: false,
        “message”: “Invalid phone number.”,
        “phoneNumber”: “1×833920903”
      },
      {
        “smsSent”: true,
        “phoneNumber”: “19492319304”
      }
    ],
    “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