Introduction

The MessageBird API connects your website or application to operators around the world. With our API you can integrate SMS & Voice.

The MessageBird API uses HTTP verbs and a RESTful endpoint structure. An access key is used as the API Authorization framework. Request and response payloads are formatted as JSON (although we provide a GET alternative for requests).

To use this API you need an account on MessagBird.com and an access key, which can be created in your account.

MessageBird provides the creation of test keys to discover and test the API at your own convienence. The difference between a live key and a test key is that a live key actual sends a message, while a test key does not. However, when you send a message using a test key, you will get a fake created object back.

API endpoint

https://rest.messagebird.com/

IP-address

Our API uses a CDN (Content Delivery Network). Hence you will not be able to whitelist requests to our platform.

Endpoint summary

/messages
/messages/{messageID}
/voicemessages
/voicemessages/{voiceMessageId}
/hlr
/hlr/{hlrId}
/balance

Previous versions

If you want to use one of our older API's, please see the old developers page.

Libraries

Currently we offer 6 pre-built libraries for our REST API. The libraries can be downloaded from our GitHub account.

Library examples

On this side of this documentation you will find examples your chosen language.

Authentication

With each API call, you will need to set request headers, including your access key to authenticate yourself.

Don't have an access key? Get an access key in the Developers menu in your account. There you can create test and live keys.

When your application can't send an Authorization header, you can use the GET parameter access_key to provide your access key.

We do not provide incoming request whitelisting on our platform for our REST API. All requests are forced SSL with an access key.

Parameters

Parameters
When calling our API, send your access key with the authentication type set as AccessKey (Example: Authorization: AccessKey {accessKey}). Required.
Accept
Set to application/json. Required.

cURL Example

$ curl https://rest.messagebird.com/balance \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Example (GET)

$ curl https://rest.messagebird.com/balance
?access_key=test_gshuPaZoeEG6ovbc8M79w0QyM

If possible, please use the Authorization header

PHP example

$MessageBird = new \MessageBird\Client('YOUR_ACCESS_KEY');

Ruby example

require 'messagebird'
client = MessageBird::Client.new('YOUR_ACCESS_KEY')

Go example

import messagebird "github.com/messagebird/go-rest-api"

func main() {
    client := messagebird.New("YOUR_ACCESS_KEY")
    // ...
}

C# example

const string YourAccessKey = "YOUR_ACCESS_KEY";
Client client = Client.CreateDefault(YourAccessKey);

Python example

import messagebird
client = messagebird.Client('YOUR_ACCESS_KEY')

Java example

import com.messagebird.MessageBirdClient;
import com.messagebird.MessageBirdService;
import com.messagebird.MessageBirdServiceImpl;

public class ExampleAuthenticate {

    public static void main() {
        // Create a MessageBirdService
        final MessageBirdService wsr = new MessageBirdServiceImpl("YOUR_ACCESS_KEY");

        // Add the service to the client
        final MessageBirdClient messageBirdClient = new MessageBirdClient(wsr);
    }
}

Errors

MessageBird uses standard HTTP status codes to indicate success or failure of an API request. Codes in the 2xx range indicate that a request was successfuly processed and codes in the 4xx range indicate that there was an error that resulted from the information sent (e.g. authentication, no balance or a missing or wrong parameter).

In case of an error, the body of the response includes a json formatted response that tells you exactly what is wrong.

Attributes

code
An integer that represents the error type.
descripton
A human-readable description of the error. You can provide your users with this information to indicate what they can do about the error.
parameter
The parameter in your request that is related to the error if the error is parameter specific.

HTTP status codes

200 Found: we found the request resource
201 Created: the resource is successfuly created
204 No Content: the requested resources is empty
401 Unauthorized: the access key was incorrect
404 Not found: the resources cannot be found
405 Method Not Allowed: the method is not allowed
422 Unprocessable Entity: the resource couldn't be created
5xx Something went wrong on our end, please try again.

Error codes

2  Request not allowed
9  Missing params
10 Invalid params
20 Not found
25 Not enough balance
98 API not found
99 Internal error

Error object example

{
  "errors":[
    {
      "code":2,
      "description":"Request not allowed (incorrect access_key)",
      "parameter":"access_key"
    }
  ]
}

Error handling

The error object will give you information about the occured error.

try {
  // Execute a MessageBird method
} catch (\MessageBird\Exceptions\AuthenticateException $e) {
  // Authentication failed. Is this a wrong access_key?

} catch (\MessageBird\Exceptions\BalanceException $e) {
  // That means that you are out of credits. Only called on creation of a object.

} catch (\Exception $e) {
  // Request failed. More information can be found in the body.

  // Echo's the error messages, split by a comma (,)
  echo $e->getMessage();
}
begin
  # Execute a MessageBird method

rescue MessageBird::ErrorException => ex
    # Request failed. More information can be found in the
    # ex.errors array.

    ex.errors.each { |error| puts error.inspect }
end
if err != nil {
  // messagebird.ErrResponse means custom JSON errors.
  if err == messagebird.ErrResponse {
    for _, mbError := range object.Errors {
      fmt.Printf("Error: %#v\n", mbError)
    }
  }

  return
}
try
{
    # Execute a MessageBird method
}
catch (ErrorException e)
{
    // Request failed.
    if (e.HasErrors)
    {
        foreach (Error error in e.Errors)
        {
            // error.Code, error.Description, error.Parameter
        }
    }
}
try:
    # Execute a MessageBird method
except messagebird.client.ErrorException as e:

    for error in e.errors: print(error.__dict__)
try {
  // Execute a MessageBird method
} catch (UnauthorizedException unauthorized) {
  if (unauthorized.getErrors() != null) {
    // Authentication failed. Is this a wrong access key?
    System.out.println(unauthorized.getErrors().toString());
  }
  unauthorized.printStackTrace();
} catch (GeneralException generalException) {
  if (generalException.getErrors() != null) {
      System.out.println(generalException.getErrors().toString());
  }
  generalException.printStackTrace();
}

Alternatives

The MessageBird API uses HTTP verbs to understand if you want to read (GET), delete (DELETE) or create (POST) an object. When your website or application doesn't have the possibility the do a POST or DELETE, we provide the ability to set the method through the query parameter _method.

Sequentially, resource arguments can be send through GET arguments instead of a JSON body.

Example

Sending a message:
/messages?_method=POST&msisdn=31612345678&...

Requesting an HLR:
/hlr?_method=POST&msisdn=31612345678&...

Messaging

MessageBird provides an API to send and receive SMS messages to and from any country across the world.

Messages are identified by a unique random ID. And with this ID you can always check the status of the message through the provided endpoint.

URI

https://rest.messagebird.com/messages

Available http methods

POST /messages
GET  /messages/{messageId}

The message object

This object represents a message at MessageBird.com

Attributes

attribute
type
description
id
string
An unique random ID which is created on the MessageBird platform and is returned upon creation of the object.
href
string
The URL of the created object.
direction
string
Tells you if the message is sent or received.
mt: mobile terminated (sent to mobile)
mo: mobile originated (received from mobile)
type
string
The type of message. Values can be: sms, binary, premium, or flash
originator
string
The sender of the message. This can be a telephone number (including country code) or an alphanumeric string. In case of an alphanumeric string, the maximum length is 11 characters.
body
string
The body of the SMS message.
reference
string
A client reference
validity
integer
The amount of seconds that the message is valid. If a message is not delivered within this time, the message will be discarded.
gateway
integer
The SMS route that is used to send the message.
typeDetails
hash
A hash with extra information. Is only used when a binary or premium message is sent.
datacoding
string
The datacoding used, can be plain or unicode
mclass
integer
Indicated the message type. 1 is a normal message, 0 is a flash message.
scheduledDatetime
datetime
The scheduled date and time of the message in RFC3339 format (Y-m-d\TH:i:sP)
createdDatetime
datetime
The date and time of the creation of the message in RFC3339 format (Y-m-d\TH:i:sP)
recipients
hash
The hash with recipient information. Further explanation in the table below.

The recipients array

attribute
type
description
totalCount
integer
The total count of recipients.
totalSentCount
integer
The count of recipients that have the message pending (status sent, and buffered).
totalDeliveredCount
integer
The count of recipients where the message is delivered (status delivered).
totalDeliveryFailedCount
integer
The count of recipients where the delivery has failed (status delivery_failed).
items
array
An array of recipient hashes
items[].recipient
integer
The msisdn of the recipient
items[].status
string
The status of the message sent to the recipient. Possible values: scheduled, sent, buffered, delivered, and delivery_failed
items[].statusDatetime
datetime
The datum time of the last status in RFC3339 format (Y-m-d\TH:i:sP)

Message object example (sms)

{
  "id":"e8077d803532c0b5937c639b60216938",
  "href":"https://rest.messagebird.com/messages/e8077d803532c0b5937c639b60216938",
  "direction":"mt",
  "type":"sms",
  "originator":"MessageBird",
  "body":"The message to be sent",
  "reference":"the-client-reference",
  "validity":null,
  "gateway":240,
  "typeDetails":{

  },
  "datacoding":"plain",
  "mclass":1,
  "scheduledDatetime":null,
  "createdDatetime":"2015-04-19T19:03:34+00:00",
  "recipients":{
    "totalCount":1,
    "totalSentCount":1,
    "totalDeliveredCount":0,
    "totalDeliveryFailedCount":0,
    "items":[
      {
        "recipient":31612345678,
        "status":"sent",
        "statusDatetime":"2015-04-19T19:03:34+00:00"
      }
    ]
  }
}

Message object example (binary)

{
  "id":"98154fa03532c2c3fc7b341b46487018",
  "href":"https://rest.messagebird.com/messages/98154fa03532c2c3fc7b341b46487018",
  "direction":"mt",
  "type":"binary",
  "originator":"MessageBird",
  "body":"546865206d65737361676520746f2062652073656e74",
  "reference":null,
  "validity":null,
  "gateway":240,
  "typeDetails":{
    "udh":"050003340201"
  },
  "datacoding":"plain",
  "mclass":1,
  "scheduledDatetime":null,
  "createdDatetime":"2015-04-19T19:03:34+00:00",
  "recipients":{
    "totalCount":2,
    "totalSentCount":1,
    "totalDeliveredCount":1,
    "totalDeliveryFailedCount":0,
    "items":[
      {
        "recipient":31612345678,
        "status":"sent",
        "statusDatetime":"2015-04-19T19:03:34+00:00"
      },
      {
        "recipient":31612345679,
        "status":"delivered",
        "statusDatetime":"2015-04-19T19:03:34+00:00"
      }
    ]
  }
}

