API Documentation

Mobile Billing / Premium SMS / V2 Batch API (beta)

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.

ORIGINATOR DESTINATION MESSAGE
1900 233501100100 This is our great welcome message
221155 447472555488 This is same message for multiple recipients
221155 447472555466 This is same message for multiple recipients
221155 447472555455 This is same message for multiple recipients
447788 44789000111 This is a billed message
447788 447471000222 This 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

Parameter Required To Description
api_key Yes No Your API key, if migrating from older API it is called PASSWORD
reference No No Custom identification of the batch of messages in this request, if omitted, it would be calculated as a hash of the payload.
reference_type No No (batch/message) specifies if the whole batch if checked for duplicates or individual messages
messages Yes No Contains the payloads of the messages
from Yes No Formerly known as ORIGINATOR, its the sender of the message (shortcode)
to Yes Yes Formerly 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)
text Yes Yes The text content of the message. Formerly MESSAGE_TEXT
reference No Yes Your custom client reference to identify the message
provider No Yes The network provider for premium messages, or default for other
value No Yes Specifies 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
started Yes in Kenya and South Africa Yes Contains the date of when the Subscription first started (YYYY-MM-DD HH:MM:SS)
keyword Yes in Kenya, South Africa and UK Yes Contains the product id (on the network side) to which the subscriber was subscribed. See Keyword Requirements below
country No, but recommended Yes The 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_endpoint No The individual URL that the notification should be sent to. We still suggest using a globaly defined DR endpoint. This one overrides it

Keyword requirements : Kenya

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 status Situation
200 Request went through fine. Individual statuses for messages will be found in response or sent via DR notification
403 For status codes 511 and 512, unable to authenticate your request. Check your <account id> and <api_key>
400 For statuses 506 and 531. Please always have a text field and post a valid JSON document
500 Any 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 amount 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 sime time. It is pointless to query right after sending.
  • Please avoid active polling, the normal flow is we send you a status using a DR callback.

← Previous Page - Next Page →