Skip to main content
A Message Detail Record (MDR) is generated for every message sent or received by Plivo. Use the Message API to send outbound messages, retrieve message details, and monitor message delivery status.

​
The Message Object

​
Attributes

​
message_uuid
string
A 36-character string that uniquely identifies a message detail record.
​
message_time
string
The exact timestamp at which an outbound message was initiated or an inbound message was received.
​
message_direction
string
Indicates the direction of the message. Values: outbound, inbound.
​
message_state
string
Current status of the message. Outbound: queued, sent, failed, delivered, undelivered, read (WhatsApp only). Inbound: received, delivered, undelivered.
​
message_type
string
Type of message. Values: sms, mms, whatsapp.
​
from_number
string
Source address of the message. For outbound: Plivo phone number, short code, alphanumeric sender ID, or WhatsApp Business number. For inbound: the sender’s phone number.
​
to_number
string
Destination phone number. For inbound messages, this is the Plivo phone number that received the message.
​
units
integer
Number of units the message was split into.
​
total_rate
string
The charge applicable per unit of the message.
​
total_amount
string
The total amount charged for this message.
​
error_code
string
Plivo error code. 000 for successful delivery. See error codes for failure codes.
​
conversation_id
string
WhatsApp-only. ID of the conversation to which the message belongs.
​
conversation_origin
string
WhatsApp-only. How the conversation was initiated. Values: utility, authentication, marketing, service.

​
Example Message Object

{
  "api_id": "85a704c8-e47a-11eb-9a69-0242ac110004",
  "carrier_fees": "0.00000",
  "carrier_fees_rate": "0.0000",
  "error_code": "000",
  "from_number": "17087654321",
  "message_direction": "outbound",
  "message_state": "delivered",
  "message_time": "2021-07-13 13:04:06.799021+05:30",
  "message_type": "sms",
  "message_uuid": "b48d95dc-e3ac-11eb-a9c2-0242ac110005",
  "to_number": "12401234567",
  "total_amount": "0.00140",
  "total_rate": "0.00140",
  "units": 1
}

​
Send a Message

Send an SMS, MMS, or WhatsApp message to one or more recipients. 
POST https://api.plivo.com/v1/Account/{auth_id}/Message/

​
Arguments

​
src
string
required
Sender ID: phone number, short code, or alphanumeric string. For WhatsApp, use your WhatsApp Business number. Either src or powerpack_uuid is required.
​
powerpack_uuid
string
UUID of the Powerpack to use for this message. Either src or powerpack_uuid is required.
​
dst
string
required
Destination phone number in E.164 format. For multiple recipients, separate with < (e.g., 14156667777<14157778888).
​
text
string
Message content. For SMS: max 1,600 GSM characters or 737 Unicode characters. For WhatsApp freeform: max 4,096 characters.
​
type
string
Message type. Values: sms (default), mms, whatsapp.
​
media_urls
array
For MMS: comma-separated URLs (max 10, total size < 5MB). For WhatsApp: single media URL.
​
template
object
WhatsApp template object for templated messages. Required for initiating conversations.
​
interactive
object
WhatsApp interactive message object for list buttons, reply buttons, or CTA buttons.
​
location
object
WhatsApp location object with latitude, longitude, name, and address.
​
url
string
Callback URL for delivery status updates.
​
method
string
HTTP method for callback URL. Values: GET, POST (default).
​
message_expiry
integer
Queue expiry time in seconds (5-10,799). Default: 10,800 (3 hours).
​
log
string
Data logging preference. Values: true (default), false, content_only, number_only.
​
trackable
boolean
Set true for messages with trackable actions (e.g., 2FA). Default: false.
​
dlt_entity_id
string
DLT entity ID for India DLT compliance.
​
dlt_template_id
string
DLT template ID for India DLT compliance.
​
dlt_template_category
string
DLT template category. Values: transactional, promotional, service_implicit, service_explicit.

​
Response

Returns the message UUID(s) and API request ID. 
import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.messages.create(
    src='+14151234567',
    dst='+14157654321',
    text='Hello from Plivo!'
)
print(response)
Response
{
  "message": "message(s) queued",
  "message_uuid": ["db3ce55a-7f1d-11e1-8ea7-1231380bc196"],
  "api_id": "db342550-7f1d-11e1-8ea7-1231380bc196"
}

​
Retrieve a Message

Get details of a specific message by its UUID. 
GET https://api.plivo.com/v1/Account/{auth_id}/Message/{message_uuid}/

​
Arguments

​
message_uuid
string
required
The unique identifier of the message to retrieve.
import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.messages.get('message_uuid')
print(response)

​
List All Messages

Retrieve a list of message records with optional filters. 
GET https://api.plivo.com/v1/Account/{auth_id}/Message/

​
Arguments

​
subaccount
string
Filter by subaccount auth_id.
​
message_direction
string
Filter by direction. Values: inbound, outbound.
​
message_state
string
Filter by state. Values: queued, sent, delivered, undelivered, failed, received.
​
message_type
string
Filter by type. Values: sms, mms, whatsapp.
​
message_time__gt
string
Filter messages after this timestamp (format: yyyy-MM-dd HH:mm:ss).
​
message_time__lt
string
Filter messages before this timestamp.
​
error_code
integer
Filter by error code.
​
powerpack_id
string
Filter by Powerpack ID.
​
limit
integer
Results per page (max 20). Default: 20.
​
offset
integer
Number of records to skip. Default: 0.
import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.messages.list(
    limit=5,
    offset=0,
    message_direction='outbound'
)
print(response)

​
List MMS Media

Retrieve media files associated with an MMS message. 
GET https://api.plivo.com/v1/Account/{auth_id}/Message/{message_uuid}/Media/

​
Arguments

​
message_uuid
string
required
The unique identifier of the MMS message.
import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.messages.list_media('message_uuid')
print(response)

​
Message Status Callbacks

Configure a callback URL to receive delivery status updates for your messages.

​
Callback Parameters

ParameterTypeDescription
FromstringThe sender ID of the message.
TostringThe destination number.
MessageUUIDstringUnique identifier for the message.
StatusstringCurrent status: queued, sent, delivered, undelivered, failed, read.
UnitsintegerNumber of message units.
TotalRatestringPer-unit charge.
TotalAmountstringTotal charge for the message.
ErrorCodestringError code if delivery failed.
MCCstringMobile Country Code of the destination.
MNCstringMobile Network Code of the destination.

​
Handling Incoming Messages

When a message is received on your Plivo number, Plivo sends a request to your configured Message URL.

​
Incoming Message Parameters

ParameterTypeDescription
FromstringSender’s phone number.
TostringYour Plivo phone number.
TextstringMessage content.
TypestringMessage type (sms, mms, whatsapp).
MessageUUIDstringUnique message identifier.
Media0…MediaNstringMMS media URLs (for MMS messages).

​
Configuration

  1. Create a Messaging Application
  2. Set your Message URL endpoint
  3. Assign the application to your Plivo number
Your endpoint should return a 200 OK response. Optionally, return Message XML to send a reply.