Send a message

Creates a new message object. MessageBird returns the created message object with each request. Per request, a max of 50 recipients can be entered.

Required parameters

parameter
type
description
originator
string
The sender of the message. This can be a telephone number (including country code) or an alphanumeric string. In case of an alphanumeric string, the maximum length is 11 characters. Required
body
string
The body of the SMS message. Required
recipients
array
The array of recipients msisdn's. Required

Optional parameters

parameter
type
description
type
string
The type of message. Values can be: sms, binary, premium, or flash.
Default: sms
reference
string
A client reference
validity
integer
The amount of seconds that the message is valid. If a message is not delivered within this time, the message will be discarded.
gateway
integer
The SMS route that is used to send the message.
typeDetails
hash
An hash with extra information. Is only used when a binary or premium message is sent.
datacoding
string
The datacoding used, can be plain or unicode
Default: plain
mclass
integer
Indicated the message type. 1 is a normal message, 0 is a flash message.
Default: 1
scheduledDatetime
datetime
The scheduled date and time of the message in RFC3339 format (Y-m-d\TH:i:sP)

Returns

Returns a message object if the request was successful. If the request failed, an error object will be returned.

Definition

POST https://rest.messagebird.com/messages

cURL example request

$ curl -X POST https://rest.messagebird.com/messages \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
-d "recipients=31612345678" \
-d "originator=YourName" \
-d "body=This is a test message"

Do note that values are not automaticly urlencoded with the above example. Use --data-urlencode if you want to urlencode the values.

Example response

{
  "id":"e8077d803532c0b5937c639b60216938",
  "href":"https://rest.messagebird.com/messages/e8077d803532c0b5937c639b60216938",
  "direction":"mt",
  "type":"sms",
  "originator":"YourName",
  "body":"This is a test message",
  "reference":null,
  "validity":null,
  "gateway":null,
  "typeDetails":{

  },
  "datacoding":"plain",
  "mclass":1,
  "scheduledDatetime":null,
  "createdDatetime":"2015-04-19T19:03:34+00:00",
  "recipients":{
    "totalCount":1,
    "totalSentCount":1,
    "totalDeliveredCount":0,
    "totalDeliveryFailedCount":0,
    "items":[
      {
        "recipient":31612345678,
        "status":"sent",
        "statusDatetime":"2015-04-19T19:03:34+00:00"
      }
    ]
  }
}

PHP Example request

$MessageBird = new \MessageBird\Client('ACCESS_KEY');

$Message = new \MessageBird\Objects\Message();
$Message->originator = 'MessageBird';
$Message->recipients = array(31612345678);
$Message->body = 'This is a test message.';

$MessageBird->messages->create($Message);

Example response

{
  'id' => 'e60a6f90453a19019c56ed6b20170831',
  'href' => 'https://rest.messagebird.com/messages/e60a6f90453a19019c56ed6b20170831',
  'direction' => 'mt',
  'type' => 'sms',
  'originator' => 'MessageBird',
  'body' => 'This is a test message.',
  'reference' => NULL,
  'validity' => NULL,
  'gateway' => 240,
  'typeDetails' => {},
  'datacoding' => 'plain',
  'mclass' => 1,
  'scheduledDatetime' => NULL,
  'createdDatetime' => '2015-04-19T19:03:34+00:00',
  'recipients' => array(
    'totalCount' => 1,
    'totalSentCount' => 1,
    'totalDeliveredCount' => 0,
    'totalDeliveryFailedCount' => 0,
    'items' => array (
      {
        'recipient' => 31612345678,
        'status' => 'sent',
        'statusDatetime' => '2015-04-19T19:03:34+00:00',
      },
    )
  )
}

Ruby example request

client = MessageBird::Client.new(YOUR_ACCESS_KEY)
client.message_create('FromMe', '31612345678', 'Hello World', :reference => 'Foobar')

Example response

#<MessageBird::Message:0x007f8d5b883520
 @body="Hello World",
 @createdDatetime=2015-04-19 19:03:34 +0000,
 @datacoding="plain",
 @direction="mt",
 @gateway=239,
 @href=
  "https://rest.messagebird.com/messages/211e6280453ba746e8eeff7b12582146",
 @id="211e6280453ba746e8eeff7b12582146",
 @mclass=1,
 @originator="FromMe",
 @recipient=
  {"totalCount"=>1,
   "totalSentCount"=>1,
   "totalDeliveredCount"=>0,
   "totalDeliveryFailedCount"=>0,
   "items"=>
    [#<MessageBird::Recipient:0x007f8d5c058c00
      @recipient=31612345678,
      @status="sent",
      @statusDatetime=2015-04-19 19:03:34 +0000>]},
 @reference=nil,
 @scheduledDatetime=nil,
 @type="sms",
 @typeDetails={},
 @validity=nil>

Go example request

// The optional parameters.
params := &messagebird.MessageParams{Reference: "MyReference"}

message, err := client.NewMessage(
  "MyName",
  []string{"31612345678"},
  "Hello World",
  params)

Example response

&messagebird.Message{
    Id:"8ef55b60453c653f5794a87b46861030",
    HRef:"https://rest.messagebird.com/messages/8ef55b60453c653f5794a87b46861030",
    Direction:"mt",
    Type:"sms",
    Originator:"MyName",
    Body:"Hello World",
    Reference:"MyReference",
    Validity:"",
    Gateway:239,
    TypeDetails:map[string]interface {}{},
    DataCoding:"plain",
    MClass:1,
    ScheduledDatetime:(*time.Time)(nil),
    CreatedDatetime:(*time.Time)(0xc20810c040),
    Recipients:messagebird.Recipients{
        TotalCount:1,
        TotalSentCount:1,
        TotalDeliveredCount:0,
        TotalDeliveryFailedCount:0,
        Items:[]messagebird.Recipient{
            messagebird.Recipient{
                Recipient:31612345678,
                Status:"sent",
                StatusDatetime:(*time.Time)(0xc20810c360)
            }
        }
    },
    Errors:[]
}

C# example request

const string YourAccessKey = "YOUR_ACCESS_KEY";
Client client = Client.CreateDefault(YourAccessKey);
const long Msisdn = 31612345678;

MessageBird.Objects.Message message =
client.SendMessage("MessageBird", "Tjirp", new[] { Msisdn });

Python example request

client = messagebird.Client(ACCESS_KEY)
message = client.message_create(
        'MessageBird',
        '31612345678',
        'This is a test message.',
        { 'reference' : 'Foobar' }
    )

Example response

{
  'id' : 'e60a6f90453a19019c56ed6b20170831',
  'href' : 'https://rest.messagebird.com/messages/e60a6f90453a19019c56ed6b20170831',
  'direction' : 'mt',
  'type' : 'sms',
  'originator' : 'MessageBird',
  'body' : 'This is a test message.',
  'reference' : 'Foobar',
  'validity' : None,
  'gateway' : 240,
  'typeDetails' : {},
  'datacoding' : 'plain',
  'mclass' : 1,
  'scheduledDatetime' : None,
  'createdDatetime' : '2015-04-19 19:03:34',
  'recipients' : [
    'totalCount' : 1,
    'totalSentCount' : 1,
    'totalDeliveredCount' : 0,
    'totalDeliveryFailedCount' : 0,
    'items' : [
      {
        'recipient' : 31612345678,
        'status' : 'sent',
        'statusDatetime' : '2015-04-19 19:03:34',
      },
    ]
  ]
}

Java example request

import com.messagebird.MessageBirdClient;
import com.messagebird.MessageBirdService;
import com.messagebird.MessageBirdServiceImpl;
import com.messagebird.exceptions.NotFoundException;
import com.messagebird.objects.MessageResponse;
import com.messagebird.exceptions.GeneralException;
import com.messagebird.exceptions.UnauthorizedException;

import java.math.BigInteger;
import java.util.ArrayList;
import java.util.List;

public class ExampleSendMessage {

    public static void main(String[] args) {
        if (args.length < 3) {
            System.out.println("Please specify your access key, one ore more phone numbers and a message body example : java -jar <this jar file> test_accesskey 31612345678,3161112233 \"My message to be send\"");
            return;
        }

        // First create your service object
        final MessageBirdService wsr = new MessageBirdServiceImpl(args[0]);

        // Add the service to the client
        final MessageBirdClient messageBirdClient = new MessageBirdClient(wsr);

        try {
            // Get Hlr using msgId and msisdn
            System.out.println("Sending message:");
            final List<BigInteger> phones = new ArrayList<BigInteger>();
            for (final String phoneNumber : args[1].split(",")) {
                phones.add(new BigInteger(phoneNumber));
            }

            final MessageResponse response = messageBirdClient.sendMessage("MessageBird", args[2], phones);
            System.out.println(response.toString());
        } catch (UnauthorizedException unauthorized) {
            if (unauthorized.getErrors() != null) {
                System.out.println(unauthorized.getErrors().toString());
            }
            unauthorized.printStackTrace();
        } catch (GeneralException generalException) {
            if (generalException.getErrors() != null) {
                System.out.println(generalException.getErrors().toString());
            }
            generalException.printStackTrace();
        }

    }
}

Example response

#<MessageBird::Message:0x007f8d5b883520
 @body="Hello World",
 @createdDatetime=2015-04-19 19:03:34 +0000,
 @datacoding="plain",
 @direction="mt",
 @gateway=239,
 @href=
  "https://rest.messagebird.com/messages/211e6280453ba746e8eeff7b12582146",
 @id="211e6280453ba746e8eeff7b12582146",
 @mclass=1,
 @originator="FromMe",
 @recipient=
  {"totalCount"=>1,
   "totalSentCount"=>1,
   "totalDeliveredCount"=>0,
   "totalDeliveryFailedCount"=>0,
   "items"=>
    [#<MessageBird::Recipient:0x007f8d5c058c00
      @recipient=31612345678,
      @status="sent",
      @statusDatetime=2015-04-19 19:03:34 +0000>]},
 @reference=nil,
 @scheduledDatetime=nil,
 @type="sms",
 @typeDetails={},
 @validity=nil>

Receive a message

Incoming messages from a Virtual Mobile Number (VMN) are received through a configured callback URL (configureable per VMN). The message attributes are send through a POST request by default but the method can be configured per VMN.

Attribute

attribute
type
description
id
string
An unique random ID which is created on the MessageBird platform.
recipient
string
The recipient of the message (the VMN).
originator
string
The sender of the message.
body
string
The body of the SMS message.
createdDatetime
datetime
The date and time of the creation of the message in RFC3339 format (Y-m-d\TH:i:sP)

