Messagebird APIs SmsMessaging

From 탱이의 잡동사니
Revision as of 07:56, 8 October 2018 by Pchero (talk | contribs)
Jump to navigation Jump to search

Overview

Meessagebird API SMS messaging 내용 정리

Basic

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
GET /messages/{messageId}
DELETE /messages/{messageID}

List message

To list all messages sent and received with your account, you can do a GET request on the /messages endpoint.

  • URI
https://rest.messagebird.com/messages
  • FILTERS

Besides listing all messages, the API also provides some filters that can be used as query parameters.

Attribute : Type : Description
originator : string : Display messages by the specified originator.
recipient : string : Display messages for the specified recipient.
direction : string : Display either mt(sent) or mo(received) messages.
limit : int : Limit the amount of messages listed.
offset : int : Skip the first n results.
searchterm : string : Display messages including the specified searchterm.
type : string : Display messages of type sms, binary or flash.
contact_id : int : Display messages by contact_id. See Contacts API for more info.
status : string : Display messages with status scheduled, sent, buffered, delivered, expired or delivery failed.
from : datetime : Display messages starting from the specified date in RFC 3339 format(Y-m-d\TH:i:sP).
until : datetime : Display messages until the specified date in RFC 3339 format(Y-m-d\TH:i:sP).
  • EXAMPLE
curl -X GET https://rest.messagebird.com/messages\?access_key\=test_gshuPaZoeEG6ovbc8M79w0QyM

{"offset":0,"limit":20,"count":0,"totalCount":0,"links":{"first":null,"previous":null,"next":null,"last":null},"items":[]}

The message object

This object represents a message at MessageBird.com

  • ATTRIBUTES
Attribute : Type : Description
id : string : A 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 obje ct.
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 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. You can set a default originator in your account or use inbox to use the Sticky VMN feature.
body : string : The body of the SMS message.
reference : string : A client reference.
reportUrl : string : The status report URL to be used on a per-message basis. reference is required for a status report webhook to be sent.
validity : integer : The amount of seconds that the message is valid. If 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. Further explanation in the table below.
datacoding : string : The datacoding used, can be plain(GSM 03.38 characters only), unicode(contains non-GSM 03.38 characters) or auto, we will set unicode or plain depending on the body content.
Using unicode will the maximum number of charaters to 70 instead of 160. If message character size exceeds the limit, messages will be concatenated, resulting in separately billed messages.
mclass : integer : Indicated the message type. 1 is a normal message, 0 is a flash message. (0 - 3 are valid values)
scheduledDatetime : datetime : The scheduled date and time of the message in RFC 3339 format(Y-m-d\TH:i:sP).
createdDatetime : datetime : The date and time of the creation of the message in RFC 3339 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, expired and delivery_failed.
items[].statusDatetime : datetime : The datum time of the last status in RFC 3339 format(Y-m-d\TH:i:sP).
  • THE TYPEDETAIL ARRAY
Attribute : Type : Description
udh : string : The UDH to prepend to the message payload. This can be used for sending concatenated SMS. Often required to send binary messages.
  • 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":"2016-04-29T09:42:26+00:00",
  "recipients":{
    "totalCount":1,
    "totalSentCount":1,
    "totalDeliveredCount":0,
    "totalDeliveryFailedCount":0,
    "items":[
      {
        "recipient":31612345678,
        "status":"sent",
        "statusDatetime":"2016-04-29T09:42:26+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":"2016-04-29T09:42:26+00:00",
  "recipients":{
    "totalCount":2,
    "totalSentCount":1,
    "totalDeliveredCount":1,
    "totalDeliveryFailedCount":0,
    "items":[
      {
        "recipient":31612345678,
        "status":"sent",
        "statusDatetime":"2016-04-29T09:42:26+00:00"
      },
      {
        "recipient":31612345679,
        "status":"delivered",
        "statusDatetime":"2016-04-29T09:42:26+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.

  • STICKY VMN
Sticky VMN's are only available in the US, Canada, Netherlands and United Kingdom. Because there are no capacity limits in other countries, you won't need multiple VMNs.

Whether you're using a pool of dedicated VMNs or our shared VMN pool, you'd like the recipient to always receive your messages from the same VMN as a sender. Our Sticky-VMN-as-a-Sender service makes this possible. Simply use inbox as the originator when sending messages to our API. This will tigger our system to select a random VMN(dedicated or shared - depending on what's available) for the first message and ensure that the selected VMN be reused for all following messages.

  • REQUIRED PARAMETERS
Parameter : Type : Description
originator : string : The sender of the message. This can be 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 SMS message. Required.
recipients : array : The array of recipients msisdn. Note: can also contain grouplds. Required.
  • OPTIONAL PARAMETERS
Parameter : Type : Description
type : string : The type of message. Values can be sms, binary or flash. Default:sms
reference : string : A client reference.
reportUrl : string : The status report URL to be used on a per-message basis. reference is required for a status report webhook to be sent.
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 message is sent.
datacoding : string : Use plain when the body contains only GSM 03.38 characters, or you want non GSM 03.38 characters to be replaced. Use unicode to be able to send all characters. If you set auto, we will set unicode or plain depending on the body content.
Using unicode will limit the maximum number of characters tot 70 instead of 160. If message character size exceeds the limit, messages will be concatenated, resulting in separately billed messages. 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 RFC 3339 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.l

  • DEFINITION
POST https://rest.messagebird.com/messages
  • CURL EXAMPLE
$ 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"

{
    "body": "This is a test message",
    "createdDatetime": "2018-10-05T12:17:27+00:00",
    "datacoding": "plain",
    "direction": "mt",
    "gateway": 2,
    "href": "https://rest.messagebird.com/messages/cc500a6103dc45d681cfa221f0a28be3",
    "id": "cc500a6103dc45d681cfa221f0a28be3",
    "mclass": 1,
    "originator": "YourName",
    "recipients": {
        "items": [
            {
                "recipient": 31612345678,
                "status": "sent",
                "statusDatetime": "2018-10-05T12:17:27+00:00"
            }
        ],
        "totalCount": 1,
        "totalDeliveredCount": 0,
        "totalDeliveryFailedCount": 0,
        "totalSentCount": 1
    },
    "reference": null,
    "scheduledDatetime": null,
    "type": "sms",
    "typeDetails": {},
    "validity": null
}

Receive a message

  • ON A VIRTUAL MOBILE NUMBER(VMN)

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

  • ATTRIBUTES
Attribute : Type : Description
id : string : A unique random ID which is created on the mMessageBird 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 RFC 3339 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=2016-05-03T14:26:57+00:00
  • RESPONSE
200 OK

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

  • ON A SHORTCODE

Incoming messages from an end user to - a(sub)keyword at - a shortcode are received through a configured callback URL(configurable per keyword/shortcode). The message attributes are sent through a GET request by default but the method can be configured per keyword.

  • ATTRIBUTES
Attribute : Type : Description
mid : integer : A unique random ID which is created on the MessageBird platform.
shortcode : string : The shortcode that received the message.
keyword : string : The keyword that matched the message.
originator : string : The sender of the message(end user).
operator : integer : The operator of the sender of the message(MCC/MNC).
message : string : The body of the SMS message. including the sub(keyword).
receive_datetime : datetime : The date and time when the message was received at shortcode in format: (Y-m-d\TH:i:sP)
  • EXAMPLE REQUEST








Retrieved from "http://wiki.pchero21.com/index.php?title=Messagebird_APIs_SmsMessaging&oldid=3004"