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

string

A 36-character string that uniquely identifies a message detail record.

string

The exact timestamp at which an outbound message was initiated or an inbound message was received.

string

Indicates the direction of the message. Values: outbound, inbound.

string

Current status of the message. Outbound: queued, sent, failed, delivered, undelivered, read (WhatsApp only). Inbound: received, delivered, undelivered.

string

Type of message. Values: sms, mms, whatsapp.

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.

string

Destination phone number. For inbound messages, this is the Plivo phone number that received the message.

integer

Number of units the message was split into.

string

The charge applicable per unit of the message.

string

The total amount charged for this message.

string

Plivo error code. 000 for successful delivery. See error codes for failure codes.

string

WhatsApp-only. ID of the conversation to which the message belongs.

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

string

Filter by subaccount auth_id.

string

Filter by direction. Values: inbound, outbound.

string

Filter by state. Values: queued, sent, delivered, undelivered, failed, received.

string

Filter by type. Values: sms, mms, whatsapp.

string

Filter messages after this timestamp (format: yyyy-MM-dd HH:mm:ss).

string

Filter messages before this timestamp.

integer

Filter by error code.

string

Filter by Powerpack ID.

integer

Results per page (max 20). Default: 20.

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

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

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.

string

UUID of the Powerpack to use for this message. Either src or powerpack_uuid is required.

string

required

Destination phone number in E.164 format. For multiple recipients, separate with < (e.g., 14156667777<14157778888).

string

Message content. For SMS: max 1,600 GSM characters or 737 Unicode characters. For WhatsApp freeform: max 4,096 characters.

string

Message type. Values: sms (default), mms, whatsapp.

array

For MMS: comma-separated URLs (max 10, total size < 5MB). For WhatsApp: single media URL.

object

WhatsApp template object for templated messages. Required for initiating conversations.

object

WhatsApp interactive message object for list buttons, reply buttons, or CTA buttons.

object

WhatsApp location object with latitude, longitude, name, and address.

string

Callback URL for delivery status updates.

string

HTTP method for callback URL. Values: GET, POST (default).

integer

Queue expiry time in seconds (5-10,799). Default: 10,800 (3 hours).

string

Data logging preference. Values: true (default), false, content_only, number_only.

boolean

Set true for messages with trackable actions (e.g., 2FA). Default: false.

string

deprecated

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

string

deprecated

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

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

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