MessageBird API Reference

Dive into our full API Reference Documentation and seamlessly integrate SMS, Chat, Voice functionalities into your website or application with the MessageBird APIs.

MessageBird's APIs use 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), using UTF-8 encoding and URL encoded values.

// In this column you view the code examples.
// Pick one of our APIs from the sidebar on the left and start coding.

SDKs

Official SDK libraries for MessageBird's APIs are available in several languages.

API Endpoint

In order to use MessageBirds APIs, you need to first sign up for free at www.messagebird.com.

API Endpoint

https://rest.messagebird.com/

Authentication

MessageBird's APIs use API keys to authenticate requests. You can create, retrieve, and manage your API keys in your MessageBird Dashboard.

Test API keys have the prefix test_ and live API keys don't require a prefix.

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

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

Notification icon

Your API keys carry significant privileges. Please ensure to keep them 100% secure and be sure to not share your secret API keys in areas that are publicly accessible like GitHub.

Example Request

curl https://rest.messagebird.com/balance -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'
curl https://rest.messagebird.com/balance?access_key=test_gshuPaZoeEG6ovbc8M79w0QyM
If possible, please use the Authorization header.
ParametersDescription
AuthorizationWhen calling our API, send your access key with the authentication type set as AccessKey (Example: Authorization: AccessKey {accessKey}). Required.
AcceptSet to application/json. Required.

IP-address

Our API platform is offered from a globally distributed infrastructure, so you won't be able to whitelist the IP-addresses of our platform. Keep in mind that request for delivery reports and inbound messages originate from various IP-addresses.

API Errors