Example request

GET http://your-own.url/script
?id=e8077d803532c0b5937c639b60216938
&recipient=31642500190
&originator=31612345678
&body=This+is+an+incoming+message
&createdDatetime=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script.php
    ?id=e8077d803532c0b5937c639b60216938
    &recipient=31642500190
    &originator=31612345678
    &body=This+is+an+incoming+message
    &createdDatetime=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &recipient=31642500190
    &originator=31612345678
    &body=This+is+an+incoming+message
    &createdDatetime=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &recipient=31642500190
    &originator=31612345678
    &body=This+is+an+incoming+message
    &createdDatetime=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script
?id=e8077d803532c0b5937c639b60216938
&recipient=31642500190
&originator=31612345678
&body=This+is+an+incoming+message
&createdDatetime=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &recipient=31642500190
    &originator=31612345678
    &body=This+is+an+incoming+message
    &createdDatetime=2015-04-19 19:03:34

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &recipient=31642500190
    &originator=31612345678
    &body=This+is+an+incoming+message
    &createdDatetime=2015-04-19T19:03:34+00:00

Response

200 OK

Your platform should respond with a 200 OK HTTP header. When our platform doesn't receive a 200 OK header, we will try to delivery the receipt again (up to 10 times).

View a message

Retrieves the information of an existing message. This message can be a sent or a received message. You only need to supply the unique message id that was returned upon creation or receiving.

Required parameters

parameter
type
description
id
string
An unique random ID which is created on the MessageBird platform and is returned upon creation of the object. Required

Returns

Returns a message object if the request was successful. If the request failed, an error object will be returned.

Definition

GET https://rest.messagebird.com/messages/{messageId}

cURL example request

$ curl -X GET https://rest.messagebird.com/messages/e8077d803532c0b5937c639b60216938 \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Example response

{
  "id":"e8077d803532c0b5937c639b60216938",
  "href":"https://rest.messagebird.com/messages/e8077d803532c0b5937c639b60216938",
  "direction":"mt",
  "type":"sms",
  "originator":"YourName",
  "body":"This is a test message",
  "reference":null,
  "validity":null,
  "gateway":null,
  "typeDetails":{

  },
  "datacoding":"plain",
  "mclass":1,
  "scheduledDatetime":null,
  "createdDatetime":"2015-04-19T19:03:34+00:00",
  "recipients":{
    "totalCount":1,
    "totalSentCount":1,
    "totalDeliveredCount":0,
    "totalDeliveryFailedCount":0,
    "items":[
      {
        "recipient":31612345678,
        "status":"sent",
        "statusDatetime":"2015-04-19T19:03:34+00:00"
      }
    ]
  }
}

PHP example request

$MessageBird = new \MessageBird\Client('ACCESS_KEY');
$MessageBird->messages->read('e60a6f90453a19019c56ed6b20170831');

Example response

{
  'id' => 'e60a6f90453a19019c56ed6b20170831',
  'href' => 'https://rest.messagebird.com/messages/e60a6f90453a19019c56ed6b20170831',
  'direction' => 'mt',
  'type' => 'sms',
  'originator' => 'MessageBird',
  'body' => 'This is a test message.',
  'reference' => NULL,
  'validity' => NULL,
  'gateway' => 240,
  'typeDetails' => {},
  'datacoding' => 'plain',
  'mclass' => 1,
  'scheduledDatetime' => NULL,
  'createdDatetime' => '2015-04-19T19:03:34+00:00',
  'recipients' => array(
    'totalCount' => 1,
    'totalSentCount' => 1,
    'totalDeliveredCount' => 0,
    'totalDeliveryFailedCount' => 0,
    'items' => array (
      {
        'recipient' => 31612345678,
        'status' => 'delivered',
        'statusDatetime' => '2015-04-19T19:03:34+00:00',
      },
    )
  )
}

Ruby example request

client = MessageBird::Client.new(YOUR_ACCESS_KEY)
client.message('211e6280453ba746e8eeff7b12582146')

Example response

#<MessageBird::Message:0x007f8d5b883520
 @body="Hello World",
 @createdDatetime=2014-07-07 12:20:30 +0200,
 @datacoding="plain",
 @direction="mt",
 @gateway=239,
 @href=
  "https://rest.messagebird.com/messages/211e6280453ba746e8eeff7b12582146",
 @id="211e6280453ba746e8eeff7b12582146",
 @mclass=1,
 @originator="FromMe",
 @recipient=
  {"totalCount"=>1,
   "totalSentCount"=>1,
   "totalDeliveredCount"=>0,
   "totalDeliveryFailedCount"=>0,
   "items"=>
    [#<MessageBird::Recipient:0x007f8d5c058c00
      @recipient=31612345678,
      @status="delivered",
      @statusDatetime=2015-04-19 19:03:34 +0000>]},
 @reference=nil,
 @scheduledDatetime=nil,
 @type="sms",
 @typeDetails={},
 @validity=nil>

Go example request

message, err := client.Message("8ef55b60453c653f5794a87b46861030")

Example response

&messagebird.Message{
    Id:"8ef55b60453c653f5794a87b46861030",
    HRef:"https://rest.messagebird.com/messages/8ef55b60453c653f5794a87b46861030",
    Direction:"mt",
    Type:"sms",
    Originator:"MyName",
    Body:"Hello World",
    Reference:"MyReference",
    Validity:nil,
    Gateway:239,
    TypeDetails:map[string]interface {}{},
    DataCoding:"plain",
    MClass:1,
    ScheduledDatetime:(*time.Time)(nil),
    CreatedDatetime:(*time.Time)(0xc20810c040),
    Recipients:messagebird.Recipients{
        TotalCount:1,
        TotalSentCount:0,
        TotalDeliveredCount:1,
        TotalDeliveryFailedCount:0,
        Items:[]messagebird.Recipient{
            messagebird.Recipient{
                Recipient:31612345678,
                Status:"delivered",
                StatusDatetime:(*time.Time)(0xc20810c360)
            }
        }
    },
    Errors:[]
}

C# example request

const string YourAccessKey = "YOUR_ACCESS_KEY";
const string MessageId = "211e6280453ba746e8eeff7b12582146";

Client client = Client.CreateDefault(YourAccessKey);
MessageBird.Objects.Message message =
    client.ViewMessage(MessageId);

Python example request

client = messagebird.Client(ACCESS_KEY)
message = client.message('e60a6f90453a19019c56ed6b20170831')

Example response

{
  'id' : 'e60a6f90453a19019c56ed6b20170831',
  'href' : 'https://rest.messagebird.com/messages/e60a6f90453a19019c56ed6b20170831',
  'direction' : 'mt',
  'type' : 'sms',
  'originator' : 'MessageBird',
  'body' : 'This is a test message.',
  'reference' : None,
  'validity' : None,
  'gateway' : 240,
  'typeDetails' : {},
  'datacoding' : 'plain',
  'mclass' : 1,
  'scheduledDatetime' : None,
  'createdDatetime' : '2015-04-19 19:03:34',
  'recipients' : [
    'totalCount' : 1,
    'totalSentCount' : 1,
    'totalDeliveredCount' : 0,
    'totalDeliveryFailedCount' : 0,
    'items' : [
      {
        'recipient' : 31612345678,
        'status' : 'delivered',
        'statusDatetime' : '2015-04-19 19:03:34',
      },
    ]
  ]
}

Java example request

import com.messagebird.MessageBirdClient;
import com.messagebird.MessageBirdService;
import com.messagebird.MessageBirdServiceImpl;
import com.messagebird.exceptions.GeneralException;
import com.messagebird.exceptions.NotFoundException;
import com.messagebird.exceptions.UnauthorizedException;
import com.messagebird.objects.MessageResponse;

public class ExampleViewMessage {

  public static void main(String[] args) {
      if (args.length < 2) {
          System.out.println("Please specify your access key and a message ID : java -jar <this jar file≶ test_accesskey e8077d803532c0b5937c639b60216938");
          return;
      }

      // First create your service object
      final MessageBirdService wsr = new MessageBirdServiceImpl(args[0]);

      // Add the service to the client
      final MessageBirdClient messageBirdClient = new MessageBirdClient(wsr);

      try {
          // Get Hlr using msgId and msisdn
          System.out.println("getting message info message:");
          final MessageResponse response = messageBirdClient.viewMessage(args[1]);
          System.out.println(response.toString());


      } catch (UnauthorizedException unauthorized) {
          if (unauthorized.getErrors() != null) {
              System.out.println(unauthorized.getErrors().toString());
          }
          unauthorized.printStackTrace();
      } catch (GeneralException generalException) {
          if (generalException.getErrors() != null) {
              System.out.println(generalException.getErrors().toString());
          }
          generalException.printStackTrace();
      } catch (NotFoundException notFoundException) {
          if (notFoundException.getErrors() !=null) {
              System.out.println(notFoundException.getErrors().toString());
          }
          notFoundException.printStackTrace();
      }
  }
}

Example response

MessageResponse
{
  id='802acbc0354e1d585223067b44890824',
  href='https://rest.messagebird.com/messages/802acbc0354e1d585223067b44890824',
  direction='mt',
  type=MsgType{value='sms'},
  originator='MessageBird',
  body='Hello world',
  reference='null',
  validity=null,
  gateway=239,
  typeDetails={},
  datacoding=DataCoding{value='unicode'},
  mclass=MClass{value=1},
  scheduledDatetime=null,
  createdDatetime=Mon Feb 16 12:33:25 CET 2015,
  recipients=Recipients{totalSentCount=1,
                        totalDeliveredCount=0,
                        totalDeliveryFailedCount=0,
                        items=[Items{recipient=31612345678, status='sent', statusDatetime=Mon Feb 16 12:33:25 CET 2015}]
  }
}

Handle a status rapport

Status rapports are requests that are sent to your platform through a GET request. The requests holds information about the status of a message that you have sent through our API. status rapports are only provided for messages that have a reference and accounts that have configured their status rapport url.

Attributes

