Messaging API Quickstart

Get started with Plivo Messaging in minutes. This guide walks you through sending your first SMS/MMS message and receiving incoming messages.

Prerequisites

Before you begin:

Sign up for a Plivo account (free trial includes credits)
Note your Auth ID and Auth Token from the console dashboard
Rent a phone number for sending/receiving messages

Install the SDK

pip install plivo

For web framework support, also install Flask:

pip install flask

npm install plivo

For web server support, also install Express:

npm install express

gem install plivo sinatra

composer require plivo/plivo-php

Add to your pom.xml:

<dependency>
  <groupId>com.plivo</groupId>
  <artifactId>plivo-java</artifactId>
  <version>5.9.0</version>
</dependency>

dotnet add package Plivo

go get github.com/plivo/plivo-go/v7

Send an SMS Message

Send an outbound SMS message from your Plivo number to any destination number.

import plivo

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

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

print(response)

const plivo = require('plivo');

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

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

require 'plivo'

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

response = api.messages.create(
  '+14151234567',    # from
  ['+14157654321'],  # to
  '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 SendSMS {
    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!",
    })
}

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/

Replace the phone numbers with your Plivo number and destination number in E.164 format (e.g., +12025551234).

Send an MMS Message

Send a message with media attachments (US and Canada only).

import plivo

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

response = client.messages.create(
    src='+14151234567',
    dst='+14157654321',
    text='Check out this image!',
    type_='mms',
    media_urls=['https://example.com/image.jpg']
)

print(response)

const plivo = require('plivo');

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

client.messages.create({
    src: '+14151234567',
    dst: '+14157654321',
    text: 'Check out this image!',
    type: 'mms',
    media_urls: ['https://example.com/image.jpg']
}).then(console.log);

require 'plivo'

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

response = api.messages.create(
  '+14151234567',
  ['+14157654321'],
  'Check out this image!',
  { type: 'mms', media_urls: ['https://example.com/image.jpg'] }
)

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' => 'Check out this image!',
    'type' => 'mms',
    'media_urls' => ['https://example.com/image.jpg']
]);

print_r($response);

import com.plivo.api.Plivo;
import com.plivo.api.models.message.Message;
import java.util.Arrays;

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

        Message.creator("+14151234567", "+14157654321", "Check out this image!")
            .type("mms")
            .mediaUrls(Arrays.asList("https://example.com/image.jpg"))
            .create();
    }
}

using Plivo;

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

var response = api.Message.Create(
    src: "+14151234567",
    dst: new[] { "+14157654321" },
    text: "Check out this image!",
    type: "mms",
    mediaUrls: new[] { "https://example.com/image.jpg" }
);

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:      "Check out this image!",
        Type:      "mms",
        MediaUrls: []string{"https://example.com/image.jpg"},
    })
}

Receive an Incoming Message

Set up a web server to handle incoming messages. When someone sends an SMS to your Plivo number, Plivo sends a request to your Message URL with the message details.

from flask import Flask, request

app = Flask(__name__)

@app.route('/receive_sms/', methods=['GET', 'POST'])
def receive_sms():
    from_number = request.values.get('From')
    to_number = request.values.get('To')
    text = request.values.get('Text')

    print(f'Message received - From: {from_number}, To: {to_number}, Text: {text}')
    return 'OK'

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

Run: python app.py

const express = require('express');
const app = express();

app.use(express.urlencoded({ extended: true }));

app.all('/receive_sms/', (req, res) => {
    const fromNumber = req.body.From || req.query.From;
    const toNumber = req.body.To || req.query.To;
    const text = req.body.Text || req.query.Text;

    console.log(`Message received - From: ${fromNumber}, To: ${toNumber}, Text: ${text}`);
    res.send('OK');
});

app.listen(5000, () => console.log('Server running on port 5000'));

Run: node app.js

require 'sinatra'

get '/receive_sms/' do
    from_number = params[:From]
    to_number = params[:To]
    text = params[:Text]

    puts "Message received - From: #{from_number}, To: #{to_number}, Text: #{text}"
    'OK'
end

post '/receive_sms/' do
    from_number = params[:From]
    to_number = params[:To]
    text = params[:Text]

    puts "Message received - From: #{from_number}, To: #{to_number}, Text: #{text}"
    'OK'
end

Run: ruby app.rb

<?php
$from_number = $_REQUEST['From'];
$to_number = $_REQUEST['To'];
$text = $_REQUEST['Text'];

error_log("Message received - From: $from_number, To: $to_number, Text: $text");

echo 'OK';

import static spark.Spark.*;

public class ReceiveSMS {
    public static void main(String[] args) {
        port(5000);

        get("/receive_sms/", (req, res) -> {
            String fromNumber = req.queryParams("From");
            String toNumber = req.queryParams("To");
            String text = req.queryParams("Text");

            System.out.println("Message received - From: " + fromNumber +
                ", To: " + toNumber + ", Text: " + text);
            return "OK";
        });

        post("/receive_sms/", (req, res) -> {
            String fromNumber = req.queryParams("From");
            String toNumber = req.queryParams("To");
            String text = req.queryParams("Text");

            System.out.println("Message received - From: " + fromNumber +
                ", To: " + toNumber + ", Text: " + text);
            return "OK";
        });
    }
}

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("[controller]")]
public class ReceiveSmsController : ControllerBase
{
    [HttpGet]
    [HttpPost]
    public IActionResult ReceiveSms()
    {
        var fromNumber = Request.Form["From"].ToString();
        var toNumber = Request.Form["To"].ToString();
        var text = Request.Form["Text"].ToString();

        Console.WriteLine($"Message received - From: {fromNumber}, To: {toNumber}, Text: {text}");
        return Ok("OK");
    }
}

