How it Works
The SMS External Consent REST API allows the user to send transactional SMS messages to contacts who might or might not be in the Watson Campaign Automation SMS database.
Use Case
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
- Your Watson Campaign Automation org must have SMS enabled by provisioning.
- A database in your Watson Campaign Automation 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.
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 Watson Campaign Automation 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
|
Attribute: Content Description: Content for SMS, string, required Example: Hey %%FIRST NAME%%! Happy birthday!! |
|
Attribute: Contacts Description: List of contacts (Phone Number must include Country Code). API accepts max 1000 contacts, array, required Example: Use Contact ID or Contact Lookup |
|
Attribute: Channel Qualifier Description: 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 |
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
| 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 |
Check Status of SMS Sent using the SMS External Consent API
SMS messages sent using the External Consent 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 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
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
I had a client ask a question about additional elements that can be used in this call…
does the API handle the legal times of a day to send the SMS messages? I think the law (our legal team found) states between 8 AM and 9 PM of the recipient’s time zone is the timeframe you can send SMS messages?
Hi Thomas,
I’ve reached out to the PA on this one to confirm information. I’ll get back to you via email.
Thank you
Jeri
Hi Thomas,
Sorry for delayed answer as I had not seen your question earlier. All messages sent using the above API are sent immediately. There is not Time of Day window associated with the above API.