Message

The following actions can be performed with the Message API.

BaseURI https://api.plivo.com/v1/Account/{auth_id}/Message/

Send a Message

This API enables you to send messages via Plivo’s SMS service. The API supports Unicode UTF-8 encoded texts, so you can send messages in any language. The API also handles long SMS automatically by splitting it into standard SMS sized chunks and sending them. Delivery reports are automatically supported in networks where they are provided by the operator.

POST https://api.plivo.com/v1/Account/{auth_id}/Message/

Arguments

Parameter Description
src (mandatory) The phone number that will be shown as the sender ID. Be sure that all phone numbers include country code, area code, and phone number without spaces or dashes (e.g., 14153336666). Note that a Plivo phone number is required for sending messages to the U.S. or Canada. You can buy a Plivo number from the Buy Numbers tab on your Plivo account dashboard.
dst (mandatory) The number to which the message will be sent. Be sure that all phone numbers include country code, area code, and phone number without spaces or dashes (e.g., 14153336666). To send messages to multiple numbers, separate your destination phone numbers with the delimiter "<" (e.g., 14156667777<14157778888<14158889999).
text (mandatory) The text message that will be sent. The API will encode the text in Unicode UTF-8 and accepts up to 1000 bytes of UTF-8 encoded text in a single API request. The text will be automatically split into multiple messages and sent separately if the message exceeds the size limit. See notes below for more details.
type (optional) The type of message. Should be `sms` for a text message. Defaults to `sms`.
url (optional) The URL to which with the status of the message is sent. The following parameters are sent to the URL:
  • To - phone number of the recipient
  • From - phone number of the sender
  • Status - status of the message including "queued", "sent", "failed", "delivered", "undelivered" or "rejected"
  • MessageUUID - the unique ID for the message
  • ParentMessageUUID - ID of the parent message (see notes about long SMS below)
  • PartInfo - specifies the sequence of the message (useful for long messages split into multiple text messages; see notes about long SMS below)
method (optional) The method used to call the url. Defaults to POST.
log (optional) If set to false, the content of this message will not be logged on the Plivo infrastructure and the dst value will be masked (e.g., 141XXXXX528). Default is set to true.

Response

HTTP Status Code: 202

{
    "message": "message(s) queued",
    "message_uuid": ["db3ce55a-7f1d-11e1-8ea7-1231380bc196"],
    "api_id": "db342550-7f1d-11e1-8ea7-1231380bc196"
}

Long SMS

A standard SMS contains at most 160 bytes. However, most mobile handsets support displaying longer messages. Plivo’s API supports sending long SMS to supported carriers and handsets.

Information about split SMSes are sent to the url and are also reported in the Message Logs in the Account Dashboard. The ParentMessageUUID is the same in all split parts and is the same as the UUID of the first part of the message. The PartInfo field specifies the sequence number of the part with strings of the form “1 of 2”, “2 of 2”, etc.

Unicode or Multilingual SMS

Plivo API’s supports sending SMS in languages other than English by encoding them in Unicode UTF-8. All Plivo helpers take care of encoding to UTF-8 as needed.

A single SMS can contain only up to 70 Unicode characters. SMS more than 70 Unicode characters, is automatically split as a long SMS.

Delivery Reports

Delivery reports are automatically supported in destination locations/networks where they are provided by the operator. When delivery reports are received, the “Status” value of a message is updated from “sent” to one of “delivered”, “undelivered”, or “rejected”. This status change is also sent to the url.

Billing

Each split part in a long SMS is considered a separate SMS, and is billed at the same rate as a normal SMS to the same destination.


Get Details of All Messages

GET https://api.plivo.com/v1/Account/{auth_id}/Message/

Arguments