package main

import (
    "fmt"
    "net/http"
)

func main() {
    http.HandleFunc("/receive_sms/", func(w http.ResponseWriter, r *http.Request) {
        r.ParseForm()
        fromNumber := r.FormValue("From")
        toNumber := r.FormValue("To")
        text := r.FormValue("Text")

        fmt.Printf("Message received - From: %s, To: %s, Text: %s\n", fromNumber, toNumber, text)
        w.Write([]byte("OK"))
    })

    http.ListenAndServe(":5000", nil)
}

Run: go run main.go

Expose Your Server

Use ngrok to expose your local server to the internet:

ngrok http 5000

Copy the HTTPS forwarding URL (e.g., https://abc123.ngrok.io).

Configure Your Number

Go to Messaging Applications in the Plivo console
Click Add New Application
Set the Message URL to your ngrok URL + /receive_sms/ (e.g., https://abc123.ngrok.io/receive_sms/)
Save the application
Go to Phone Numbers and assign the application to your number

Reply to an Incoming Message

Return XML to automatically reply to incoming messages.

from flask import Flask, request, Response
from plivo import plivoxml

app = Flask(__name__)

@app.route('/reply_sms/', methods=['GET', 'POST'])
def reply_sms():
    from_number = request.values.get('From')
    to_number = request.values.get('To')

    response = plivoxml.ResponseElement()
    response.add(plivoxml.MessageElement(
        'Thanks for your message!',
        src=to_number,
        dst=from_number
    ))

    return Response(response.to_string(), mimetype='application/xml')

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

const express = require('express');
const plivo = require('plivo');

const app = express();
app.use(express.urlencoded({ extended: true }));

app.all('/reply_sms/', (req, res) => {
    const fromNumber = req.body.From || req.query.From;
    const toNumber = req.body.To || req.query.To;

    const response = plivo.Response();
    response.addMessage('Thanks for your message!', {
        src: toNumber,
        dst: fromNumber
    });

    res.set('Content-Type', 'application/xml');
    res.send(response.toXML());
});

app.listen(5000, () => console.log('Server running on port 5000'));

require 'sinatra'
require 'plivo'

post '/reply_sms/' do
    from_number = params[:From]
    to_number = params[:To]

    response = Plivo::XML::Response.new
    response.addMessage('Thanks for your message!', {
        src: to_number,
        dst: from_number
    })

    content_type 'application/xml'
    response.to_xml
end

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

$from_number = $_REQUEST['From'];
$to_number = $_REQUEST['To'];

$response = new Response();
$response->addMessage('Thanks for your message!', [
    'src' => $to_number,
    'dst' => $from_number
]);

header('Content-Type: application/xml');
echo $response->toXML();

import com.plivo.api.xml.Response;
import com.plivo.api.xml.Message;
import static spark.Spark.*;

public class ReplySMS {
    public static void main(String[] args) {
        port(5000);

        post("/reply_sms/", (req, res) -> {
            String fromNumber = req.queryParams("From");
            String toNumber = req.queryParams("To");

            res.type("application/xml");
            return new Response()
                .children(
                    new Message("Thanks for your message!")
                        .src(toNumber)
                        .dst(fromNumber)
                )
                .toXmlString();
        });
    }
}

using Microsoft.AspNetCore.Mvc;
using Plivo.XML;

[ApiController]
[Route("[controller]")]
public class ReplySmsController : ControllerBase
{
    [HttpPost]
    public ContentResult ReplySms()
    {
        var fromNumber = Request.Form["From"].ToString();
        var toNumber = Request.Form["To"].ToString();

        var response = new Response();
        response.AddMessage("Thanks for your message!", new Dictionary<string, string>
        {
            { "src", toNumber },
            { "dst", fromNumber }
        });

        return Content(response.ToString(), "application/xml");
    }
}

package main

import (
    "github.com/plivo/plivo-go/v7/xml"
    "net/http"
)

func main() {
    http.HandleFunc("/reply_sms/", func(w http.ResponseWriter, r *http.Request) {
        r.ParseForm()
        fromNumber := r.FormValue("From")
        toNumber := r.FormValue("To")

        response := xml.ResponseElement{
            Contents: []interface{}{
                new(xml.MessageElement).
                    SetSrc(toNumber).
                    SetDst(fromNumber).
                    SetContents("Thanks for your message!"),
            },
        }

        w.Header().Set("Content-Type", "application/xml")
        w.Write([]byte(response.String()))
    })

    http.ListenAndServe(":5000", nil)
}

Next Steps

Send bulk messages - Send to multiple recipients
Use Powerpack - Distribute traffic across multiple numbers
Set up 10DLC - Register for A2P messaging in the US
Explore use cases - SMS alerts, 2FA, marketing, and more

Getting Started

Concepts

API Reference

XML Reference

Tutorials

Migration Guides

Troubleshooting

Messaging API Quickstart

Prerequisites

Install the SDK

Send an SMS Message

Send an MMS Message

Receive an Incoming Message

Expose Your Server

Configure Your Number

Reply to an Incoming Message

Next Steps

Getting Started

Concepts

API Reference

XML Reference

Tutorials

Migration Guides

Troubleshooting

Documentation Index

​Prerequisites

​Install the SDK

​Send an SMS Message

​Send an MMS Message

​Receive an Incoming Message

​Expose Your Server

​Configure Your Number

​Reply to an Incoming Message

​Next Steps

Prerequisites

Install the SDK

Send an SMS Message

Send an MMS Message

Receive an Incoming Message

Expose Your Server

Configure Your Number

Reply to an Incoming Message

Next Steps