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 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 (mandatory) 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. Multiple numbers can be added by using a delimiter. For e.g. 15677654321<12077657621<12047657621.
text (mandatory) 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.
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 - 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 (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) Defaults 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
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
}