Parameter Description
subaccount (optional) The id of the subaccount, if message details of the subaccount is needed.
message_direction (optional) Filter the results by message direction. The valid inputs are inbound and outbound.
message_time (optional) Filter out messages according to the time of completion. The filter can be used in the following five forms:
  • message_time: The format expected is YYYY-MM-DD HH:MM[:ss[.uuuuuu]]. Eg:- To get all messages that were sent/received at 2012-03-21 11:47[:30], use message_time=2012-03-21 11:47[:30]
  • message_time__gt: gt stands for greater than. The format expected is YYYY-MM-DD HH:MM[:ss[.uuuuuu]]. Eg:- To get all messages that were sent/received after 2012-03-21 11:47, use message_time__gt=2012-03-21 11:47
  • message_time__gte: gte stands for greater than or equal. The format expected is YYYY-MM-DD HH:MM[:ss[.uuuuuu]]. Eg:- To get all messages that were sent/received after or exactly at 2012-03-21 11:47[:30], use message_time__gte=2012-03-21 11:47[:30]
  • message_time__lt: lt stands for lesser than. The format expected is YYYY-MM-DD HH:MM[:ss[.uuuuuu]]. Eg:- To get all messages that were sent/received before 2012-03-21 11:47, use message_time__lt=2012-03-21 11:47
  • message_time__lte: lte stands for lesser than or equal. The format expected is YYYY-MM-DD HH:MM[:ss[.uuuuuu]]. Eg:- To get all messages that were sent/received before or exactly at 2012-03-21 11:47[:30], use message_time__lte=2012-03-21 11:47[:30]
Note: The above filters can be combined to get messages that were sent/received in a particular time range. The timestamps need to be UTC timestamps.
message_state (optional) Status value of the message, is one of "queued", "sent", "failed", "delivered", "undelivered" or "rejected"
limit (optional) Used to display the number of results per page. The maximum number of results that can be fetched is 20.
offset (optional) Denotes the number of value items by which the results should be offset. Eg:- If the result contains a 1000 values and limit is set to 10 and offset is set to 705, then values 706 through 715 are displayed in the results. This parameter is also used for pagination of the results.

Response

HTTP Status Code: 200

{
  "meta": {
    "previous": null,
    "total_count": 2,
    "offset": 0,
    "limit": 20,
    "next": null
  },
  "api_id": "40b5a864-58cb-11e1-86da-adf28403fe48",
  "objects": [
    {
      "cloud_rate": "0.00000",
      "carrier_rate": "0.00800",
      "message_direction": "outbound",
      "to_number": "15551112200",
      "message_state": "failed",
      "total_amount": "0.00800",
      "from_number": "155588877766",
      "message_uuid": "c02600f8-b938-11e1-8ea7-12313806be9a",
      "message_time": "2012-06-18T11:28:40",
      "resource_uri": "/v1/Account/MAYUUUDMMJNJM2ZYU/Message/c02600f8-b938-11e1-8ea7-12313806be9a/",
      "message_type": "sms",
    },
    {
      "cloud_rate": "0.00000",
      "carrier_rate": "0.00800",
      "message_direction": "outbound",
      "to_number": "15551112200",
      "message_state": "failed",
      "total_amount": "0.00800",
      "from_number": "155588877766",
      "message_uuid": "c02600f8-b938-11e1-8ea7-12313806be9a",
      "message_time": "2012-06-18T11:28:40",
      "resource_uri": "/v1/Account/MAYUUUDMMJNJM2ZYU/Message/c02600f8-b938-11e1-8ea7-12313806be9a/",
      "message_type": "sms",
    }
  ]
}

Get Details of a Single Message

 GET https://api.plivo.com/v1/Account/{auth_id}/Message/{message_uuid}/

Arguments

None

Response

HTTP Status Code: 200

{
    "from_number" : "525549998243",
    "message_direction" : "outbound",
    "message_state" : "delivered",
    "message_time" : "2014-02-12 00:35:19+00:00",
    "message_type" : "sms",
    "message_uuid" : "8cec3fe2-937d-11e3-944e-1231400195a3",
    "resource_uri" : "/v1/Account/MAOGE1YWFHNGFIMZI2MG/Message/8cec3fe2-937d-11e3-944e-1231400195a3/",
    "to_number" : "525549998272",
    "total_amount" : 0.06000,
    "total_rate" : 0.06000,
    "units" : 1
}