attribute
type
description
id
string
An unique random ID which is created on the MessageBird platform and is returned upon creation of the object.
reference
string
A client reference
recipient
string
The recipient where this status rapport applies to.
status
string
The status of the message sent to the recipient. Possible values: scheduled, sent, buffered, delivered, and delivery_failed
statusDatetime
datetime
The datum time of this status in RFC3339 format (Y-m-d\TH:i:sP)

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &reference=YouReference123
    &recipient=31612345678
    &status=delivered
    &status=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script.php
    ?id=e8077d803532c0b5937c639b60216938
    &reference=YouReference123
    &recipient=31612345678
    &status=delivered
    &status=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &reference=YouReference123
    &recipient=31612345678
    &status=delivered
    &status=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &reference=YouReference123
    &recipient=31612345678
    &status=delivered
    &status=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &reference=YouReference123
    &recipient=31612345678
    &status=delivered
    &status=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &reference=YouReference123
    &recipient=31612345678
    &status=delivered
    &status=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script
        ?id=e8077d803532c0b5937c639b60216938
        &reference=YouReference123
        &recipient=31612345678
        &status=delivered
        &status=2015-04-19T19:03:34+00:00

Response

200 OK

Your platform should respond with a 200 OK HTTP header. When our platform doesn't receive a 200 OK header, we will try to delivery the receipt again (up to 10 times).

Voice Messaging

MessageBird provides an API to transform text messages into voice messages to any country across the world.

Voice messages are identified by a unique random ID. And with this ID you can always check the status of the voice message through the provided endpoint.

URI

https://rest.messagebird.com/voicemessages

Available http methods

POST /voicemessages
GET  /voicemessages/{voiceMessageId}

The voice message object

This object represents a voice message at MessageBird.com

Attributes

attribute
type
description
id
string
An unique random ID which is created on the MessageBird platform and is returned upon creation of the object.
href
string
The URL of the created object.
reference
string
A client reference
body
string
The body of the SMS message. The maxlength is 1000 charachters. Check the voice body for more options
language
string
The language in which the message needs to be read to the recipient. Possible values are: nl-nl, de-de, en-gb, en-us, fr-fr.
voice
string
The voice in which the messages needs to be read to the recipient. Possible values are: male, female.
repeat
int
How many times needs the message to be repeated?
ifMachine
string
What to do when a machine picks up the phone? Possible values are:
- continue do not check, just play the message
- delay if a machine answers, wait until the machine stops talking
- hangup hangup when a machine answers
scheduledDatetime
datetime
The scheduled date and time of the message in RFC3339 format (Y-m-d\TH:i:sP)
createdDatetime
datetime
The date and time of the creation of the message in RFC3339 format (Y-m-d\TH:i:sP)
recipients
hash
The hash with recipient information. Further explanation in the table below.

The recipients array

attribute
type
description
totalCount
integer
The total count of recipients.
totalSentCount
integer
The count of recipients that have the message pending (status calling).
totalDeliveredCount
integer
The count of recipients where the message is delivered (status answered).
totalDeliveryFailedCount
integer
The count of recipients where the delivery has failed (status failed, busy, machine).
items
array
An array of recipient hashes
items[].recipient
integer
The msisdn of the recipient
items[].status
string
The status of the message sent to the recipient. Possible values: calling, answered, failed. For future use the following status are reserved: busy and machine
items[].statusDatetime
datetime
The datum time of the last status in RFC3339 format (Y-m-d\TH:i:sP)

Voice message object example

{
  "id":"e8077d803532c0b5937c639b60216938",
  "href":"https://rest.messagebird.com/voicemessages/e8077d803532c0b5937c639b60216938",
  "body":"The voice message to be sent",
  "reference":"the-client-reference",
  "language":"en-gb",
  "voice":"female",
  "repeat":1,
  "ifMachine":"continue",
  "scheduledDatetime":null,
  "createdDatetime":"2015-04-19T19:03:34+00:00",
  "recipients":{
    "totalCount":1,
    "totalSentCount":1,
    "totalDeliveredCount":0,
    "totalDeliveryFailedCount":0,
    "items":[
      {
        "recipient":31612345678,
        "status":"answered",
        "statusDatetime":"2015-04-19T19:03:34+00:00"
      }
    ]
  }
}

The voice body

By tweaking the body you can alter the speed and delays in the spoken text.

You can add a small delay between words or digits by adding a comma (,).
Another possibility is adding the "break" tag with an attribute "value" in seconds (s) or milliseconds (ms).

It is also possible to change the speaking rate, you can use the "prosody" tag with an attribute "value" in percentage.

Examples

Delay with a comma:
Hello, your login token is 1, 8, 3, 4, 0

Delay with a break tag:
Hello, your login token is<break time="1s"/>1<break time="500ms"/>8
   <break time="500ms"/>3<break time="500ms"/>4<break time="500ms"/>0

Speaking rate:
You login token is <prosody rate="-10%">1, 8, 3, 4, 0</prosody>


Send a voice message

Creates a new voice message object. MessageBird returns the created voice message object with each request. Per request, a max of 50 recipients can be entered.

Required parameters

parameter
type
description
body
string
The body of the SMS message. Required
recipients
array
The array of recipients msisdn's. Required

Optional parameters

parameter
type
description
reference
string
A client reference
language
string
The language in which the message needs to be read to the recipient. Possible values are: nl-nl, de-de, en-gb, en-us, fr-fr.
Default: en-gb
voice
string
The voice in which the messages needs to be read to the recipient. Possible values are: male, female.
Default: female
repeat
int
How many times needs the message to be repeated?
Default: 1
ifMachine
string
What to do when a machine picks up the phone? Possible values are:
- continue do not check, just play the message
- delay if a machine answers, wait until the machine stops talking
- hangup hangup when a machine answers
Default: continue
scheduledDatetime
datetime
The scheduled date and time of the message in RFC3339 format (Y-m-d\TH:i:sP)

Returns

Returns a message object if the request was successful. If the request failed, an error object will be returned.

cURL example request

$ curl -X POST https://rest.messagebird.com/voicemessages \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
-d "recipients=31612345678" \
-d "body=The voice message to be sent"

Example response

{
  "id":"e8077d803532c0b5937c639b60216938",
  "href":"https://rest.messagebird.com/voicemessages/e8077d803532c0b5937c639b60216938",
  "body":"The voice message to be sent",
  "reference":"the-client-reference",
  "language":"en-gb",
  "voice":"female",
  "repeat":1,
  "ifMachine":"continue",
  "scheduledDatetime":null,
  "createdDatetime":"2015-04-19T19:03:34+00:00",
  "recipients":{
    "totalCount":1,
    "totalSentCount":1,
    "totalDeliveredCount":0,
    "totalDeliveryFailedCount":0,
    "items":[
      {
        "recipient":31612345678,
        "status":"calling",
        "statusDatetime":"2015-04-19T19:03:34+00:00"
      }
    ]
  }
}

PHP example request

$MessageBird = new \MessageBird\Client('ACCESS_KEY');

$VoiceMessage = new \MessageBird\Objects\VoiceMessage();
$VoiceMessage->originator = 'MessageBird';
$VoiceMessage->body = 'This is a test message.';
$VoiceMessage->language = 'en-gb';
$VoiceMessage->voice = 'male';

$MessageBird->voicemessages->create($VoiceMessage);

Example response

{
  'id' => 'e60a6f90453a19019c56ed6b20170831',
  'href' => 'https://rest.messagebird.com/voicemessages/e60a6f90453a19019c56ed6b20170831',
  'body' => 'This is a test message.',
  'reference' => NULL,
  'language' => 'en-gb',
  'voice' => 'male',
  'repeat' => 1,
  'ifMachine' => 'continue',
  'scheduledDatetime' => NULL,
  'createdDatetime' => '2015-04-19T19:03:34+00:00',
  'recipients' => array(
    'totalCount' => 1,
    'totalSentCount' => 1,
    'totalDeliveredCount' => 0,
    'totalDeliveryFailedCount' => 0,
    'items' => array (
      {
        'recipient' => 31612345678,
        'status' => 'calling',
        'statusDatetime' => '2015-04-19T19:03:34+00:00',
      },
    )
  )
}

Ruby example request

client = MessageBird::Client.new(YOUR_ACCESS_KEY)
  vmsg = client.voice_message_create('  31612345678', 'Hello World', :reference => 'Foobar')

Example response

#<MessageBird::VoiceMessage:0x007f8d5b883520
 @body="Hello World",
 @createdDatetime=2015-04-19 19:03:34 +0000,
 @language="en-gb",
 @voice="female",
 @repeat=1,
 @ifMachine="continue",
 @href=
  "https://rest.messagebird.com/voicemessages/211e6280453ba746e8eeff7b12582146",
 @id="211e6280453ba746e8eeff7b12582146",
 @recipient=
  {"totalCount"=>1,
   "totalSentCount"=>1,
   "totalDeliveredCount"=>0,
   "totalDeliveryFailedCount"=>0,
   "items"=>
    [#<MessageBird::Recipient:0x007f8d5c058c00
      @recipient=31612345678,
      @status="calling",
      @statusDatetime=2015-04-19 19:03:34 +0000>]},
 @reference=nil,
 @scheduledDatetime=nil>

Go example request

// The optional parameters.
params := &messagebird.VoiceMessageParams{Reference: "MyReference"}

message, err := client.NewVoiceMessage(
  []string{"31612345678"},
  "Hello World",
  params)

Example response

&messagebird.VoiceMessage{
    Id:"7e239990453c654186e1556a08066993",
    HRef:"https://rest.messagebird.com/voicemessages/7e239990453c654186e1556a08066993",
    Body:"Hello World",
    Reference:"MyReference",
    Language:"en-gb",
    Voice:"female",
    Repeat:1,
    IfMachine:"continue",
    ScheduledDatetime:(*time.Time)(nil),
    CreatedDatetime:(*time.Time)(0xc208268920),
    Recipients:messagebird.Recipients{
        TotalCount:1,
        TotalSentCount:1,
        TotalDeliveredCount:0,
        TotalDeliveryFailedCount:0,
        Items:[]messagebird.Recipient{
            messagebird.Recipient{
                Recipient:31612345678,
                Status:"calling",
                StatusDatetime:(*time.Time)(0xc208268b80)
            }
        }
    },
    Errors:[]
}

C# example request

const string YourAccessKey = "YOUR_ACCESS_KEY";
const long Msisdn = 31612345678;

Client client = Client.CreateDefault(YourAccessKey);

MessageBird.Objects.VoiceMessage voiceMessage =
    client.SendVoiceMessage("Hello world", new[] { Msisdn }, {});

Python example request

client = messagebird.Client(ACCESS_KEY)
voice_message = client.voice_message_create(
        '31612345678',
        'This is a test message',
        { 'language' : 'en-gb', 'voice': 'male' }
    )

Example response

