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 1600 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)
  • TotalRate - Total rate per sms
  • TotalAmount - Total cost of sending the sms (TotalRate * Units)
  • Units - Number of units into which a long SMS was split
  • MCC - Mobile Country Code (see here for more details)
  • MNC - Mobile Network Code (see here for more details)
  • ErrorCode - Delivery Response code returned by the carrier attempting the delivery. See Supported error codes 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 characters. However, most mobile handsets support displaying longer messages. Plivo’s API supports sending long SMS to supported carriers and handsets. Messages longer than 160 characters are split into 153 character chunks and concatenated by the mobile operator into one long message.

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. A message longer than 70 Unicode characters is automatically split into 67 character chunks 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.
error_code (optional) Delivery Response code returned by the carrier attempting the delivery. See Supported error codes below.

Standard Plivo Error Codes

Error Code Error Reason Description
10 Invalid message The message content is blank or exceeds the character limit of 1600 for messages encoded with GMS and 737 for messaged encoded with Unicode. Note that while we provide a separate error code to indicate if a message is too long, some carriers only send an “invalid message” error and don’t differentiate between blank messages and long message errors.
20 Network error The carrier delivering the text message had network issues. To resolve this, you can retry at a later time when the carrier network is unaffected.
30 Spam detected One of the most common reasons for SMS delivery failure is carrier level spam filters. Carriers have added systems and algorithms that detect spam content and then block them before they even get delivered. Unfortunately, these filters are always hidden, subject to carrier preferences, vary from carrier to carrier, and can be changed without notice.

Another common reason why this error code could be returned is that you may have attempted to send too many messages using long code phone numbers in US & Canada. Long codes are 10-digit phone numbers and are intended only for peer-to-peer (P2P) communication. If this issue persists, we highly recommend using short codes for sending bulk messages within US and Canada. Visit our short code page to learn more about obtaining and setting up a short code for your campaign.

However, if you are confident that your message content is compliant, then retry sending the message again. You can also contact our support team to whitelist your message one time with our downstream carriers.
40 Invalid source number The source number you entered is either not in the correct format, not SMS-enabled or not assigned to your Plivo account. Check the “src” phone number in your application and ensure that it is in the correct format and has the ability to send text messages. All phone numbers in your application should include country code, area code, and phone number without spaces or dashes (e.g., 14155555555 for US or +491155555555 for Berlin, Germany).
50 Invalid destination number The destination number you entered is either not entered correctly, not SMS-enabled or is a PSTN landline. Check the “dst” phone number in your application to ensure that it is able to receive text messages. All phone numbers in your application should include country code, area code, and phone number without spaces or dashes (e.g., 14155555555). If you’re sending multiple text messages, make sure that the phone numbers are separated with the “<” character (e.g., 14156667777<14157778888<14158889999).
60 Loop detected The carrier is not able to route your SMS because certain settings in your application are corresponding to an endless loop of messages being sent and received between your “src” and “dst” phone numbers. This can occur when two auto-responding SMS applications start to talk to each other and end up in a loop. Carriers detect loops by comparing messages within a predefined period of time to previous messages sent and received.

SMS loops can increase unnecessary spend, so to ensure that your applications do not trigger loops, it’s a good idea to create loop filters in your application because not all carriers have loop detection.

