Overview

Skill Level: Intermediate

Prerequisites

Before using SMS APIs, first obtain SMS API credentials and get familiar with common SMS API use cases. You can also view common REST APIs used for SMS messages.

Obtaining SMS API credentials

You must have the appropriate authorization credentials to make SMS API calls. Provisioning will request a username and password on your behalf. You will receive an email notification with the username and password credentials from our SMS partner.

Note:   

 The email notification from our partner may contain additional information. This information is not applicable to your SMS setup—you only need the username and password to make the SMS API calls listed below.

  

If you do not have SMS API access, contact Client Support.

Common use cases for SMS APIs

I want to…  Reference the following article(s) 
 Send SMS messages to an external system Use the Gateway API to Send SMS Messages from an External System
 Send a virtual MO to an SMS Program Use WebMO API to send a virtual MO to an SMS Program
 Export messages from the SMS Campaign Manager  Export SMS Messages API from the SMS Campaign Manager
 Get published messages from the Watson Campaign Automation REST API to get published messages from the Watson Campaign Automation
 Send messages to a contact source REST API to send SMS to Contact Source
 Send transactional SMS messages to input contacts having SMS consent managed in Watson Campaign Automation REST API Transactional SMS API
 Use transactional SMS messages to input contacts having SMS consent managed outside Watson Campaign Automation REST API SMS External Consent
 Test REST API calls See Swagger. Paste the following URL in your browser.https://apix.silverpop.com/restdoc, where x is your pod number.
 Test SMS APIs that terminate at https://communicatepro.mgage.com See Test your SMS API Call

REST APIs for SMS messages

Go to the REST API Methods topic to get a complete list of REST APIs, some of which can be used for SMS messages.

Here’s a list of common SMS REST APIs:

