Message API - Upgrade from gateway

Introduction

On July 1st, 2016, we released a new version of our Message API and deprecated the previous (SMS Gateway v2). The Message API has been redesigned from the ground up to provide a cleaner and more consistent way to send and receive messages. It also integrates a set of new features that were not supported by the previous version.

This document aims at helping developers to migrate from the SMS Gateway v2 to the new Message API.

If you need help or have questions about it, please send us an email to support@ringring.be .

First steps

The new version of the API dropped the use of Public and Standard Gateways, the IP whitelisting is configurable via the web interface of the Message API.

You will find a quick start guide to create your first application here. Once you have an application setup, you will have to change different parameters of your web requests.

Note that the new Message API is fully supporting JSON and XML. As this guide is written for migrating from older SMS Gateway using XML, we will focus here only on XML. More....

Sending SMS

First of all, you will have to change the URL from https://gateway.ringring.be/MT/MTService.asmx/sendMT or https://publicgateway.ringring.be/MT/MTService.asmx/sendMT to https://api.ringring.be/sms/V1/Message/

(Please note that starting January 2019 only protocols TLS1.1 and TLS1.2 are going to be supported. Please make sure you are using one of these. If you need to change the protocol you use, we recommend you to use TLS1.2)

You can also use https://api.ringring.be/sms/sandbox/Message/ instead if you wish to do some testing first without sending any real messages, in old SMS Gateway 1 was used to test the SMS Gateway without sending real messages. With the new Message API, all services can be tested in sandbox mode.

Changing the XML posted to the API

SMS Gateway XML

<GW_SMS_MT>
 <INFO>
   <Reference>reference001</Reference>
  </INFO>
  <MT>
    <Message>my first message by ringring</Message>
    <Shortcode>8686</Shortcode>
    <Msisdn>32485123456</Msisdn>
  </MT>
  <SESSION>
    <Login>MyLogin</Login>
    <Password>MyPassword</Password>
    <AppId>17</AppId>
  </SESSION>
</GW_SMS_MT>

Message API XML

<MessageRequest>
  <ApiKey>MY-API-KEY</ApiKey>
  <To>32485123456</To>
  <Message>my first message by ringring</Message>
</MessageRequest>

MO Gateway and how to receive incoming Messages

If you were using an MO gateway to receive Incoming Messages, you can now set it up yourself. By going to the application settings and enter an URL, choose the way you want to receive incoming messages as described in the applications settings page.

However, New Message API adds a new way to get incoming Messages (MO). You can now pull a service that will retrieve the latest incoming messages. Be sure to check out here.

Here is the structure of an old XML for an MO and the new XML:

SMS Gateway Incoming

xml=<?xml version="1.0"?>
<GW_SMS_MO>
  <MO>
    <InboxId>555555</InboxId>
    <MSISDN>32485123456</MSISDN>
    <Shortcode>8686</Shortcode>
    <Message>This is a test MO</Message>
    <Timestamp>2016/03/03 15:00:00</Timestamp>
    <ProviderId>1</ProviderId>
    <isRealMo>true</isRealMo>
  </MO>
  <INFO>
    <AppId>55555</AppId>
    <CustomerId>55555</CustomerId>
  </INFO>
</GW_SMS_MO>

Message API Incoming

<?xml version="1.0" encoding="UTF-8"?>
<IncomingResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <NumberOfRecords>1</NumberOfRecords>
   <RemainingRecords>0</RemainingRecords>
   <IncomingMessages>
      <IncomingMessage>
         <MessageId>UNIQUE-MESSAGE-ID</MessageId>
         <From>32485123456</From>
         <To>8689</To>
         <Message>This is a test MO</Message>
         <Country>BE</Country>
         <TimeReceived>2016/03/03 15:00:00</TimeReceived>
      </IncomingMessage>
   </IncomingMessages>
   <ResultCode>0</ResultCode>
   <ResultDescription>Success</ResultDescription>
</IncomingResponse>

As you can see, the XML is now simplified and an MO can be send with a minimal amount of information.

All the information that used be in the session part of the xml is now behind the scene and linked to your API key.

DLR Gateway and how to receive SMS Delivery notifications

If you are using an DLR gateway to receive Delivery Notifications (Status), you can now set it up yourself. By going to the application settings and enter an URL, choose the way you want to receive incoming messages as described in the applications settings page.

However, New Message API adds a new way to get Status Messages (DLR). You can now pull a service that will retrieve the latest status of messages or you can use the unique Message Identifier to retrieve a specific Message Status . Be sure to check out here. And here is a comparison between an old DLR XML and a new Message API :

SMS Gateway DLR

xml=<?xml version="1.0"?>
<GW_SMS_DLR  xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:noNamespaceSchemaLocation="http://interactive.ringring.be/public/XMLschema/smsgatewaystd/GW_SMS_DLR.xsd">
  <DLR>
    <OutboxId>256782</OutboxId>
    <Reference>001</Reference>
    <MessageStatus>200</MessageStatus>
    <DeliveryTime>2015-09-30 16:45:00.789</DeliveryTime>
  </DLR>
  <INFO>
    <AppId>340</AppId>
    <CustomerId>185</CustomerId>
  </INFO>
</GW_SMS_DLR>

Message API DLR

<?xml version="1.0" encoding="UTF-8"?>
<StatusMessageResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <MessageId>10-11-12-13-14</MessageId>
   <StatusCode>200</StatusCode>
   <StatusDescription>Delivered</StatusDescription>
   <TimeSubmitted>2016/03/03 13:55:03</TimeSubmitted>
   <DeliveryTime>2016/03/03 13:55:00</DeliveryTime>
   <Country>BE</Country>
   <To>32485123456</To>
   <ResultCode>0</ResultCode>
   <ResultDescription>Success</ResultDescription>
   <Message>my message</Message>
</StatusMessageResponse>

Supervisor

The Supervisor is fully rebranded and provides more additional features, it's included in the Message API web interface available from the [RingRing's Portal] (https://portal.ringring.be)

New features

Many other new features have been introduced in Message API since SMS Gateway v2. Be sure to check them out in the documentation. Here are some examples of features that might be helpful to you:

  • Full sandbox environment available for all services
  • You can cancel a scheduled Message through the Cancel service
  • You can get the status of your messages by using the status and statusmessage services
  • You can setup Time Windows to protect yourself from sending messages outside defined business hours
  • The Gateway Supervisor is replaced by a new powerful interface
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.