{
  'id' : 'e60a6f90453a19019c56ed6b20170831',
  'href' : 'https://rest.messagebird.com/voicemessages/e60a6f90453a19019c56ed6b20170831',
  'body' : 'This is a test message.',
  'reference' : None,
  'language' : 'en-gb',
  'voice' : 'male',
  'repeat' : 1,
  'ifMachine' : 'continue',
  'scheduledDatetime' : None,
  'createdDatetime' : '2015-04-19 19:03:34',
  'recipients' : [
    'totalCount' : 1,
    'totalSentCount' : 1,
    'totalDeliveredCount' : 0,
    'totalDeliveryFailedCount' : 0,
    'items' : [
      {
        'recipient' : 31612345678,
        'status' : 'calling',
        'statusDatetime' : '2015-04-19 19:03:34',
      },
    ]
  ]
}

Java example request

import com.messagebird.MessageBirdClient;
import com.messagebird.MessageBirdService;
import com.messagebird.MessageBirdServiceImpl;
import com.messagebird.exceptions.GeneralException;
import com.messagebird.exceptions.UnauthorizedException;
import com.messagebird.objects.IfMachineType;
import com.messagebird.objects.VoiceType;
import com.messagebird.objects.VoiceMessage;
import com.messagebird.objects.VoiceMessageResponse;

import java.math.BigInteger;
import java.util.ArrayList;
import java.util.List;

public class ExampleSendVoiceMessage {
    public static void main(String[] args) {
        if (args.length < 3) {
            System.out.println("Please specify your access key, one ore more phone numbers and a message body example : java -jar <this jar file≶ test_accesskey 31612345678,3161112233 \"My message to be send\"");
            return;
        }

        // First create your service object
        final MessageBirdService wsr = new MessageBirdServiceImpl(args[0]);

        // Add the service to the client
        final MessageBirdClient messageBirdClient = new MessageBirdClient(wsr);

        try {
            // Get Hlr using msgId and msisdn
            System.out.println("Sending message:");
            final List<BigInteger≶ phones = new ArrayList<BigInteger≶();
            for (final String phoneNumber : args[1].split(",")) {
                phones.add(new BigInteger(phoneNumber));
            }

            // Send a voice message using the VoiceMessage object
            final VoiceMessage vm = new VoiceMessage(args[2], phones);
            vm.setIfMachine(IfMachineType.hangup);
            vm.setVoice(VoiceType.male);
            final VoiceMessageResponse response = messageBirdClient.sendVoiceMessage(vm);
            System.out.println(response.toString());

        } catch (UnauthorizedException unauthorized) {
            if (unauthorized.getErrors() != null) {
                System.out.println(unauthorized.getErrors().toString());
            }
            unauthorized.printStackTrace();
        } catch (GeneralException generalException) {
            if (generalException.getErrors() != null) {
                System.out.println(generalException.getErrors().toString());
            }
            generalException.printStackTrace();
        }
    }
}

Example response

VoiceMessageResponse{
  id='a35955b0454e1e8d9597a71a08500938',
  href='https://rest.messagebird.com/voicemessages/a35955b0454e1e8d9597a71a08500938',
  body='Hello world',
  reference='null',
  language='en-gb',
  voice=Voice{value='male'},
  repeat=1,
  ifMachine=IfMachine{value='hangup'},
  scheduledDatetime=null,
  createdDatetime=Mon Feb 16 13:55:53 CET 2015,
  recipients=Recipients{totalSentCount=1,
                        totalDeliveredCount=0,
                        totalDeliveryFailedCount=0,
                        items=[Items{recipient=31612345678, status='calling', statusDatetime=Mon Feb 16 13:55:53 CET 2015}]
  }
}

View a voice message

Retrieves the information of an existing voice message. You only need to supply the unique voice message id that was returned upon creation.

Required parameters

parameter
type
description
id
string
An unique random ID which is created on the MessageBird platform and is returned upon creation of the object. Required

Returns

Returns a voice message object if the request was successful. If the request failed, an error object will be returned.

Definition

GET https://rest.messagebird.com/voicemessages/{voiceMessageId}

cURL example request

$ curl -X GET https://rest.messagebird.com/voicemessages/e8077d803532c0b5937c639b60216938 \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Example response

{
  "id":"e8077d803532c0b5937c639b60216938",
  "href":"https://rest.messagebird.com/voicemessages/e8077d803532c0b5937c639b60216938",
  "body":"The voice message to be sent",
  "reference":"the-client-reference",
  "language":"en-gb",
  "voice":"female",
  "repeat":1,
  "ifMachine":"continue",
  "scheduledDatetime":null,
  "createdDatetime":"2015-04-19T19:03:34+00:00",
  "recipients":{
    "totalCount":1,
    "totalSentCount":1,
    "totalDeliveredCount":0,
    "totalDeliveryFailedCount":0,
    "items":[
      {
        "recipient":31612345678,
        "status":"calling",
        "statusDatetime":"2015-04-19T19:03:34+00:00"
      }
    ]
  }
}

PHP example request

$MessageBird = new \MessageBird\Client('ACCESS_KEY');
$MessageBird->voicemessages->read('e60a6f90453a19019c56ed6b20170831');

Example response

{
  'id' => 'e60a6f90453a19019c56ed6b20170831',
  'href' => 'https://rest.messagebird.com/voicemessages/e60a6f90453a19019c56ed6b20170831',
  'body' => 'This is a test message.',
  'reference' => NULL,
  'language' => 'en-gb',
  'voice' => 'male',
  'repeat' => 1,
  'ifMachine' => 'continue',
  'scheduledDatetime' => NULL,
  'createdDatetime' => '2015-04-19T19:03:34+00:00',
  'recipients' => array(
    'totalCount' => 1,
    'totalSentCount' => 1,
    'totalDeliveredCount' => 0,
    'totalDeliveryFailedCount' => 0,
    'items' => array (
      {
        'recipient' => 31612345678,
        'status' => 'answered',
        'statusDatetime' => '2015-04-19T19:03:34+00:00',
      },
    )
  )
}

Ruby example request

client = MessageBird::Client.new(YOUR_ACCESS_KEY)
client.voice_message('211e6280453ba746e8eeff7b12582146')

Example response

#<MessageBird::VoiceMessage:0x007f8d5b883520
 @body="Hello World",
 @createdDatetime=2015-04-19 19:03:34 +0000,
 @language="en-gb",
 @voice="female",
 @repeat=1,
 @ifMachine="continue",
 @href=
  "https://rest.messagebird.com/voicemessages/211e6280453ba746e8eeff7b12582146",
 @id="211e6280453ba746e8eeff7b12582146",
 @recipient=
  {"totalCount"=>1,
   "totalSentCount"=>1,
   "totalDeliveredCount"=>0,
   "totalDeliveryFailedCount"=>0,
   "items"=>
    [#<MessageBird::Recipient:0x007f8d5c058c00
      @recipient=31612345678,
      @status="answered",
      @statusDatetime=2015-04-19 19:03:34 +0000>]},
 @reference=nil,
 @scheduledDatetime=nil>

Go example request

voicemessage, err := client.VoiceMessage("211e6280453ba746e8eeff7b12582146")

Example response

&messagebird.VoiceMessage{
    Id:"211e6280453ba746e8eeff7b12582146",
    HRef:"https://rest.messagebird.com/voicemessages/211e6280453ba746e8eeff7b12582146",
    Body:"Hello World",
    Reference:"MyReference",
    Language:"en-gb",
    Voice:"female",
    Repeat:1,
    IfMachine:"continue",
    ScheduledDatetime:(*time.Time)(nil),
    CreatedDatetime:(*time.Time)(0xc208268920),
    Recipients:messagebird.Recipients{
        TotalCount:1,
        TotalSentCount:1,
        TotalDeliveredCount:0,
        TotalDeliveryFailedCount:0,
        Items:[]messagebird.Recipient{
            messagebird.Recipient{
                Recipient:31612345678,
                Status:"answered",
                StatusDatetime:(*time.Time)(0xc208268b80)
            }
        }
    },
    Errors:[]
}

C# example request

const string YourAccessKey = "YOUR_ACCESS_KEY";
const string MessageId = "211e6280453ba746e8eeff7b12582146";

Client client = Client.CreateDefault(YourAccessKey);
MessageBird.Objects.VoiceMessage voiceMessage =
    client.ViewVoiceMessage(MessageId);

Python example request

client = messagebird.Client(ACCESS_KEY)
voice_message= client.voice_message('e60a6f90453a19019c56ed6b20170831')

Example response

{
  'id' : 'e60a6f90453a19019c56ed6b20170831',
  'href' : 'https://rest.messagebird.com/voicemessages/e60a6f90453a19019c56ed6b20170831',
  'body' : 'This is a test message.',
  'reference' : None,
  'language' : 'en-gb',
  'voice' : 'male',
  'repeat' : 1,
  'ifMachine' : 'continue',
  'scheduledDatetime' : None,
  'createdDatetime' : '2015-04-19 19:03:34',
  'recipients' : [
    'totalCount' : 1,
    'totalSentCount' : 1,
    'totalDeliveredCount' : 0,
    'totalDeliveryFailedCount' : 0,
    'items' : [
      {
        'recipient' : 31612345678,
        'status' : 'answered',
        'statusDatetime' : '2015-04-19 19:03:34',
      },
    ]
  ]
}

Java example request

import com.messagebird.MessageBirdClient;
import com.messagebird.MessageBirdService;
import com.messagebird.MessageBirdServiceImpl;
import com.messagebird.exceptions.NotFoundException;
import com.messagebird.objects.VoiceMessageResponse;
import com.messagebird.exceptions.GeneralException;
import com.messagebird.exceptions.UnauthorizedException;

public class ExampleViewVoiceMessage {
  public static void main(String[] args) {
      if (args.length < 2) {
          System.out.println("Please specify your access key and a voice message ID : java -jar  test_accesskey e8077d803532c0b5937c639b60216938");
          return;
      }

      // First create your service object
      final MessageBirdService wsr = new MessageBirdServiceImpl(args[0]);

      // Add the service to the client
      final MessageBirdClient messageBirdClient = new MessageBirdClient(wsr);

      try {
          // Get Hlr using msgId and msisdn
          System.out.println("Getting message info message:");
          final VoiceMessageResponse response = messageBirdClient.viewVoiceMessage(args[1]);
          System.out.println(response.toString());


      } catch (UnauthorizedException unauthorized) {
          if (unauthorized.getErrors() != null) {
              System.out.println(unauthorized.getErrors().toString());
          }
          unauthorized.printStackTrace();
      } catch (GeneralException generalException) {
          if (generalException.getErrors() != null) {
              System.out.println(generalException.getErrors().toString());
          }
          generalException.printStackTrace();
      } catch (NotFoundException notFoundException) {
          if (notFoundException.getErrors() !=null) {
              System.out.println(notFoundException.getErrors().toString());
          }
          notFoundException.printStackTrace();
      }
  }
}

