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 a 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:

  • Get the SMS Program ID from the SMS Campaign Manager. Open the interactive program and in your browser address window, look for the program id at the end of the URL.
  • SMS API access. You must receive your SMS API authentication credentials from Provisioning.

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.

Authentication

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

Request URL

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

Filters (Optional)

You can specify filters in the Request URL to control the data that is returned:

Filter Data Type 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

Test Your SMS API Call

For information on how to test your SMS API call, click here.

Join The Discussion

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