> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Messaging API Quickstart

> Send your first SMS/MMS message and handle incoming messages with Plivo's Messaging API

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:

1. [Sign up for a Plivo account](https://cx.plivo.com/signup) (free trial includes credits)
2. Note your **Auth ID** and **Auth Token** from the [console dashboard](https://cx.plivo.com/home)
3. [Rent a phone number](https://cx.plivo.com/phone-numbers) for sending/receiving messages

***

## Install the SDK

> [tab] Python
>
> ```bash theme={null}
> pip install plivo
> ```
>
> For web framework support, also install Flask:
>
> ```bash theme={null}
> pip install flask
> ```

> [tab] Node.js
>
> ```bash theme={null}
> npm install plivo
> ```
>
> For web server support, also install Express:
>
> ```bash theme={null}
> npm install express
> ```

> [tab] Ruby
>
> ```bash theme={null}
> gem install plivo sinatra
> ```

> [tab] PHP
>
> ```bash theme={null}
> composer require plivo/plivo-php
> ```

> [tab] Java
>
> Add to your `pom.xml`:
>
> ```xml theme={null}
> <dependency>
>   <groupId>com.plivo</groupId>
>   <artifactId>plivo-java</artifactId>
>   <version>5.9.0</version>
> </dependency>
> ```

> [tab] .NET
>
> ```bash theme={null}
> dotnet add package Plivo
> ```

> [tab] Go
>
> ```bash theme={null}
> 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.

> [tab] Python
>
> ```python theme={null}
> 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)
> ```

> [tab] Node.js
>
> ```javascript theme={null}
> 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);
> ```

> [tab] Ruby
>
> ```ruby theme={null}
> require 'plivo'
>
> api = Plivo::RestClient.new('<auth_id>', '<auth_token>')
>
> response = api.messages.create(
>   '+14151234567',    # from
>   ['+14157654321'],  # to
>   'Hello from Plivo!'
> )
>
> puts response
> ```

> [tab] PHP
>
> ```php theme={null}
> <?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);
> ```

> [tab] Java
>
> ```java theme={null}
> 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();
>     }
> }
> ```

> [tab] .NET
>
> ```csharp theme={null}
> 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);
> ```

> [tab] Go
>
> ```go theme={null}
> 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!",
>     })
> }
> ```

> [tab] cURL
>
> ```bash theme={null}
> 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](https://en.wikipedia.org/wiki/E.164) (e.g., +12025551234).

***

## Send an MMS Message

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

> [tab] Python
>
> ```python theme={null}
> 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)
> ```

> [tab] Node.js
>
> ```javascript theme={null}
> 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);
> ```

> [tab] Ruby
>
> ```ruby theme={null}
> 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
> ```

> [tab] PHP
>
> ```php theme={null}
> <?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);
> ```

> [tab] Java
>
> ```java theme={null}
> 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();
>     }
> }
> ```

> [tab] .NET
>
> ```csharp theme={null}
> 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);
> ```

> [tab] Go
>
> ```go theme={null}
> 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.

> [tab] Python
>
> ```python theme={null}
> 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`

> [tab] Node.js
>
> ```javascript theme={null}
> 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`

> [tab] Ruby
>
> ```ruby theme={null}
> 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`

> [tab] PHP
>
> ```php theme={null}
> <?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';
> ```

> [tab] Java
>
> ```java theme={null}
> 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";
>         });
>     }
> }
> ```

> [tab] .NET
>
> ```csharp theme={null}
> 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");
>     }
> }
> ```

> [tab] Go
>
> ```go theme={null}
> 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](https://ngrok.com) to expose your local server to the internet:

```bash theme={null}
ngrok http 5000
```

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

### Configure Your Number

1. Go to [Messaging Applications](https://cx.plivo.com/xml-applications) in the Plivo console
2. Click **Add New Application**
3. Set the **Message URL** to your ngrok URL + `/receive_sms/` (e.g., `https://abc123.ngrok.io/receive_sms/`)
4. Save the application
5. Go to [Phone Numbers](https://cx.plivo.com/phone-numbers) and assign the application to your number

***

## Reply to an Incoming Message

Return XML to automatically reply to incoming messages.

> [tab] Python
>
> ```python theme={null}
> 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)
> ```

> [tab] Node.js
>
> ```javascript theme={null}
> 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'));
> ```

> [tab] Ruby
>
> ```ruby theme={null}
> 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
> ```

> [tab] PHP
>
> ```php theme={null}
> <?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();
> ```

> [tab] Java
>
> ```java theme={null}
> 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();
>         });
>     }
> }
> ```

> [tab] .NET
>
> ```csharp theme={null}
> 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");
>     }
> }
> ```

> [tab] Go
>
> ```go theme={null}
> 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](https://plivo.com/docs/messaging/api/messages.md) - Send to multiple recipients
* [Use Powerpack](https://plivo.com/docs/messaging/concepts/powerpack.md) - Distribute traffic across multiple numbers
* [Set up 10DLC](https://plivo.com/docs/messaging/api/10dlc/) - Register for A2P messaging in the US
* [Explore use cases](https://plivo.com/docs/messaging/use-cases/send-an-sms/) - SMS alerts, 2FA, marketing, and more
