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 the start and end times are not defined, the operation returns data for the specific program only for "today".

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:

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 100 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.