MessageBird uses standard HTTP status codes to indicate the success or failure of an API request. Generally speaking, codes in the 2xx range indicate that a request was successfully processed and codes in the 4xx range indicate that there was an error that resulted from the information provided (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.

AttributesDescription
codeAn integer that represents the error type.
descriptionA human-readable description of the error. You can provide your users with this information to indicate what they can do about the error.
parameterThe parameter in your request that is related to the error if the error is parameter specific.
HTTP Status CodesDescription
200 FoundWe found the request resource
201 CreatedThe resource is successfully created
204 No ContentThe requested resources is empty
401 UnauthorizedThe access key was incorrect
404 Not foundThe resources cannot be found
405 Method Not AllowedThe method is not allowed
408 Request TimeoutThe request is taking too long to respond
422 Unprocessable EntityThe resource couldn't be created
5xx Something went wrong on our endPlease try again
Error codesDescription
2Request not allowed
9Missing params
10Invalid params
20Not found
21Bad request
25Not enough balance
98API not found
99Internal error

Error handling

The error object will give you information about the error makes it easier to fix.

Error Object

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

Error Handling

curl -X POST https://rest.messagebird.com/messages
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'
-d "recipients=31612345678"
-d "originator=YourName"
-d "body="{"errors":[{"code":9,"description":"body is required","parameter":"body"}]}

SMS Errors

In addition to the base status errors, there are also SMS error codes - also called extended error codes. These codes are reported as part of the HTTP status report or in the SMPP deliver_sm delivery report.

Via SMPP

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

Via HTTP

The error code is reported as value of the statusErrorCode variable. This variable is only given when the data is available.

SMS Error codes

CodeDescriptionStatus
0EC_NO_ERRORN/A
1EC_UNKNOWN_SUBSCRIBERPermanent
2EC_UNKNOWN_BASE_STATIONPermanent
3EC_UNKOWN_MSCIntermediate
5EC_UNIDENTIFIED_SUBSCRIBERIntermediate
7EC_UNKNOWN_EQUIPMENTIntermediate
8EC_ROAMING_NOT_ALLOWEDIntermediate
9EC_ILLEGAL_SUBSCRIBERPermanent
10EC_BEARERSERVICE_NOT_PROVISIONEDIntermediate
11EC_TELESERVICE_NOT_PROVISIONEDIntermediate
12EC_ILLEGAL_EQUIPMENTIntermediate
13EC_CALL_BARREDIntermediate
21EC_FACILITY_NOT_SUPPORTEDIntermediate
26EC_SUBSEQUENT_HANDOVER_FAILUREIntermediate
27EC_ABSENT_SUBSCRIBERIntermediate
28EC_ABSENT_SUBSCRIBER_NO_PAGEIntermediate
29EC_ABSENT_SUBSCRIBER_IMSI_DETACHEDIntermediate
30EC_CONTROLLING_MSC_FAILUREIntermediate
31EC_SUBSCRIBER_BUSY_FOR_MT_SMSIntermediate
32EC_SM_DELIVERY_FAILUREIntermediate
33EC_MESSAGE_WAITING_LIST_FULLIntermediate
34EC_SYSTEM_FAILUREIntermediate
35EC_DATA_MISSINGPermanent
36EC_UNEXPECTED_DATA_VALUEPermanent
37EC_SYSTEM_FAILUREPermanent
38EC_DATA_MISSINGPermanent
39EC_UNEXPECTED_DATA_VALUEPermanent
40EC_UNEXPECTED_DATA_VALUEIntermediate
71EC_UNKNOWN_ALPHABETPermanent
72EC_USSD_BUSYIntermediate
101EC_SUBSCRIBER_INSUFFICIENT_BALANCEIntermediate

Requests

POST and PUT requests to the API should contain a JSON-formatted payload in the request body. Alternatively, resource attributes can be sent through GET parameters.

JSON request payload example

{
"recipients": 31612345678,
"originator": "MessageBird",
"body": "The message to be sent"
}

HTTP Methods

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 to do a POST or DELETE, we provide the ability to set the method through the query parameter _method.

Alternatively, resource attributes can be sent through GET attributes instead of a JSON body.

Sending a message

/messages?_method=POST&...

Requesting an HLR

/hlr?_method==POST&...

Verifying HTTP requests

We sign our HTTP requests to allow you to verify that they actually came from us (authentication) and that they haven't been altered along the way (integrity).

Notification icon

The rundown below applies to all our services apart from our Voice platform, where the validation process is slightly different.

What is request signing?

For each HTTP request that MessageBird sends, a MessageBird-Signature and MessageBird-Request-Timestamp header is added.

The 'MessageBird-Signature' consists of a HMAC-SHA256 keyed hash generated from the request body and your signing key. You can then compute a signature in your implementation based on the request, and compare both to ensure the request is valid and unaltered. The MessageBird-Request-Timestamp allows you to prove the time of the request, protecting from replay attacks and the like. Easy!

How to implement this in your application:

  1. First, login to your Dashboard account and retrieve your signing key.
  2. In your HTTP request handler make sure that you read the MessageBird-Signature and MessageBird-Request-Timestamp headers.
  3. Check that request was issued recently by parsing the timestamp, which is formatted in Unix Epoch time.
  4. Deserialize the signature bytes from the MessageBird-Signature header value by base64 decoding it.
  5. Calculate the SHA256 hash sum of the request body..
  6. Generate the HMAC-SHA256 signature by concatenating the timestamp, query params (in lexicographical order) and body hash sum, separated by \\n.

What if my signing secret has been compromised?

If your secret has been leaked, don't panic. You can easily regenerate your secret at any time via your MessageBird Dashboard by clicking on the 'Regenerate' blue button.

Pseudocode example

signature = HMAC_SHA_256(
TIMESTAMP + \n + QUERY_PARAMS + \n + SHA_256_SUM(BODY),
signing_key
)
if HMAC_EQUALS(signature, BASE_64_DECODE(request_signature)) {
// Yay!
}

Example (Go)

func sign(timestamp, queryParams string, body []byte, key string) []byte {
var buf bytes.Buffer
buf.WriteString(timestamp)
buf.WriteRune('\n')
buf.WriteString(queryParams)
buf.WriteRune('\n')
hash := sha256.Sum256(body)
buf.Write(hash[:])
mac := hmac.New(sha256.New, []byte(key))
mac.Write(buf.Bytes())
return mac.Sum(nil)
}
actualSignature, err := base64.StdEncoding.DecodeString(reqSignature)
if err != nil {
// handle error
}
signature := sign(timestamp, queryParams, body, signingKey)
if hmac.Equal(signature, expectedSignature) {
// OK
}

SMPP

The SMPP documentation describes everything you need to know about the MessageBird SMPP server. Keep in mind that it's important for you to already have a basic understanding of the SMPP protocol and to 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, a TLS1.0, or better connection.

Here is an overview of the available servers:

HostnamePortTLS port
smpp01.messagebird.com27752776
smpp02.messagebird.com27752776
smpp03.messagebird.com27752776

Username and password

Your account manager at MessageBird will give you a username (system_id) and password. If you haven’t received them yet or you still need to make the request, simply send us an email to support@messagebird.com; we'll be happy to help you out.

Bindings and throughput

Whenever an SMPP account has been set up for you, you’ll receive the maximum amount of binds and throughput. In most cases, these values will be something like 3 binds and 50 messages per second.

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 9 binds in total with a throughput of 150 messages per second when you connect to all servers.

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 9 binds in total with a throughput of 150 messages per second when you connect to all servers.

Keep in mind that for maintenance purposes we only guarantee either that one server is up at any given time, so we advise you to connect to all of them.

Bindings and relaying

MessageBird’s message relaying system is connection and server agnostic, so 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 this scenario is also possible if connection A is made to the smpp01 server and connection B to the smpp02 server.

Security

If you connect to either server via a TLS connection, make sure to 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 namecommand_id
bind_receiver0x00000001
bind_transceiver0x00000009
bind_transmitter0x00000002
deliver_sm_resp0x80000005
enquire_link0x00000015
generic_nack0x80000000
submit_sm0x00000004
unbind0x00000006
unbind_resp0x80000006

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; actually, we only read the system_id, password, and interface_version fields and the rest is ignored.

Field nameDescription
system_idThe username
passwordThe password
system_typeIGNORED
interface_versionThe SMPP protocol version you want to talk
addr_tonIGNORED
addr_npiIGNORED
address_rangeIGNORED

interface_version

The MessageBird SMPP server supports SMPP protocol version 3.3, 3.4, and 5.0. Keep in mind 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 safely be ignored.

service_typeIGNORED
source_addr_tonType of number for source_addr
source_addr_npiNumbering plan indicator for source_addr
source_addrAddress of message origin
dest_addr_tonType of number for destination_addr
dest_addr_npiNumbering plan indicator for destination_addr
destination_addrAddress of message destination
esm_classMessage mode and type
protocol_idIGNORED
priority_flagIGNORED
schedule_delivery_timeIGNORED
validity_periodThe validity period of this message
registered_deliveryThe type if DLRs you want to receive
replace_if_present_flagIGNORED
data_codingThe coding of the short_message field
sm_default_msg_idIGNORED
sm_lengthThe length of short_message field
short_messageThe 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. Below is a list of data codings that we accept as input. Keep in mind that only the values of 0, 2 and 8 are used as-is, other values will be converted to the most appropriate encoding out of 0, 2 and 8 to ensure acceptance of your messages by the operators.

ValueEncoding
0GSM7
1ASCII
28BIT
3ISO-8859-15 West European languages (Latin-9)
6ISO-8859-5 Latin/Cyrillic
7ISO-8859-8 Latin/Hebrew
8UTF-16BE (UCS2)

deliver_sm PDU

MOs and DLRs will be sent 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.

FieldName Description
service_typeIGNORED
source_addr_tonType of number for source_addr
source_addr_npiNumbering plan indicator for source_addr
source_addrAddress of message origin
dest_addr_tonType of number for destination_addr
dest_addr_npiNumbering plan indicator for destination_addr
destination_addrAddress of message destination
esm_classMessage mode and type
protocol_idIGNORED
priority_flagIGNORED
schedule_delivery_timeIGNORED
validity_periodThe validity period of this message
registered_deliveryIGNORED
replace_if_present_flagIGNORED
data_codingThe coding of the short_message field
sm_default_msg_idIGNORED
sm_lengthThe length of short_message field
short_messageThe contents of the MT

data_coding

The values here are the same as in section submit_sm.

tlvs

DLR messages which are sent 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:

NameTag IDDescription
receipted_message_id0x001EThe message_id referencing the same message_id that was returned in the submit_sm_resp of the MT (SMPP v5.0 spec: 4.8.4.47)
message_state0x0427The final message state for a delivery receipt (SMPP v5.0 spec: 4.7.15 and 4.8.4.37)
network_error_code0x0423The actual network error code (SMPP v5.0 spec: 4.8.4.42)
network_mccmnc *0x1560Operator MCCMNC of recipient MSISDN of related SMS; given when available.

TLVs marked with * are custom MessageBird SMPP tags.

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.

Start building

Explore the MessageBird Docs, SDKs, and Developer Tutorials in your favorite programming languages.

If you have any questions, don’t hesitate to let us know at support@messagebird.com; we’re here to help.

cURL
PHP
Node
C#
Java
Ruby
Go
Python
Cookie Settings