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.

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

Join The Discussion

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