Example response

VoiceMessageResponse{
  id='a35955b0454e1e8d9597a71a08500938',
  href='https://rest.messagebird.com/voicemessages/a35955b0454e1e8d9597a71a08500938',
  body='Hello world',
  reference='null',
  language='en-gb',
  voice=Voice{value='male'},
  repeat=1,
  ifMachine=IfMachine{value='hangup'},
  scheduledDatetime=null,
  createdDatetime=Mon Feb 16 13:55:53 CET 2015,
  recipients=Recipients{totalSentCount=1,
                        totalDeliveredCount=0,
                        totalDeliveryFailedCount=0,
                        items=[Items{recipient=31612345678, status='calling', statusDatetime=Mon Feb 16 13:55:53 CET 2015}]
  }
}

Handle a status rapport

Status rapports are requests that are sent to your platform through a GET request. The requests holds information about the status of a voice message that you have sent through our API. Status rapports are only provided for voice messages that have a reference and accounts that have configured their status rapport url.

Attributes

attribute
type
description
id
string
An unique random ID which is created on the MessageBird platform and is returned upon creation of the object.
reference
string
A client reference
recipient
string
The recipient where this status rapport applies to.
status
string
The status of the message sent to the recipient. Possible values: calling, answered, failed. For future use the following status are reserved: busy and machine
statusDatetime
datetime
The datum time of this status in RFC3339 format (Y-m-d\TH:i:sP)

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &reference=YouReference123
    &recipient=31612345678
    &status=answered
    &status=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script.php
    ?id=e8077d803532c0b5937c639b60216938
    &reference=YouReference123
    &recipient=31612345678
    &status=answered
    &status=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &reference=YouReference123
    &recipient=31612345678
    &status=answered
    &status=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &reference=YouReference123
    &recipient=31612345678
    &status=answered
    &status=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &reference=YouReference123
    &recipient=31612345678
    &status=answered
    &status=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &reference=YouReference123
    &recipient=31612345678
    &status=answered
    &status=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &reference=YouReference123
    &recipient=31612345678
    &status=answered
    &status=2015-04-19T19:03:34+00:00

Response

200 OK

Your platform should respond with a 200 OK HTTP header. When our platform doesn't receive a 200 OK header, we will try to delivery the receipt again (up to 10 times).

HLR

MessageBird provides an API to send Network Queries to any mobile number across the world.

An HLR allows you to view which mobile number (MSISDN) belongs to what operator in real time and see whether the number is active.

URI

https://rest.messagebird.com/hlr

Available http methods

POST /hlr
GET  /hlr/{hlrId}

The HLR object

This object represents a hlr at MessageBird.com

Attributes

attribute
type
description
id
string
An unique random ID which is created on the MessageBird platform and is returned upon creation of the object.
href
string
The URL of the created object.
msisdn
int
The telephone number.
network
int
The MCCMNC code of the network provider.
reference
string
A client reference
status
string
The status of the msisdns. Possible values: sent, absent, active, unknown, and failed
createdDatetime
datetime
The date and time of the creation of the message in RFC3339 format (Y-m-d\TH:i:sP)
statusDatetime
datetime
The datum time of the last status in RFC3339 format (Y-m-d\TH:i:sP)

HLR object example

{
  "id":"0da180b035398662ceb3c42h04904985",
  "href":"https:\/\/rest.messagebird.com\/hlr\/0da180b035398662ceb3c42h04904985",
  "msisdn":31612345678,
  "network":20406,
  "reference":"YourReference",
  "status":"active",
  "createdDatetime":"2015-04-19T19:03:34+00:00",
  "statusDatetime":"2015-04-19T19:03:34+00:00"
}

Request an HLR

Creates a new HLR object. MessageBird returns the created HLR object with each request.

Required parameters

parameter
type
description
msisdn
int
The telephone number that you want to do a network query on. Required
reference
string
A client reference. Required

Returns

Returns an HLR object if the request was successful. If the request failed, an error object will be returned.

Definition

POST https://rest.messagebird.com/hlr

cURL example request

$ curl -X POST https://rest.messagebird.com/hlr \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
-d "msisdn=31612345678" \
-d "reference=YourReference"

Example response

{
  "id":"0da180b035398662ceb3c42h04904985",
  "href":"https:\/\/rest.messagebird.com\/hlr\/0da180b035398662ceb3c42h04904985",
  "msisdn":31612345678,
  "network":null,
  "reference":"YourReference",
  "status":"sent",
  "createdDatetime":"2015-04-19T19:03:34+00:00",
  "statusDatetime":"2015-04-19T19:03:34+00:00"
}

PHP example request

$MessageBird = new \MessageBird\Client('ACCESS_KEY');

$Hlr = new \MessageBird\Objects\Hlr();
$Hlr->msisdn = 31612345678;
$Hlr->reference = "Referencetietje";

$MessageBird->hlr->create($Hlr);

Example response

{
  'id' => '9772ef10153a19646413512h43680562',
  'href' => 'https://rest.messagebird.com/hlr/9772ef10153a19646413512h43680562',
  'msisdn' => 31612345678,
  'network' => NULL,
  'reference' => 'Referencetietje',
  'status' => 'sent',
  'createdDatetime' => '2015-04-19T19:03:34+00:00',
  'statusDatetime' => '2015-04-19T19:03:34+00:00',
}

Ruby example request

client = MessageBird::Client.new(YOUR_ACCESS_KEY)
client.hlr_create('0612345678', 'MyReference')

Example response

#<MessageBird::HLR:0x007f8d5b8dafc8
 @createdDatetime=2015-04-19 19:03:34 +0000,
 @href="https://rest.messagebird.com/hlr/4933bed0453ba7455031712h16830892",
 @id="4933bed0453ba7455031712h16830892",
 @msisdn=31612345678,
 @network=nil,
 @reference="MyReference",
 @status="sent",
 @statusDatetime=2015-04-19 19:03:34 +0000>

Go example request

hlr, err := client.NewHLR("31612345678", "MyReference")
    

Example response

&messagebird.HLR{
    Id:"4933bed0453ba7455031712h16830892",
    HRef:"https://rest.messagebird.com/hlr/4933bed0453ba7455031712h16830892",
    MSISDN:31612345678,
    Reference:"MyReference",
    Status:"sent",
    CreatedDatetime:(*time.Time)(0xc2081254c0),
    StatusDatetime:(*time.Time)(0xc208125680),
    Errors:[]
}

C# example request

const string YourAccessKey = "YOUR_ACCESS_KEY";
const long Msisdn = 31612345678;

Client client = Client.CreateDefault(YourAccessKey);
Hlr hlr = client.RequestHlr(Msisdn, "Custom reference");

Python example request

client = messagebird.Client(ACCESS_KEY)
hlr = client.hlr_create(
        '31612345678',
        'MyReference'
    )

Example response

{
  'id' : '9772ef10153a19646413512h43680562',
  'href' : 'https://rest.messagebird.com/hlr/9772ef10153a19646413512h43680562',
  'msisdn' : 31612345678,
  'network' : None,
  'reference' : 'MyReference',
  'status' : 'sent',
  'createdDatetime' : '2015-04-19 19:03:34',
  'statusDatetime' : '2015-04-19 19:03:34',
}

Java example request

import com.messagebird.MessageBirdClient;
import com.messagebird.MessageBirdService;
import com.messagebird.MessageBirdServiceImpl;
import com.messagebird.exceptions.NotFoundException;
import com.messagebird.objects.Hlr;
import com.messagebird.exceptions.GeneralException;
import com.messagebird.exceptions.UnauthorizedException;

import java.math.BigInteger;

public class ExampleReadHlr {

    public static void main(String[] args) {

        if (args.length < 2) {
            System.out.println("Please specify your access key and phone in that order example : java -jar <this jar file≶ test_accesskey 31612345678");
            return;
        }

        // First create your service object
        final MessageBirdService wsr = new MessageBirdServiceImpl(args[0]);

        // Add the service to the client
        final MessageBirdClient messageBirdClient = new MessageBirdClient(wsr);

        try {
            // Get Hlr using msgId and msisdn
            System.out.println("Retrieving HLR:");
            final Hlr hlr1 = messageBirdClient.getRequestHlr(new BigInteger(0612345678), "ExampleReadHlr reference");
            System.out.println(hlr1.toString());

            // Get Hlr using the id only
            System.out.println("Now using returned id to get Hlr:");
            final Hlr hlr2 = messageBirdClient.getViewHlr(hlr1.getId());
            System.out.println(hlr1.toString());

        } catch (UnauthorizedException unauthorized) {
            if (unauthorized.getErrors()!=null) {
                System.out.println(unauthorized.getErrors().toString());
            }
            unauthorized.printStackTrace();
        } catch (GeneralException generalException) {
            if (generalException.getErrors() !=null) {
                System.out.println(generalException.getErrors().toString());
            }
            generalException.printStackTrace();
        } catch (NotFoundException notFoundException) {
            if (notFoundException.getErrors() !=null) {
                System.out.println(notFoundException.getErrors().toString());
            }
            notFoundException.printStackTrace();
        }
    }
}

Example response


{
  id='ce654390654e1ce5530e9a8h56512055',
  href='https://rest.messagebird.com/hlr/ce654390654e1ce5530e9a8h56512055',
  msisdn=31612345678, network='null',
  reference='ExampleReadHlr reference',
  status='sent',
  createdDatetime=2015-04-19T19:03:34+00:00,
  statusDatetime=2015-04-19T19:03:34+00:00
}

View an HLR

Retrieves the information of an existing HLR. You only need to supply the unique message id that was returned upon creation or receiving.

Required parameters

parameter
type
description
id
string
An unique random ID which is created on the MessageBird platform and is returned upon creation of the object. Required

Returns

Returns an HLR object if the request was successful. If the request failed, an error object will be returned.

Definition

GET https://rest.messagebird.com/hlr/{hlrId}

cURL example request

$ curl -X GET https://rest.messagebird.com/hlr/0da180b035398662ceb3c42h04904985 \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Example response

