Messages

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
}

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.

curl -i --user AUTH_ID:AUTH_TOKEN \
    "https://api.plivo.com/v1/Account/{auth_id}/Message/?limit=5&message_direction=outbound"

import plivo

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

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');
client.messages.list({
    limit: 5,
    offset: 0,
    message_direction: 'outbound'
}).then(console.log);

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.

curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Message/{message_uuid}/

import plivo

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

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');
client.messages.get('message_uuid').then(console.log);

require 'plivo'

api = Plivo::RestClient.new('<auth_id>', '<auth_token>')
response = api.messages.get('message_uuid')
puts response

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

deprecated

Deprecated. Plivo no longer supports domestic India SMS via DLT; messages to India are delivered over international (ILDO) routes.

dlt_template_id

string

deprecated

Deprecated. Plivo no longer supports domestic India SMS via DLT; messages to India are delivered over international (ILDO) routes.

dlt_template_category

string

deprecated

Deprecated. Plivo no longer supports domestic India SMS via DLT; messages to India are delivered over international (ILDO) routes.

Response

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

curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{
        "src": "+14151234567",
        "dst": "+14157654321",
        "text": "Hello from Plivo!"
    }' \
    https://api.plivo.com/v1/Account/{auth_id}/Message/

import plivo

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

response = client.messages.create(
    src='+14151234567',
    dst='+14157654321',
    text='Hello from Plivo!'
)
print(response)

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.messages.create({
    src: '+14151234567',
    dst: '+14157654321',
    text: 'Hello from Plivo!'
}).then(console.log);

require 'plivo'

api = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = api.messages.create(
  '+14151234567',
  ['+14157654321'],
  'Hello from Plivo!'
)
puts response

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->messages->create([
    'src' => '+14151234567',
    'dst' => '+14157654321',
    'text' => 'Hello from Plivo!'
]);
print_r($response);

import com.plivo.api.Plivo;
import com.plivo.api.models.message.Message;

public class SendMessage {
    public static void main(String[] args) {
        Plivo.init("<auth_id>", "<auth_token>");

        Message.creator("+14151234567", "+14157654321", "Hello from Plivo!")
            .create();
    }
}

using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.Message.Create(
    src: "+14151234567",
    dst: new[] { "+14157654321" },
    text: "Hello from Plivo!"
);
Console.WriteLine(response);

package main

import "github.com/plivo/plivo-go/v7"

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    client.Messages.Create(plivo.MessageCreateParams{
        Src:  "+14151234567",
        Dst:  "+14157654321",
        Text: "Hello from Plivo!",
    })
}

Response

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

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.

curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Message/{message_uuid}/Media/

import plivo

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

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');
client.messages.listMedia('message_uuid').then(console.log);

Message Status Callbacks

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

Callback Parameters

Status callback parameters

Parameter	Type	Description
`From`	string	The sender ID of the message.
`To`	string	The destination number.
`MessageUUID`	string	Unique identifier for the message.
`Status`	string	Current status: `queued`, `sent`, `delivered`, `undelivered`, `failed`, `read`.
`Units`	integer	Number of message units.
`TotalRate`	string	Per-unit charge.
`TotalAmount`	string	Total charge for the message.
`ErrorCode`	string	Error code if delivery failed.
`MCC`	string	Mobile Country Code of the destination.
`MNC`	string	Mobile 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

Parameter	Type	Description
`From`	string	Sender’s phone number.
`To`	string	Your Plivo phone number.
`Text`	string	Message content.
`Type`	string	Message type (`sms`, `mms`, `whatsapp`).
`MessageUUID`	string	Unique message identifier.
`Media0`…`MediaN`	string	MMS media URLs (for MMS messages).

Configuration

Create a Messaging Application
Set your Message URL endpoint
Assign the application to your Plivo number

Your endpoint should return a 200 OK response. Optionally, return Message XML to send a reply.

Getting Started

Concepts

API Reference

XML Reference

Tutorials

Migration Guides

Troubleshooting

The Message Object

Attributes

Example Message Object

List All Messages

Arguments

Retrieve a Message

Arguments

Send a Message

Arguments

Response

List MMS Media

Arguments

Message Status Callbacks

Callback Parameters

Handling Incoming Messages

Incoming Message Parameters

Configuration

​The Message Object

​Attributes

​Example Message Object

​List All Messages

​Arguments

​Retrieve a Message

​Arguments

​Send a Message

​Arguments

​Response

​List MMS Media

​Arguments

​Message Status Callbacks

​Callback Parameters

​Handling Incoming Messages

​Incoming Message Parameters

​Configuration

The Message Object

Attributes

Example Message Object

List All Messages

Arguments

Retrieve a Message

Arguments

Send a Message

Arguments

Response

List MMS Media

Arguments

Message Status Callbacks

Callback Parameters

Handling Incoming Messages

Incoming Message Parameters

Configuration