Messagebird General

Overview

Messagebird develop document 내용 정리

Introduction

The MessageBird APIs connect your website or application to operators around the world. With our APIs you can integrate SMS, Chat & Voice.

REST

The MessageBird API uses HTTP verbs and a RESTful endpoint structure. An access key is used as the API Authoriiztion 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.

GET STARTED

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

MessageBird provides the creation of the keys to discover and test the API at your own convenience. The difference between a live key and a test key is that a live key actually 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 platform is offered from a global distributed infrastructure. Hence you will not be able to whitelist the IP-addresses of our platform. Requests from our platform (for delivery reports and inbound messages) originate from various IP-addresses.

Authentication

When 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 API 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.

• PARAMETER

Authorization : 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'

{"payment":"prepaid","type":"credits","amount":10.1}

• EXAMPLE(GET)

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

{"payment":"prepaid","type":"credits","amount":10.1}

If possible, please use the Authorization header.

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(See alternatives).

• JSON REQUEST PAYLOAD EXAMPLE

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

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

description : 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 successfully created.

204 No Content : The requested resources are empty.

401 Unauthorized : The access key was incorrect.

404 Not found : The resources can not 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.

21 : Bad request.

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 occurred error.

$ curl -X POST https://rest.messagebird.com/messages -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' -d "recipients=31612345678" -d "originator=YourName"

{"errors":[{"code":9,"description":"body is required","parameter":"body"}]}

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&msisdn=31612345678&...

• REQUESTING AN HLR

/hlr?_method=POST&msisdn=31612345678&...