Messagebird APIs SmsMessaging

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

Overview

Meessagebird API 내용 정리

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