{
  "id":"0da180b035398662ceb3c42h04904985",
  "href":"https:\/\/rest.messagebird.com\/hlr\/0da180b035398662ceb3c42h04904985",
  "msisdn":31612345678,
  "network":20406,
  "reference":"YourReference",
  "status":"active",
  "createdDatetime":"2015-04-19T19:03:34+00:00",
  "statusDatetime":"2015-04-19T19:03:34+00:00"
}

PHP example request

$MessageBird = new \MessageBird\Client('ACCESS_KEY');
$MessageBird->hlr->read('9772ef10153a19646413512h43680562');

Example response

{
  'id' => '9772ef10153a19646413512h43680562',
  'msisdn' => 31612345678,
  'network' => 20104,
  'reference' => 'Referencetietje',
  'status' => 'active',
  'createdDatetime' => '2015-04-19T19:03:34+00:00',
  'statusDatetime' => '2015-04-19T19:03:34+00:00',
}

Ruby example request

client = MessageBird::Client.new(YOUR_ACCESS_KEY)
client.hlr('4933bed0453ba7455031712h16830892')

Example response

#<MessageBird::HLR:0x007f8db91ebe20
 @createdDatetime=2014-07-07 12:58:18 +0200,
 @href="https://rest.messagebird.com/hlr/4933bed0453ba7455031712h16830892",
 @id="4933bed0453ba7455031712h16830892",
 @msisdn=31612345678,
 @network="20408",
 @reference="MyReference",
 @status="absent",
 @statusDatetime=2015-04-19 19:03:34 +0000>

Go example request

hlr, err := client.HLR("4933bed0453ba7455031712h16830892")

Example response

&messagebird.HLR{
    Id:"4933bed0453ba7455031712h16830892",
    HRef:"https://rest.messagebird.com/hlr/4933bed0453ba7455031712h16830892",
    MSISDN:31612345678,
    Network:20406,
    Reference:"MyReference",
    Status:"absent",
    CreatedDatetime:(*time.Time)(0xc2081254c0),
    StatusDatetime:(*time.Time)(0xc208125680),
    Errors:[]
}

Example request

const string YourAccessKey = "YOUR_ACCESS_KEY";
const string HlrId = "4933bed0453ba7455031712h16830892";

Client client = Client.CreateDefault(YourAccessKey);
Hlr hlr = client.ViewHlr(HlrId);

Python example request

client = messagebird.Client(ACCESS_KEY)
hlr = client.hlr('9772ef10153a19646413512h43680562')

Example response

{
  'id' : '9772ef10153a19646413512h43680562',
  'msisdn' : 31612345678,
  'network' : 20104,
  'reference' : 'Referencetietje',
  'status' : 'active',
  'createdDatetime' : '2015-04-19 19:03:34',
  'statusDatetime' : '2015-04-19 19:03:34',
}

Java example request

import com.messagebird.MessageBirdClient;
import com.messagebird.MessageBirdService;
import com.messagebird.MessageBirdServiceImpl;
import com.messagebird.exceptions.NotFoundException;
import com.messagebird.objects.Hlr;
import com.messagebird.exceptions.GeneralException;
import com.messagebird.exceptions.UnauthorizedException;

import java.math.BigInteger;

public class ExampleReadHlr {

   public static void main(String[] args) {

       if (args.length < 2) {
           System.out.println("Please specify your access key and phone in that order example : java -jar  test_accesskey 31612345678");
           return;
       }

       // First create your service object
       final MessageBirdService wsr = new MessageBirdServiceImpl(args[0]);

       // Add the service to the client
       final MessageBirdClient messageBirdClient = new MessageBirdClient(wsr);

       try {
           // Get Hlr using msgId and msisdn
           System.out.println("Retrieving HLR:");
           final Hlr hlr1 = messageBirdClient.getRequestHlr(new BigInteger(args[1]), "ExampleReadHlr reference");
           System.out.println(hlr1.toString());

           // Get Hlr using the id only
           System.out.println("Now using returned id to get Hlr:");
           final Hlr hlr2 = messageBirdClient.getViewHlr(hlr1.getId());
           System.out.println(hlr1.toString());

       } catch (UnauthorizedException unauthorized) {
           if (unauthorized.getErrors()!=null) {
               System.out.println(unauthorized.getErrors().toString());
           }
           unauthorized.printStackTrace();
       } catch (GeneralException generalException) {
           if (generalException.getErrors() !=null) {
               System.out.println(generalException.getErrors().toString());
           }
           generalException.printStackTrace();
       } catch (NotFoundException notFoundException) {
           if (notFoundException.getErrors() !=null) {
               System.out.println(notFoundException.getErrors().toString());
           }
           notFoundException.printStackTrace();
       }
   }
}

Example response


{
  id='ce654390654e1ce5530e9a8h56512055',
  href='https://rest.messagebird.com/hlr/ce654390654e1ce5530e9a8h56512055',
  msisdn=31612345678, network='null',
  reference='ExampleReadHlr reference',
  status='sent',
  createdDatetime=2015-04-19T19:03:34+00:00,
  statusDatetime=2015-04-19T19:03:34+00:00
}

Handle an HLR response

HLR responses are requests that are sent to your platform through a GET request. The requests holds information about the requested network query. You can configure your HLR callback url on de developers settings.

Attributes

attribute
type
description
id
string
An unique random ID which is created on the MessageBird platform and is returned upon creation of the object.
msisdn
int
The telephone number.
network
int
The MCCMNC code of the network provider.
reference
string
A client reference
status
string
The status of the msisdn. Possible values: sent, absent, active, unknown, and failed
createdDatetime
datetime
The date and time of the creation of the message in RFC3339 format (Y-m-d\TH:i:sP)
statusDatetime
datetime
The datum time of the last status in RFC3339 format (Y-m-d\TH:i:sP)

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &msisdn=31612345678
    &reference=YourReference
    &status=active
    &createdDatetime=2015-04-19T19:03:34+00:00    &statusDatetime=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script.php
    ?id=e8077d803532c0b5937c639b60216938
    &msisdn=31612345678
    &reference=YourReference
    &status=active
    &createdDatetime=2015-04-19T19:03:34+00:00    &statusDatetime=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &msisdn=31612345678
    &reference=YourReference
    &status=active
    &createdDatetime=2015-04-19T19:03:34+00:00
    &statusDatetime=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &msisdn=31612345678
    &reference=YourReference
    &status=active
    &createdDatetime=2015-04-19T19:03:34+00:00    &statusDatetime=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &msisdn=31612345678
    &reference=YourReference
    &status=active
    &createdDatetime=2015-04-19T19:03:34+00:00    &statusDatetime=2015-04-19T19:03:34+00:00

Example request

GET http://your-own.url/script
    ?id=e8077d803532c0b5937c639b60216938
    &msisdn=31612345678
    &reference=YourReference
    &status=active
    &createdDatetime=2015-04-19T19:03:34+00:00    &statusDatetime=2015-04-19T19:03:34+00:00

Example request


{
  id='f4194340454e1c54ecf5d77h88866105',
  href='https://rest.messagebird.com/hlr/f4194340454e1c54ecf5d77h88866105',
  msisdn=31612345678, network='null',
  reference='ExampleReadHlr reference',
  status='sent',
  createdDatetime=2015-04-19T19:03:34+00:00,
  statusDatetime=2015-04-19T19:03:34+00:00
}

Response

200 OK

Your platform should respond with a 200 OK HTTP header. When our platform doesn't receive a 200 OK header, we will try to delivery the receipt again (up to 10 times).

Balance

MessageBird provides an API to get the balance and balance information of your account.

URI

https://rest.messagebird.com/balance

Available http methods

GET /balance

The balance object

This object represents your balance at MessageBird.com

Attributes

attribute
type
description
payment
string
Your payment method. Possible values are: prepaid & postpaid
type
string
Your payment type. Possible values are: credits & euros
amount
string
The amount of balance of the payment type. When postpaid is your payment method, the amount will be 0.

Balance object example

{
  "payment": "prepaid",
  "type": "euros",
  "amount": 103
}

Get your balance

Retrieves your MessageBird balance.

Required parameters

No parameters are required.

Returns

Returns a balance object if the request was successful. If the request failed, an error object will be returned.

Definition

GET https://rest.messagebird.com/balance

cURL example request

$ curl -X GET https://rest.messagebird.com/balance \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Example response

{
  "payment": "prepaid",
  "type": "euros",
  "amount": 103
}

PHP example request

$MessageBird = new \MessageBird\Client('ACCESS_TOKEN');
$MessageBird->balance->read();

Example response

{
  'payment' => 'prepaid',
  'type' => 'euros',
  'amount' => 4929,
}

Ruby example request

client = MessageBird::Client.new(YOUR_ACCESS_KEY)
client.balance

Example response

#<MessageBird::Balance:0x007f8d5c83f478
 @amount=9,
 @payment="prepaid",
 @type="credits">

Go example request

balance, err := client.Balance()

Example response

&messagebird.Balance{
    Payment:"prepaid",
    Type:"credits",
    Amount:9,
    Errors:[]
}

C# example request

const string YourAccessKey = "YOUR_ACCESS_KEY";

Client client = Client.CreateDefault(YourAccessKey);
MessageBird.Objects.Balance balance = client.Balance();

Python example request

client = messagebird.Client(ACCESS_KEY)
balance = client.balance()

Example response

{
  'payment' : 'prepaid',
  'type' : 'euros',
  'amount' : 4929,
}

Java example request

import com.messagebird.MessageBirdClient;
import com.messagebird.MessageBirdService;
import com.messagebird.MessageBirdServiceImpl;
import com.messagebird.exceptions.GeneralException;
import com.messagebird.exceptions.NotFoundException;
import com.messagebird.exceptions.UnauthorizedException;
import com.messagebird.objects.Balance;

public class ExampleReadBalance {

    public static void main(String[] args) {

        if (args.length == 0) {
            System.out.println("Please specify your access key example : java -jar <this jar file≶ test_accesskey");
            return;
        }

        // First create your service object
        final MessageBirdService wsr = new MessageBirdServiceImpl(args[0]);

        // Add the service to the client
        final MessageBirdClient messageBirdClient = new MessageBirdClient(wsr);

        try {
            // Get Balance
            System.out.println("Retrieving your balance:");
            final Balance balance = messageBirdClient.getBalance();

            // Display balance
            System.out.println(balance.toString());

        } catch (UnauthorizedException unauthorized) {
            if (unauthorized.getErrors() != null) {
                System.out.println(unauthorized.getErrors().toString());
            }
            unauthorized.printStackTrace();
        } catch (GeneralException generalException) {
            if (generalException.getErrors() != null) {
                System.out.println(generalException.getErrors().toString());
            }
            generalException.printStackTrace();
        } catch (NotFoundException notFoundException) {
            if (notFoundException.getErrors() !=null) {
                System.out.println(notFoundException.getErrors().toString());
            }
            notFoundException.printStackTrace();
        }
    }
}

