API Reference

OverviewSMSVoice CallingVoice MessagingConversations APIIntegrations APIFile Storage APIOmnichannel WidgetNumbersPartner AccountsVerifyMMSHLRBalanceLookupContactsGroupsIntentFAQNamed Entity RecognitionLanguage Detection

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.

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. See API Access Key Security for more information.

Example Request

curl -X GET https://rest.messagebird.com/balance -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'
curl -X GET 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 Addresses

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 Access Key Security

Given your API access key is your authentication token for using MessageBird's APIs, they need to be appropriately secured. One of the easiest ways to think of this is to treat your API access keys just like you would your passwords, including storing them securely and never sharing them with anyone.

One of the most common mistakes that is made with API keys is to inadvertently check them into public repositories on platforms such as GitHub. From here, fraudsters can find and steal your API access key and then use it to send Spam messages and also drain your account balance. There are numerous techniques to avoid this, however storing your API access key in an environment variable, passing them as command line arguments or using a secrets manager can all help to prevent this from occurring. The main takeaway is don't hard-code your API access key and don't check it into a public code repository.

In a similar manner, sharing code snippets on platforms such as PasteBin, GitHub Gists or StackOverflow can inadvertently leak your API access key so ensure that you and your developers are aware of this risk.

MessageBird also takes measures on our side to help detect and mitigate compromised API access keys, however prevention is the best medicine so please ensure you protect your API access keys.

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
100Service unavailable
101Duplicate entry
102Ambiguous lookup

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"}]}

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).

Please keep in mind that the rundown below applies to all our services apart from our Voice Calling API Dynamic Call Flows, where the signature validation process is slightly different.

Notification icon

You can conduct a live test via Flow Builder. Please do not use the "Test" Flow Simulator as it does not invoke an HTTP Request to your endpoint.

What is request signing?

For each HTTP request that MessageBird sends, a MessageBird-Signature-JWT header is added.

The MessageBird-Signature-JWT header is a signature that consists of all the information that is required to verify the integrity of the request. The signature is generated from the request URL and request body and is signed with the HMAC-SHA256 algorithm using your your signing key. You can validate this signature using our SDKs (see signature usage) to ensure that the request is valid and unaltered. The token also includes timestamp claims that allow you to prove the time of the request, protecting from replay attacks and the like. Easy!

Notification icon

MessageBird-Signature and MessageBird-Request-Timestamp headers are being deprecated in favor of the MessageBird-Signature-JWT header. We recommend that you update your request validation to ensure better security.

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.

Signature details

The MessageBird-Signature-JWT header is a JWT token consisting of three sections: header, payload, and signature.

  • Header:
    • typ - is the type of the token, which is always JWT.
    • alg - is the algorithm that the token is signed with, HS256 reprensents HMAC-SHA256 algorithm.
  • Payload (claims):
    • iss - is the issuer of the token, which is always MessageBird.
    • nbf - is the UNIX timestamp in seconds, after which the token becomes valid.
    • exp - is the UNIX timestamp in seconds, after which the token becomes invalid.
    • jti - is a unique ID that you can use to detect replay attacks.
    • url_hash - is a hex-encoded SHA256 hash of the canonicalized URL that the webhook was sent to.
    • payload_hash - is a hex-encoded SHA256 hash of the payload of the HTTP body.
  • Signature

When handling the token without the help of our SDKs, make sure you always validate the header alg as HS256 and all the above claims. If either the url_hash or payload_hash claim checks are skipped, no query parameters or request body should be trusted.

Signature usage

Examples

use MessageBirdExceptionsValidationException;
use MessageBirdRequestValidator;
// requestSignature is the value of the 'MessageBird-Signature-JWT' HTTP header.
$requestSignature = 'JWT_TOKEN_STRING';
$requestURL = 'https://yourdomain.com/path?query=2';
$requestBody = '{"foo":"bar"}';
$validator = new RequestValidator('YOUR_SIGNING_KEY');
try {
$validator->validateSignature($requestSignature, $requestURL, $requestBody);
} catch (ValidationException $e) {
// The request is invalid, so respond accordingly.
http_response_code(412);
}

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.

Questions?

We’re always happy to help with code or other doubts you might have! Check out our Quickstarts, API Reference, Tutorials, SDKs, or contact our Support team.

Cookie Settings