Use the Gateway API 2.0 to trigger SMS messages from an external system, completely bypassing your Watson Campaign Automation organization.
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.
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 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.
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. |
| 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
<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.”
Test your SMS API call
For information on how to test your SMS API call, click here.