Messages

Send, retrieve, and manage SMS/MMS/WhatsApp messages programmatically

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

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

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

curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{
        "src": "[phone]",
        "dst": "[phone]",
        "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='[phone]',
    dst='[phone]',
    text='Hello from Plivo!'
)
print(response)

const plivo = require('plivo');

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

client.messages.create({
    src: '[phone]',
    dst: '[phone]',
    text: 'Hello from Plivo!'
}).then(console.log);

require 'plivo'

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

response = api.messages.create(
  '[phone]',
  ['[phone]'],
  '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' => '[phone]',
    'dst' => '[phone]',
    '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("[phone]", "[phone]", "Hello from Plivo!")
            .create();
    }
}

using Plivo;

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

var response = api.Message.Create(
    src: "[phone]",
    dst: new[] { "[phone]" },
    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:  "[phone]",
        Dst:  "[phone]",
        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

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

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.