mGage Gateway API

Usage

You can create this API to send transactional SMS messages, SMS reminders, or any type of SMS messages that are generated from external 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:

Get the SMS Program ID from the SMS Campaign Manager.
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.

Considerations

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

SMS consent information is not stored in Acoustic Campaign.
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 Acoustic Campaign 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.

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_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_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. Note: The Mgage Text To Join Program ID appears in the URL when you open the Text to Join program.
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

The following recipient block will repeat for each number that you sent to:

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

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