In some cases, this error code is returned when the carrier determines that it is impossible to route the SMS and the message has to be dropped as it is being looped between platforms.
70 Destination permanently unavailable The destination (i.e., “dst”) phone number is not active and there is no indication of when it will become available again. Note that this is a broad error code where the carrier has not indicated the reason for the destination unavailability. Check the “dst” phone number to ensure that it is correct. Also, try sending messages to an alternative number to ensure that all other parts of your application are working.
80 Destination temporarily unavailable The destination (i.e., “dst”) phone number is not reachable. Note that this is a broad error code and often times, the carrier does not indicate the reason for the destination to be temporarily unavailable. Though, possible reasons could be due to the handset being turned off or out of coverage. To resolve this, retry your messages at a later time.
90 No route available The carrier and fallback carriers were not able to deliver the SMS message because the route was not available. Please note that carriers do not offer the reason for why the route is unavailable, but since this is typically a carrier issue, please contact us and include the message UUIDs of the SMS affected.
100 Prohibited by carrier The carrier rejected the text message because the network did not support the message being sent. This could occur if the destination network does not support SMS.
110 Message too long The message content exceeds the character limit of 1600 for GSM and 737 for UTF encoded messages. Note that depending on the byte size, Emoji characters can also increase the message character count significantly. Also, Plivo automatically concatenates messages longer than 160 characters for GSM encoded messages and 70 characters for UTF encoded messages. Check our FAQ on long message concatenation for more details.
200 Source number blocked by STOP from destination number The destination has opted out from your campaign and blocked all messages sent from your phone number. Opt-outs are typically received via text message replies with a opt-out keyword including “STOP”. All messages to destinations that have opted out will be blocked until the destination opts in with another response. Check our FAQ to learn more about opt-out and opt-in processes.
201 Outbound messages from US Toll-Free numbers to Canadian destination numbers are blocked Your application is attempting to send text messages from a United States Toll-Free phone number to a Canadian phone number destination. Unfortunately, carriers limit US Toll-Free phone numbers to only send SMS to US phone numbers.
1000 Unknown error Delivering your message failed for reasons that are unknown to us and to our carriers. If you notice too many of these cases, please open a support ticket with us so that we can help you identify the problem. Be sure to include the message UUIDs of recent messages (preferably within the last 72 hours) that have been affected.

Response

HTTP Status Code: 200

{
  "api_id": "88415194-6df0-11e6-b608-06a72a185e87",
  "meta": {
    "limit": 20,
    "next": "/v1/Account/{auth_id}/Message/?limit=20&error_code=200&offset=20",
    "offset": 0,
    "previous": null,
    "total_count": 22
  },
  "objects": [
    {
      "error_code": "200",
      "from_number": "18552828641",
      "message_direction": "outbound",
      "message_state": "failed",
      "message_time": "2016-08-17 21:26:44+05:30",
      "message_type": "sms",
      "message_uuid": "85ce8068-6fab-4f0a-9dc7-d6c852cdde91",
      "resource_uri": "/v1/Account/{auth_id}/Message/85ce8068-6fab-4f0a-9dc7-d6c852cdde91/",
      "to_number": "19352326448",
      "total_amount": "0.00000",
      "total_rate": "0.00350",
      "units": 1
    },
    {
      "error_code": "200",
      "from_number": "18552828641",
      "message_direction": "outbound",
      "message_state": "failed",
      "message_time": "2016-08-17 21:22:36+05:30",
      "message_type": "sms",
      "message_uuid": "2a340179-e8a9-4b1d-ae2c-9f346e7b6d7d",
      "resource_uri": "/v1/Account/{auth_id}/Message/2a340179-e8a9-4b1d-ae2c-9f346e7b6d7d/",
      "to_number": "19352326448",
      "total_amount": "0.00000",
      "total_rate": "0.00350",
      "units": 1
    }
  ]
}

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

{
  "api_id": "035eeada-6df1-11e6-b608-06a72a185e87",
  "error_code": "200",
  "from_number": "18552828641",
  "message_direction": "outbound",
  "message_state": "failed",
  "message_time": "2016-08-17 21:22:36+05:30",
  "message_type": "sms",
  "message_uuid": "2a340179-e8a9-4b1d-ae2c-9f346e7b6d7d",
  "resource_uri": "/v1/Account/{auth_id}/Message/2a340179-e8a9-4b1d-ae2c-9f346e7b6d7d/",
  "to_number": "19352326448",
  "total_amount": "0.00000",
  "total_rate": "0.00350",
  "units": 1
}