Latest Legacy

The Message object

A Message Detail Record (MDR) is generated for every message sent or received by Plivo.

An MDR object has these 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. It is set to outbound for messages sent out from Plivo’s platform, and to inbound for messages received on Plivo numbers.

message_state string

Indicates the current status of the message.

Outbound messages may be in any of the following states: queued, sent, failed, delivered, undelivered, read (WhatsApp only). 

All outbound messages are initially queued. A message is marked as failed if an internal error occurs before the message is passed on to downstream carriers. A message is marked as sent when the message is successfully passed to a downstream carrier. The message is marked delivered or undelivered based on the delivery receipt received from the carrier. Note that delivery receipts are not universally supported across countries, number types, and mobile networks. The final status of a message may remain as sent in cases where delivery receipts are not received.Additionally, a message is marked as read when a WhatsApp message sent by you was read by the user. read status are only available when the destination whatsapp users have read receipts enabled.

Inbound messages may be in any of the following states: received, delivered, undelivered.

All inbound messages are initially marked as received. If the Plivo phone number on which the message was received is associated with an application, and the application has a valid message_url configured, then the message is forwarded to that URL. The message is marked as delivered on a successful response from the message_url, else it is marked undelivered.

message_type string

Set to sms for SMS messages and mms for MMS messages & whatsapp for WhatsApp messages

from_number string

Identifies the source address of the message. For outbound messages, this could be a Plivo phone number, short code, alphanumeric sender ID or a phone number linked to your WhatsApp business account.

For inbound messages, this is the phone number from which the message to the Plivo phone number was initiated.

to_number string

The destination phone number to which the message was sent. In case of inbound messages, this would be the Plivo phone number on which the message was received.

destination_country_iso2 stringThe ISO2 code of the country associated with the destination number.
units integer

Indicates the number of units that a 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. Typically, this would be equal to the product of total_rate and units.

requester_ip stringThe IP address from which the message request originated. We recommend you monitor this field to identify possible account misuse and authentication credential takeovers.
error_code string

The Plivo SMS error code that helps identify the cause for a message delivery failure. For successfully delivered messages, this attribute is set to 000. For failed and undelivered messages it’s set to one of these error codes.

Reach out to Plivo support for WhatsApp related error codes.

tendlc_registration_status stringIndicates nature of 10DLC registration for that message. Only relevant for long code messaging in the US.
tendlc_campaign_id stringThe campaign ID associated with the message. Only relevant for long code messaging in the US.
replaced_sender stringThis is the sender (numeric or alpha) that left Plivo's system. In some instances, Plivo replaces the sender to ensure compliance and deliverability. 
is_domestic stringThis is the boolean which indicates if a message is treated as 'domestic'. This is derived from the way you have classified your Sender ID at the point of Sender ID registration. This is to support India specific use cases such as DLT messaging and India DND filtering. 
dlt_entity_id string

For DLT eligible India customers only.

This is the DLT entity id passed in the message request.

dlt_template_id string

For DLT eligible India customers only.

This is the DLT template id passed in the message request.

dlt_template_category string

For DLT eligible India customers only.

Pass the template categorization as registered in DLT portal. Possible values: transactional, promotional, service_implicitservice_explicit.

conversation_id string

WhatsApp only attribute.

Represents the ID of the conversation the given message belongs to. Can be null for inbound messages. 

conversation_origin string

WhatsApp only attribute.

Possible values: utility, authentication, marketing, service

Describes how the WhatsApp conversation was initiated. This is determined if the conversation was initiated by a business or by user. 

service conversations are initiated when a user sends a message to the business. 

utility, authentication, marketing conversations are initiated when a business sends the message to their users using a templates of category: utility ,authentication , marketing respectively.

conversation_expiry_time string

WhatsApp only attribute.

Timestamp (Unix) when the current ongoing conversation expires. This is 24hrs since the conversation has started. A conversation is considered started on the first outbound message sent by you to your end user. 


    "api_id": "85a704c8-e47a-11eb-9a69-0242ac110004",
    "carrier_fees": "0.00000",
    "error_code": "000",
    "from_number": "17087654321",
    "is_domestic": true,
    "mcc": "312",
    "message_direction": "outbound",
    "message_state": "delivered",
    "message_time": "2021-07-13 13:04:06.799021+05:30",
    "message_type": "whatsapp",
    "message_uuid": "b48d95dc-e3ac-11eb-a9c2-0242ac110005",
    "mnc": "650",
    "powerpack_id": "1d5f3dd8-b207-4738-b59f-3c2ac7d3461c",
    "resource_uri": "/v1/Account/{auth_id}/Message/b48d95dc-e3ac-11eb-a9c2-0242ac110005/",
    "to_number": "12401234567",
    "total_amount": "0.00140",
    "total_rate": "0.00140",
    "tendlc_campaign_id": "CD4WJJD",
    "tendlc_registration_status": "registered",
    "destination_country_iso2": "US",
    "units": 1,
    "replaced_sender": "",
    "dlt_entity_id": "",
    "dlt_template_id": "",
    "dlt_template_category": "",
    "conversation_id": "d0dfd12bed80dca89636268d0a67c383",
    "conversation_origin": "utility",
    "conversation_expiry_time": "2023-05-26 18:54:00.000000",
    "requester_ip": "",
    "destination_network": "verizon"