Example response

Balance{payment='prepaid', type='credits', amount=103}

SMPP Introduction

This SMPP documentation describes everything you need to know about the MessageBird SMPP server. It starts out with an overview of the available servers to connect to and the particulars that come with that, like how throughput is calculated and what security options are available. Then, a summary is given about the supported PDU types, followed by a description of the used and unused fields of the most commonly used PDU types.
It is assumed that you have a basic understanding of the SMPP protocol and that you know how to set up your own SMPP client software.

 

The SMPP servers

Server list

MessageBird has multiple SMPP servers for you to connect to. Each SMPP server offers the ability to connect to it via the regular (plaintext) method or via a TLS1.0 or better. Here is an overview of the available servers

Type
Hostname
Port
TLS port
primary
smpp01.messagebird.com
2775
2776
secondary
smpp02.messagebird.com
2775
2776

Username and password

Your username (system_id) and password will be given to you by your account manager at MessageBird. If you haven’t received those or you have yet to request one, please send an email to support@messagebird.com to request them.


Bindings and throughput

Whenever an SMPP account has been setup for you, you’ll receive the maximum amount of binds you’re allowed to set up as well as a maximum throughput. In most cases, these values will be something like 3 binds and 50 message per seconds.

It might be interesting to note that these values are enforced on a per-server basis. That means that given the above example, you can set up 6 binds in total with a throughput of 100 messages per second when you connect to both the primary and secondary server.

Be aware that for maintenance purposes we only guarantee either that either the primary or the secondary server is up.


Bindings and relaying

MessageBird’s message relaying system is connection and server agnostic. That means that when you send an MT via a submit_sm PDU on connection A, you might receive the matching DLR in the form of a deliver_sm on connection B if both connections are bound with the same username.
This is even true for connections made to different servers, so the above scenario would still be true if connection A is made to the primary server and connection B to the secondary server.


Security

If you connect to either server via a TLS connection, make sure you select TCP port 2776. Also be aware that the servers only accept an SSLv3 handshake method, so the old (legacy) SSLv2 handshake won’t work, even though your crypto stick plans to negotiate to use TLS1.0 or better.

 

Supported PDUs

The MessageBird SMPP servers support the following list of PDU types:

PDU name
command_id
bind_receiver
0x00000001
bind_transceiver
0x00000009
bind_transmitter
0x00000002
deliver_sm_resp
0x80000005
enquire_link
0x00000015
generic_nack
0x80000000
submit_sm
0x00000004
unbind
0x00000006
unbind_resp
0x80000006
 

bind PDU

An SMPP bind_receiver, bind_transceiver or bind_transmitter PDU request has a fixed set of fields. Most fields are irrelevant to us. In fact, we only read the system_id, password and interface_version fields and the rest is ignored.

Field name
Description
system_id
The username
password
The password
system_type
IGNORED
interface_version
The SMPP protocol version you want to talk
addr_ton
IGNORED
addr_npi
IGNORED
address_range
IGNORED

interface_version

The MessageBird SMPP server supports SMPP protocol version 3.3, 3.4 and 5.0, but please note that if you set your SMPP client to talk version 3.3 you are missing out on some features, most notably TLV information in the deliver_sm PDUs you receive.

 

submit_sm PDU

You can use the submit_sm PDU to send us your MT messages. Like a bind request, the submit_sm PDU request also has a couple of fields that are unused by our platform and can thus safely be ignored.

service_type
IGNORED
source_addr_ton
Type of number for source_addr
source_addr_npi
Numbering plan indicator for source_addr
source_addr
Address of message origin
dest_addr_ton
Type of number for destination_addr
dest_addr_npi
Numbering plan indicator for destination_addr
destination_addr
Address of message destination
esm_class
Message mode and type
protocol_id
IGNORED
priority_flag
IGNORED
schedule_delivery_time
IGNORED
validity_period
The validity period of this message
registered_delivery
The type if DLRs you want to receive
replace_if_present_flag
IGNORED
data_coding
The coding of the short_message field
sm_default_msg_id
IGNORED
sm_length
The length of short_message field
short_message
The contents of the MT

data_coding

The values for the data_coding field are not solidly declared in the SMPP spec, so each SMPP server is more or less required to give its own definition.

Value
Encoding
0
GSM7
1
ASCII
2
8BIT
3
ISO-8859-15 (LATIN9)
6
ISO-8859-5 (LATIN5)
7
ISO-8859-8 (LATIN8)
8
UTF-16BE (UCS2)
 

deliver_sm PDU

MOs and DLRs will be send to you via a deliver_sm PDU. The fields are exactly the same as a submit_sm PDU, but there will be differences in which fields you are free to ignore and which you are not.

Field
name Description
service_type
IGNORED
source_addr_ton
Type of number for source_addr
source_addr_npi
Numbering plan indicator for source_addr
source_addr
Address of message origin
dest_addr_ton
Type of number for destination_addr
dest_addr_npi
Numbering plan indicator for destination_addr
destination_addr
Address of message destination
esm_class
Message mode and type
protocol_id
IGNORED
priority_flag
IGNORED
schedule_delivery_time
IGNORED
validity_period
The validity period of this message
registered_delivery
IGNORED
replace_if_present_flag
IGNORED
data_coding
The coding of the short_message field
sm_default_msg_id
IGNORED
sm_length
The length of short_message field
short_message
The contents of the MT

data_coding

The values here are the same as in section submit_sm.


TLVs

DLR messages which are send to you as a deliver_sm may contain TLVs that you might be interested in. The following TLVs are supported as of the writing of this document:

Name
SMPP v5.0 spec reference
Description
message_state
4.7.15 and 4.8.4.37
The final message state for a delivery receipt
network_error_code
4.8.4.42
The actual network error code
receipted_message_id
4.8.4.47
The message_id referencing the same message_id that was returned in the submit_sm_resp of the MT

short_message

In the case of MO messages, the short_message field will contain the contents of the message that was sent. In the case of DLR messages, it will contain report information in the following format:

id:xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx sub:001
dlvrd:NNN submit date:YYMMDDHHMMSS
done date:YYMMDDHHMMSS stat:STATUS err:NNN text:

For example:
id:fecf8e26-eb1d-46e7-5bdf-e509c058f7b7 sub:001
dlvrd:001 submit date:141029064451
done date:141029064502 stat:DELIVRD err:000 text:


The id parameter references the message_id that was returned in the submit_sm_resp of your submit_sm and it has the same value as the receipted_message_id TLV.

The state parameter references the message_state TLV, although the message_state contains a number pointing to a state where the state parameter in the short_message is described by a word.

The err parameter references error codes in section 3.3.4 and is the same as the network_error_code TLV.


Error codes

The network_error_code TLV and the err parameter in a DLR’s short_message contains a number that references a specific error.

Error Code
Error Code Description
Intermediate or Permanent Status
0
EC_NO_ERROR
N/A
1
EC_UNKNOWN_SUBSCRIBER
Permanent
2
EC_UNKNOWN_BASE_STATION
Permanent
3
EC_UNKOWN_MSC
Intermediate
5
EC_UNIDENTIFIED_SUBSCRIBER
Intermediate
7
EC_UNKNOWN_EQUIPMENT
Intermediate
8
EC_ROAMING_NOT_ALLOWED
Intermediate
9
EC_ILLEGAL_SUBSCRIBER
Permanent
10
EC_BEARERSERVICE_NOT_PROVISIONED
Intermediate
11
EC_TELESERVICE_NOT_PROVISIONED
Intermediate
12
EC_ILLEGAL_EQUIPMENT
Intermediate
13
EC_CALL_BARRED
Intermediate
21
EC_FACILITY_NOT_SUPPORTED
Intermediate
26
EC_SUBSEQUENT_HANDOVER_FAILURE
Intermediate
27
EC_ABSENT_SUBSCRIBER
Intermediate
28
EC_ABSENT_SUBSCRIBER_NO_PAGE
Intermediate
29
EC_ABSENT_SUBSCRIBER_IMSI_DETACHED
Intermediate
30
EC_CONTROLLING_MSC_FAILURE
Intermediate
31
EC_SUBSCRIBER_BUSY_FOR_MT_SMS
Intermediate
32
EC_SM_DELIVERY_FAILURE
Intermediate
33
EC_MESSAGE_WAITING_LIST_FULL
Intermediate
34
EC_SYSTEM_FAILURE_1
Intermediate
35
EC_DATA_MISSING_1
Permanent
36
EC_UNEXPECTED_DATA_VALUE_1
Permanent
37
EC_SYSTEM_FAILURE_2
Permanent
38
EC_DATA_MISSING_2
Permanent
39
EC_UNEXPECTED_DATA_VALUE_2
Permanent
40
EC_MEMORY_CAPACITY_EXCEEDED
Intermediate
71
EC_UNKNOWN_ALPHABET
Permanent
72
EC_USSD_BUSY
Intermediate
 

Mail to SMS

With the Mail to SMS service, an e-mail message can be converted directly into a text message and send to the chosen mobile number. You can do this without any additional software, with any e-mail program.

Authentication

Authentication for sending messages through our Mail to SMS gateway is provided by your e-mail address. First, add your email address on the Mail to SMS settings page and configure it. After setting up your account, sending a text message is very easy.

Sending a message

You send an SMS by sending an e-mail to our system. You can use *telephonenumber*@sms.messagebird.com. Depending on your configuration on the Mail to SMS page, you can provide the originator through the subject and the message through the e-mail body.

Marking the beginning and end of the text message

If you do not want to send the total content of the e-mail as a text message, but only a part of it, you can do that by marking the beginning and the end of the text message in the e-mail with --begin and/or --end. You will find some examples below.

Sending to groups

It is also possible to send messages via Mail to SMS to a whole group in one go. The name of the group you want to send the message to can only contain letters, numbers and characters (so no spaces or special characters).

 

 

 

 

Example message

- Send a message from the email address that you provided
   on the Mail to SMS settings page.
- Send to: 31612345678@sms.messagebird.com
- For the subject, you fill in the originator
- Type the message you want to send

Mail client examples

Marking beginnen & end

Hi Donald, --begin This is the part of the message that is in the SMS message --end, Best regards.

Sending to a group

Send to: groupname@sms.messagebird.com
Send to: name-of-a-group@sms.messagebird.com