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.

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

Required Parameters

Parameter Description
src The phone number to be used as the caller id (with the country code). For e.g. a USA number, 15671234567. If you're sending messages to U.S. and Canada, you need to use the numbers you purchased with Plivo.
dst The number to which the message needs to be sent. Regular phone numbers must be prefixed with the country code but without the ‘+’ sign. For e.g, a USA phone number would be, 15677654321, with '1' denoting the country code.
You can send a message to multiple destination numbers by using a delimiter < in a single API call. For e.g. 15677654321<12077657621<12047657621.
text The text to send encoded in Unicode UTF-8. The API accepts up to 1000 bytes of UTF-8 encoded text in a single API request. The text will be automatically split into multiple parts and sent if it will not fit into a single SMS. See notes below for more details.

Optional Parameters

Parameter Description
type The type of message. Should be 'sms' for a text message. Defaults to 'sms'.
url The URL to which with the status of the message is sent. The following parameters are sent to the URL:
  • To - receiver number of the SMS
  • From - sender number of the SMS
  • Status - status value of the message, is one of "queued", "sent", "failed", "delivered", "undelivered" or "rejected"
  • MessageUUID - a unique ID for the message
  • ParentMessageUUID - ID of the first part (see notes about long SMS below)
  • PartInfo - Specifies sequence information (useful for split parts in a long SMS; see notes about long SMS below)
method The method used to call the url. Defaults to POST.
log 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) Defaults to true.

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.

Response

HTTP Status: 202

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

Get All Message Recordings

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

Parameters

Parameter Description
limit Used to display the number of results per page. The maximum number of results that can be fetched is 20.
offset 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: 200

JSON:
{
  "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 a Specific Message Recording

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

Parameters

There are no parameters required for this API call.

Response

HTTP Status: 200

JSON:
{
"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
}