> ## 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

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install plivo
    ```

    For web framework support, also install Flask:

    ```bash theme={null}
    pip install flask
    ```
  </Tab>

  <Tab title="Node.js">
    ```bash theme={null}
    npm install plivo
    ```

    For web server support, also install Express:

    ```bash theme={null}
    npm install express
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash theme={null}
    gem install plivo sinatra
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require plivo/plivo-php
    ```
  </Tab>

  <Tab title="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>

  <Tab title=".NET">
    ```bash theme={null}
    dotnet add package Plivo
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={null}
    go get github.com/plivo/plivo-go/v7
    ```
  </Tab>
</Tabs>

***

## Send an SMS Message

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

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="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>

  <Tab title="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>

  <Tab title="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>

  <Tab title=".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>

  <Tab title="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>

  <Tab title="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/
    ```
  </Tab>
</Tabs>

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).

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="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>

  <Tab title="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>

  <Tab title="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>

  <Tab title=".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>

  <Tab title="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"},
        })
    }
    ```
  </Tab>
</Tabs>

***

## 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.

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="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>

  <Tab title="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>

  <Tab title="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>

  <Tab title=".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>

  <Tab title="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`
  </Tab>
</Tabs>

### 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.

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="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>

  <Tab title="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>

  <Tab title="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>

  <Tab title=".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>

  <Tab title="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)
    }
    ```
  </Tab>
</Tabs>

***

## Next Steps

* [Send bulk messages](/messaging/api/messages/) - Send to multiple recipients
* [Use Powerpack](/messaging/concepts/powerpack/) - Distribute traffic across multiple numbers
* [Set up 10DLC](/messaging/api/10dlc/) - Register for A2P messaging in the US
* [Explore use cases](/messaging/use-cases/send-an-sms/) - SMS alerts, 2FA, marketing, and more