Documentation

Version 2 - batching api

Our revised API that allows you to track individual messages and send several messages at the same time thus lowering down the overall resource usage and bandwidth.

Simple MT example:

POST /api/v2/sendsms/<account_id>/
{
    "api_key"  : "<api_key>",
    "messages" : [
   {
        "from"  : "1900",
        "to"    : "233501100100",
        "text"  : "This is our great welcome message",
        "reference" : "<your custom provided reference>"
      }]
}

Produces a single message and responds with Mobivate message reference id. For all messages in the payload

{
    "messages" : [
   {
        "id" : "MT-cf3aa273ea6d4b3f833eeca8f66be5b0",
        "status" : 0,
        "to" : "233501100100"
      }
    ]
}

Batch example

As mentioned before this API mostly allows you to send multiple messages in one batch. Lets see an example and walk through it.

POST /api/v2/sendsms/<account_id>/
  {
    "api_key"  : "<api_key>",
    "reference" : "<optional user reference for whole batch>",
    "reference_type": "<batch | message>"
    "messages" : [
   {
        "from"  : "1900",
        "to"    : "233501100100",
        "text"  : "This is our great welcome message"
      },{
        "from"  : "221155",
        "to"    : ["447472555488", "447472555466", "447472555455"],
        "text"  : "This is same message for multiple recipients",
      },{
        "from"    : "447788",
        "keyword" : "BLAH:23309990000011111",
        "cost"    :  2000,
        "country" : "UK",
        "message_class" : "PAUSE",
        "to" : [
          {
            "to"          : "44789000111",
            "reference"   : "5ce358a8-5ed0-46e2-8a3b-638f5db876c8",
            "provider"    : "o2uk"
          },{
            "to"          : "447471000222",
            "reference"   : "eb27b6cc-08f6-40dd-a6f5-61472278de8d",
            "provider"    : "threeuk"
          }
        ],
        "text"    : "This is a billed message"
      }
    ]
  }

In the example above you can see, that you can either describe your messages in list completely or you can join the fields that are similar for all the messages and just put what varies in to field. the example above would produce the following messages.

ORIGINATORDESTINATIONMESSAGE
1900233501100100This is our great welcome message
221155447472555488This is same message for multiple recipients
221155447472555466This is same message for multiple recipients
221155447472555455This is same message for multiple recipients
44778844789000111This is a billed message
447788447471000222This is a billed message

Upon sending we also check for duplicate sends due to network errors. If you specify the reference field for the whole payload and reference_type = 'batch' we than check if the whole request was sent in the last few minutes, in case you specify the reference_type = 'message' we check individual messages for duplicity.

Please note that the maximum number of messages per one batch is 100.

Payload parameters

ParameterRequiredToDescription
api_keyYesNoYour API key, if migrating from older API it is called PASSWORD
referenceNoNoCustom identification of the batch of messages in this request, if omitted, it would be calculated as a hash of the payload.
reference_typeNoNo(batch/message) specifies if the whole batch if checked for duplicates or individual messages
messagesYesNoContains the payloads of the messages
fromYesNoFormerly known as ORIGINATOR, its the sender of the message (shortcode)
toYesYesFormerly DESTINATION. Can contain either a string with the recipients msisdn (phone number in international format), list of msisdns or list of JSON objects describing the different fields for individual messages. (column To in this table)
textYesYesThe text content of the message. Formerly MESSAGE_TEXT
referenceNoYesYour custom client reference to identify the message
providerNoYesThe network provider for premium messages, or default for other
valueNoYesSpecifies the value of a Premium SMS message, in cents (this applies to all currencies). To be used only in conjunction with the PROVIDER field. For example: 300 à $3.00 250 à $2.50
startedYes in Kenya and South AfricaYesContains the date of when the Subscription first started (YYYY-MM-DD HH:MM:SS)
keywordYes in Kenya, South Africa and UKYesContains the product id (on the network side) to which the subscriber was subscribed. See Keyword Requirements below
countryNo, but recommendedYesThe ISO-2 code for the country of the recipient. Although not required and we try to detect the number from the msisdn, we suggest you provide it if you know it.
dr_endpointNoThe individual URL that the notification should be sent to. We still suggest using a globaly defined DR endpoint. This one overrides it

The Keyword parameter in Kenya must be as follows productid:serviceid. Product ID and Service ID are given to you after the service is provisioned with the networks in Kenya

Keyword requirements : South Africa

The Keyword parameter in South Africa must be as follows productid. Product ID is given to you after the service is provisioned with the networks in South Africa.

Keyword requirements : UK

The Keyword parameter in UK must be as follows campaignid. Campaign ID is given to you after the service is provisioned with the networks in UK.


Response

For correct request there would be text/json response from our server containing our internal message reference, so that you can map it to your reference. Our reference is always 35 character long consisting of MT- and 32 hexadecimal numbers. Bellow is a response for the batch example request above.

{
    "reference": "batch_reference",
    "messages" : [
   {
        "id" : "MT-a872632f053c444da416643687d51822",
        "status" : 0,
        "to" : "233501100100"
      },{
        "id" : "MT-773e05646dcd478aac2a04460614081c",
        "status" : 0,
        "to" : "447472555488"
      },{
        "id" : "MT-e774a8c683f34ee5a144dbc6f00dcdbc",
        "status" : 0,
        "to" : "447472555466"
      },{
        "id" : "MT-18500e8264184cd7affc71c1d615a855",
        "status" : 529,
        "to" : "447472555455"
      },{
        "id" : "MT-ffaa59cfb78b47688e70cb040419a5a0",
        "status" : 0,
        "to" : "44789000111",
        "reference" : "5ce358a8-5ed0-46e2-8a3b-638f5db876c8"
      },{
        "id" : "MT-9a2d585f827549789e21bdc91f6a168b",
        "status" : 0,
        "to" : "447471000222",
        "reference" : "eb27b6cc-08f6-40dd-a6f5-61472278de8d"
      }
    ]
  }

Our response should always return data and some additional information in case we would need some debuging. Please note, that we provide our internal response codes for individual messages. Our API would also return different HTTP response codes in certain scenarious:

HTTP statusSituation
200Request went through fine. Individual statuses for messages will be found in response or sent via DR notification
403For status codes 511 and 512, unable to authenticate your request. Check your <account id> and <api_key>
400For statuses 506 and 531. Please always have a text field and post a valid JSON document
500Any other error. Please use this response and provide it to us when opening a issue ticket with us


Status querying

After we get status notifications from upstream we are forwarding those as DRs to clients. If you are missing some of these you can query them using our status query api. It is just a plain post of comma separated list of mobivate messate ids.

POST /api/msgstatus/<account_id>/
MT-9a2d585f827549789e21bdc91f6a168b,MT-18500e8264184cd7affc71c1d615a855

And as a response you would get:

{
    "MT-9a2d585f827549789e21bdc91f6a168b": "1",
    "MT-18500e8264184cd7affc71c1d615a855": "529"
}

Please note, however:

  • Maximum number of MT-ids is 1000 / request
  • Although we do not enforce currently any limit on the number of requests, we might in the future. Please do not exceed more 100 requests / hour.
  • It might take some time between us accepting it on the API and the information about status being available. In the first few seconds the message might appear missing.
  • Keep in mind, that the delivery of the message and the DR reaching our system might also take some time. It is pointless to query right after sending it.
  • Please avoid active polling, the normal flow is we send you a status using a DR callback.