Step-by-step

  1. Exporting SMS messages from the SMS Campaign Manager using a REST API

    Through the use of REST API, you can export sent/received SMS messages from the SMS Campaign Manager to an external system.

    Overview

    You can retrieve all SMS messages up to one year duration. This REST operation returns all SMS based on specified Program ID. Additionally, you can filter the results using the following filters:

    • Message Type (MT, MO or both)
    • Date Range (using Start / End Dates)
    Note: If you have a need to retrieve SMS messages older than one year, please contact Client Support to retrieve the requested messages from archived data and provide the results.         

     

    See the View SMS Message Reporting article to learn how to view SMS inbound and outbound transactions in the SMS Campaign Manager.

    Before you Begin

    Before you can make API calls, you’ll need the following:

    Authentication

    This operation uses HTTP Basic authentication that you should have received from Provisioning. If you do not have these credentials, contact Client Support and open a case with Provisioning.

    See Use SMS API for details.

    Request URL

    https://communicatepro.mgage.com/api/messages/program/{programId}

    Filters (Optional)

    Optionally, you can specify filters in the Request URL to control the data that is returned:

    Filter Data Tyep Description
    messageType (String)  Message Type, MO, or MT. If not specified, the system will return both MO and MT.
    startDate DateTime  

    Return data using this as Message received/sent start date. If this is not specified, the system will use the first message received/sent (up to 1 year ago) as the startDate.

    The DateTime format is YYYY-MM-DDTHH:MM:SS.

    endDate DateTime  

    Return data using this as Message received/sent end date. If this is not specified, then the system will use the last message received/sent as the endDate.

    The DateTime format is YYYY-MM-DDTHH:MM:SS.

    pageSize Numeric Specify the size of the Page for response data. Max page size is 500 SMS messages. The default page size is 50 messages.

    Example

    The following API call exports SMS Messages to an external system, using filters for a specific program, startDate, endDate, and
    pageSize.

    GET

    https://communicatepro.mgage.com/api/messages/program/121811?filter=startDate=2015-03-12T12:00:00;endDate=2015-03-14T12:00:00;pageSize=5

    Response Specification

    This section includes the API response specification, as well as an example.

    Note: Although the default page size is 50 messages, you can specify pageSize up to 500 messages per page. If there are multiple pages, the response will contain the URL of the next page of data.

     

    {
    'meta':
    {generalErrors: An array of errors that happened while processing the request, nextPageUrl: If there are multiple pages of data then the 'nextPageUrl' property of the RestResponse.Meta object should be set to the URL of the next page of data. If there isn't another page of data available then this property should be left null.
    },
    'data':
    {
    'campaignName': (String) Campaign Name,
    'programName': (String) Program Name,
    'programType': (String) Program Type,
    'messages':[
    {
    'type': (String) Message Type, MO or MT. (If omitted, then it implies both MO and MT),
    'deliveryStatus': (String) Message Delivery Status (Possible values for Message Delivery Status will be the same as what's shown in the Message Reports in SMS Campaign Manager),
    'number': (Numeric) Mobile Number,
    'body': (String) This is a SMS Body,
    'date': (DateTime) Message Sent/Received Date returned in GMT in ISO-8601 format (for example: 2012-05-08T11:56:05),
    'network':(String) Carrier Network of Mobile if available, otherwise null,
    },
    ] }

    Example of a Successful Response

    { 
    "meta":{
    "generalErrors":[

    ],
    "nextPageUrl":"https://communicatepro.mgage.com/api/messages/program/121811?page=2"
    },
    "data":{
    "campaignName":"Default Campaign",
    "programName":"Program Name",
    "programType":"Text to Join",
    "messages":[
    {
    "type":"MO",
    "deliveryStatus":"Received",
    "number":"1234567890",
    "body":"This is complete message Body",
    "date":"2014-12-05T10:00:00.00",
    "network":"T-Mobile"
    },
    {
    "type":"MO",
    "deliveryStatus":"Received",
    "number":"15556667777",
    "body":"This is complete message Body",
    "date":"2014-12-05T10:00:00.00",
    "network":"T-Mobile"
    }
    ] }
    }

    Error Handling

    The HTTP response code should be used to determine the success of your call. The following table includes the standard HTTP response codes:

    Note: In the case of a 40x/50x error, you can find the details of what went wrong under the ‘meta’ key of the response. 

     

    Response Code    Description 
    200   Successful call
    40x   Failure to due user (client) error
      400  Returned when there is some syntactical error in the request such as invalid/misformatted data
      404 When requested resource does not exist
    50x   Failure due to server error
      500 General server exception

    Testing your SMS API Call

    How to use Google Chrome browser’s Postman web application to test your SMS API calls.

    Note: This test is applicable for the APIs calls in the following articles:   

    Requirements

    • Install a REST client, such as PostMan, found in the Chrome web store. IBM does not endorse a particular tool. Before using a tool, make sure that you read the terms and conditions.
    • Along with Provisioning, complete the API user setup.
    • You have the SMS API authentication username and password of the API user. Tomake SMS API calls, Provisioning requests a username and password on your behalf. You will receive an email notification with the username and password credentials from our SMS partner.
    • Open a new Chrome browser (that is not logged into the SMS Campaign Manager).

    Procedure

    Complete the following steps to test any SMS API call.

    Note: This example uses the Gateway API call. 
    1.  Launch Postman in Chrome.
    2. Click Basic Auth.
    3. With the credentials you received via email from our SMS partner, type the Username and Password.
    4. Click the Refresh Headers button to generate the Basic Auth token.
    5. Construct your request URL. Here’s an example, using the Gateway API: https://communicatepro.mgage.com/api/gateway?message=Testing the API Gateway for SMS 2.0&message_billed=no&message_type=sms&numbers=17277539473&spoof_from=39771&program_id=109714
    6. Make sure the selection next to the URL params button is POST.
    7. Paste the request URL into the Enter request URL here field, located above Authorization. You can click URL params to see all of the parameters and the values passed over, based on the Request URL entered, and verify these parameters.
    8. Click Send. You should see a 200 response.

    /*Code Goes Here*/

    The SMS platform is very quick, and the message should arrive in the SMS Phone Number’s inbox within a second or two.

  2. Using the Gateway API to send SMS messages from an external system

    Use the Gateway API 2.0 to trigger SMS messages from an external system, completely bypassing their Watson Campaign Automation organization.

    Usage

    You can create use cases around transactional SMS messages, SMS reminders, or any type of SMS messages that are generated from client systems.

    Note: We recommend that you use the External SMS Consent REST API or the Transactional SMS API to send messages from an external system.
    However, customers who currently send messages using the Gateway API, which is not an XML or REST API, may continue to do so. The Gateway API is invoked with POST method and contains required parameters in a query string.

    Before you Begin

    Before you can make Gateway API calls, you’ll need the following:

    Considerations

    There are few things to note when using the Gateway API 2.0:

    • SMS consent information is not stored in Watson Campaign Automation.
    • It is your responsibility to collect opt-ins and manage consent (on-going steady state opt-in and opt-out). You can export the opt-out messages directly from the SMS Campaign Manager UI.
    • You can batch up to 250 numbers in a single API call – one SMS message body (same content) to up to 250 mobile numbers.
    • SMS Campaign Manager will not trigger Universal Behavior events to Watson Campaign Automation for MT messages sent directly via Gateway API if the record contains a valid phone number in the SMS Phone Number field.
    • UK instance users have a different request format that uses ‘-uk’ in the URL. See the Request Format section below for details.

    Authentication

    This operation uses HTTP Basic authentication that you should have received from Provisioning. If you do not have these credentials, go to the Support Portal and open a case with Provisioning.

    See Use SMS API for details.

    Request Format

    SMS Campaign Manager Hosted in USA

    This is the default request format for all SMS Campaign Manager users, unless you have been informed that your SMS Campaign Manager is hosted in the
    UK.

    https://communicatepro.mgage.com/api/gateway?message={SMSMessage}&message_billed=no&message_type=sms&numbers={PhoneNumber}&spoof_from={Code/SenderId}&program_id={Text”>https://communicatepro.mgage.com/api/gateway?message={SMSMessage}&message_billed=no&message_type=sms&numbers={PhoneNumber}&spoof_from={Code/SenderId}&program_id={Text to Join Program Id}

    SMS Campaign Manager hosted in UK

    https://communicatepro-uk.mgage.com/api/gateway?message={SMSMessage}&message_billed=no&message_type=sms&numbers={PhoneNumber}&spoof_from={Code/SenderId}&program_id={Text”>https://communicatepro-uk.mgage.com/api/gateway?message={SMSMessage}&message_billed=no&message_type=sms&numbers={PhoneNumber}&spoof_from={Code/SenderId}&program_id={Text to Join Program Id}

    HTTP Method

    POST

    Authentication Method (Header)

    HTTP Basic

    Request Parameters

    All API parameters must be URL encoded.

    Parameter  Description
     allow_long_messages  

    Optional field. This field specifies whether the message is intended to exceed 160 characters. Set the value of this field to ‘no’ if the message should not exceed 160 characters. Set the value to ‘yes’ if the message may exceed 160 characters. When not specified, the gateway assumes ‘no’ as the specified value.

    For carriers and mobile handsets supporting concatenation SMS, the message text is shown as one long SMS message. If carriers and/or the mobile handset do not support concatenation SMS, then this may result in multi-part messages.

    The client is responsible for payment of each multi-part message for message size exceeding 160 chars that is split into multiple SMS messages during the delivery.

    message This is the content of the SMS message.
    message_billed Set this to ‘no’.
    message_type Set this to ‘sms’.
    numbers This is a list of destination mobile numbers separated by commas. Can be batched up to 250 unique numbers. Mobile numbers may not contain any non-numeric characters and must include the country code, for example a US mobile number would be passed as 12135551234.
    program_id Text To Join Program Id. The client must create a Text To Join program (shell), obtain the Program Id from SMS Campaign Manager and pass that value in the API call. 
    spoof_from This represents the “from” number (originator of the SMS) mobile recipients see on their handsets. You can get this value from the Text to Join Program info. In most cases this will be the code (short code or long code), for example 87767.

    Response Format

    <piri_proto_v2>

    <server_response>

    <type>Either “error” or “success” Error means the request was badly formed.</type>
    <description>A description of any problem with the request These may change. </description>
    <code> A numeric error code, or 0 on success.</code>
    <processed_numbers>Count of the numbers the platform accepted.</processed_numbers>

    </server_response>
    <recipients>The following recipient block will repeat for each number that you sent to:

    <recipient>

    <number>The number to which you attempted to send.</number>
    <message_id>A unique ID generated by mGage to identify the message you sent. This is set to 0 if no message was sent.</message_id>
    <errorcode>The error code returned if something went wrong. 0 is returned on success.</errorcode>
    <description>A plain text description of any error.</description>

    </recipient>

    </recipients>
    </piri_proto_v2>

    Example Sample Request

    Header

    Authorization: Basic 123xyz456abc789mno

    POST

    https://communicatepro.mgage.com/api/gateway?message_id=xyz123&message=This is where you type the content of your SMS message. If you allow long messages, you can enter more than 160 characters&message_billed=no&message_type=sms&numbers=1555796383&spoof_from=US- 35465&program_id=104967&allow_long_messages=yes

    <?xml version="1.0" encoding="UTF-8"?>
    <piri_proto_v2 xmlns="http://cmpro.air2web.com/api">
    <server_response>
    <status>success</status>
    <code>0</code>
    <processed_numbers>1</processed_numbers>
    <description>Request accepted onto the platform.</description>
    <message_id>xyz123</message_id>
    </server_response>
    <recipients>
    <recipient>
    <number>15559796383</number>
    <message_id>0ad9b64c-fff8-4f9c-9a34-88a83ee5870c</message_id>
    <errorcode>0</errorcode>
    </recipient>
    </recipients>
    </piri_proto_v2>

    Successful Response

    Status Codes

    0: “Request accepted onto the platform.”

    1: “Send failed. Please contact support.”

    104: “Invalid message type: ‘{0}’”

    105: “Country code not valid – currently supported country codes are: ‘US’ or ‘UK’, supplied:
    ‘{0}’”

    106: “Message billed not set correctly – should be “yes” or “no”.”

    107: “Too many characters in message – should be < 160, found {0}.”

    108: “Message must not be empty.”

    109: “You must specify at least one recipient.”

    111: “No valid numbers to send to!”

    112: “Too many numbers in request – max. {0}, received: {1}.”

    113: “Number found twice in request – please only supply each number once per request!”

    114: “Parameter allow_long_messages not set correctly – should be “yes” or “no”.”

    201: “Spoof must be set when sending unbilled messages.”

    Use Case

    A good use case to reference is Using API to add or update profile information.

  3. Using the WebMO API to send a virtual MO to an SMS Program

    The WebMO API allows an external system to send a virtual mobile-originated (MO) message to an SMS Program in the SMS Campaign Manager.

    Note: This WebMO API is not an XML or REST API. It is invoked with POST method and contains required parameters in a query string.

    Usage

    You can use this API to:

    • enter a mobile user into a Multi-Step Program to trigger a Double Opt-in Confirmation
    • opt-in to and opt-out from a Text to Join program

    Before you Begin

    Before you can make API calls, you’ll need the following:

    Authentication

    This operation uses HTTP Basic authentication that you should have received from Provisioning. If you do not have these credentials, go to the Support Portal and open a case with Provisioning.

    See Use SMS API for details.

    End Point

    https://communicatepro.mgage.com/api/externalMO

    Headers

    Authorization: Basic {token}

    Example

    POST

    https://communicatepro.mgage.com/api/externalMO?campid=108140&destination=US-87767&originator=19495724511&message=OAlerts

    Parameters

    Parameter  Description 
    campid Program ID number for an SMS program.
    destination

    Field that contains the short code associated with the interactive program.

    Valid Format: US-37911, UK-87658 etc.

    originator The mobile number entered into the program.
    message The content of the text message. When forwarding a contact into an interactive program, this field is used as the virtual MO to enter them into a session-in this case, a Keyword configured for the interactive program.

Join The Discussion

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