Send a Message | Plivo API Reference

Latest Legacy

Send SMS/MMS/WhatsApp

This API enables you to send messages via Plivo’s SMS service.

API Endpoint

POST https://api.plivo.com/v1/Account/{auth_id}/Message/

Arguments

src string Required — Conditional	The sender ID you want to use, which may be a phone number, a short code, or an alphanumeric string. For a WhatsApp message, use the phone number associated with your WhatsApp Business Account and mapped to your Plivo account. You may use either src or powerpack_uuid but not both. If you’re sending a message toward India and are registered on a DLT portal, use the registered DLT header that's mapped to the template you're sending. All characters other than A-Z, a-z, and 0-9 are stripped off automatically as part of the sanitization process. Sanitized phone numbers must begin with the international country code (for example, 14152828726), and should be <= 14 characters in length. Sanitized alphanumeric sender IDs should be <= 11 characters in length. Support for alphanumeric sender IDs is disabled by default. You must have a Plivo phone number to send messages to the US or Canada. You can buy a Plivo number from Phone Numbers > Buy Numbers on the Plivo console or via the Numbers API.
powerpack_uuid string Required — Conditional	Set this to the UUID of the SMS Powerpack you wish to use for this message. You may use either src or powerpack_uuid but not both.
dst string Required	The phone number to which the message is to be delivered. The following characters are stripped off automatically as part of the sanitization process: /, -, ., +, (, ), and white spaces. Sanitized phone numbers must begin with the international country code (for example, 14152828726), and should be <= 14 characters in length. To send messages to multiple numbers, separate your destination phone numbers with the delimiter < — for example, 14156667777<14157778888<14158889999. When you send WhatsApp messages to multiple destination numbers in a single request, each destination number will result in a unique conversation and will be tracked separately.
text string Required - Conditional	The content of the text message. For SMS Messages containing only GSM 03.38 7-bit characters have a maximum limit of 1,600 characters. Messages longer than 160 characters are split into multiple message units, each unit consisting of 153 characters. Messages containing one or more UCS-2 16-bit Unicode characters have a maximum limit of 737 characters. Messages longer than 70 characters are split into multiple message units, each unit consisting of 67 characters. Multiunit messages are automatically stitched back together and delivered as a single message in countries where mobile networks support long message concatenation. For WhatsApp messages You can send messages with this field when sending freeform messages. Non-templated messages can only be sent when an active conversation is ongoing. If no conversation is ongoing, such messages will fail with error 340. Use this parameter when you’re sending freeform (non-templated) text messages. These messages may be no longer than 4,096 characters. When sent along with media, this text will be displayed in WhatsApp as a media caption. When sent with media, text may be no longer than 1,024 characters.
type string	Allowed values: sms for SMS messages, mms for MMS messages, or whatsapp for WhatsApp messages Defaults to sms.
media_urls string Required — Conditional	For MMS messages A comma-separated list of URL-encoded hyperlinks to the images or media to be included in the MMS message. This is a required field if the message type is mms. Up to 10 media files may be included in a single MMS message. Images of type gif, png, and jpeg will be formatted correctly for device compatibility before being forwarded downstream. Plivo may also resize an image if the original attachment exceeds the maximum size supported by the destination network. You may include other media types (audio, video, vcards), but attachments of these types are not optimized for device compatibility. The total size of the MMS must not exceed 5MB. Messages exceeding this limit will be marked as Failed with error code 120. Note that Plivo will attempt to order media attachments on the device in the order specified in the API request, but the ordering cannot be guaranteed. For WhatsApp messages Use only a single media URL per message. Image, video, documents, and audio files are supported. For valid file types and maximum file size accepted refer to Meta documentation.
template object Required — Conditional	JSON object to send templated WhatsApp messages when type is whatsapp. Message templates are used to initiate conversations with customers. Templated messages are the only types of message that you can send to customers who have yet to initiate a conversation with you, or who have not sent you a message in an existing conversation thread within the last 24 hours. You can create templates using WhatsApp Manager. Templates are uniquely identified by a combination of template name and language code. Components are used if dynamic variables are sent within a template. Here are the arguments sent in the Template object.
message_expiry string	Set this parameter to control the time your message remains in the messaging queue. Once this period elapses your messages will fail with error code 420. The error code will be relayed back to your message URL, if configured. The value can be between 5 and 10,799 seconds. Defaults to 10,800 seconds (3 hours).
url string	Set this parameter to the fully qualified URL to which status update callbacks for the message should be sent. Read more about the message attributes passed to this callback URL.
dlt_entity_id string Required — Conditional	The DLT entity ID that was generated during the DLT registration process. Used only by customers with India DLT registrations that have their Plivo accounts configured to support India DLT traffic. For more information see DLT Registration Process for Sending SMS to India. Your message will fail with Plivo error code 160 if you pass this parameter incorrectly.
dlt_template_id string Required — Conditional	The DLT template ID that was generated during template creation in DLT portal. Used only by customers that have their Plivo accounts configured to support India DLT traffic. For more information see DLT Registration Process for Sending SMS to India. The template should be associated with the DLT header that’s passed as the src as part of this request. Your message will fail with Plivo error code 160 if you pass this parameter incorrectly.
dlt_template_category string Required — Conditional	The DLT template category from the DLT portal. Used only by customers that have their Plivo accounts configured to support India DLT traffic. Incorrect tagging of this parameter might result in message failures due to DND scrubbing. Allow values: transactional, promotional, service_implicit, service_explicit,
method string	The HTTP method to be used when calling the URL defined above. Allow values: GET, POST Defaults to POST
trackable boolean	Set this parameter to true for messages that have a trackable user action, such as entering a 2FA verification code. Setting this parameter to true implies that you intend to update Plivo upon successful delivery of the message using the Conversion Feedback API. Defaults to false.
log string	Possible values: true, false, content_only, number_only Defaults to true. If set to true, this message’s phone number and content data (text and media) will be logged on Plivo’s infrastructure. If set to false, this message's phone number and content data (text and media) will not be logged on Plivo’s infrastructure, and the value will be masked (for example, +141XXXXX528). Media URLs will not be logged for MMS messages, and the message's media sub-resource will return an empty list. If set to content_only, this message's content data (text and media) will be logged on Plivo’s infrastructure. Phone number data will be masked. If set to number_only, the phone number data of this message will be logged on Plivo’s infrastructure. Content data (text and media) will be masked. The customer agrees and acknowledges that Plivo may need to override this setting and log the content of some messages from time to time to ensure compliance with the applicable local laws or to monitor and debug for service quality.

Arguments sent in Template Object

name string Required	Name of the template
language string Required	string indicating locale by combining language in ISO 639-1 format and region in ISO 3166-1 format. Ex: en_US, en, en_GB
components object optional	If you have defined dynamic variables in your template, you need to set this object. Array of components objects containing the dynamic parameters of the message. This specifies where the dynamic variables appear in your template and the values against those variables. Review the Components object. Review the Components object.

Arguments sent in Components Object

type string Required	Describes the component type. Supported values are header, body, button. header — Supports dynamic variables of type text or media . body — Supports dynamic variables of type text. button — use this component if your template has a button which accepts dynamic variables. Example use case being - You have defined a url button in your template and you want to append a text parameter to the predefined prefix URL. You have defined a quick reply button in your template and you want to return a developer-defined payload that is returned when the button is clicked in addition to the display text on the button.
sub_type string Required — Conditional	Required when component type=button. This further defines the type of button. Not used for the other types. Supported values are : quick_reply: Refers to a quick reply button that allows for the customer to return a predefined message. url: Refers to a button that allows the customer to visit the URL generated by appending the text parameter to the predefined prefix URL in the template.
index string Required — Conditional	Required when component type is button. Not used for the other types. Position index of the button. You can have up to 10 buttons using index values of 0 to 9.
parametersobject Required	Parameters object describes the parameters and the values that need to replace the dynamic variables defined in your template. Pass the parameters array in the same order in which you have defined this in your templates. Review the Parameters object.

Arguments sent in Parameters Object

type string Required	Describes the parameter type. Supported values: text media (only supported when component type is header) payload (only supported when component type is button)
text string Required — Conditional	This parameter is required when parameter type is text. When component type is header, text can be upto 60 chars long. When component type is body, text can be upto 1024 characters if other component types are included and 32768 characters if body is the only component type included. When component type is button, this is the developer-provided suffix that is appended to the predefined prefix URL in the template. Only applicable when component type is button and component sub type is url
media string Required — Conditional	This parameter can only be passed for component type is header and is required when parameter type is media. Supports images, documents and videos only.For valid file types and maximum file size accepted refer to Meta documentation
payloadstring Required — Conditional	This parameter is required when component type is button, component sub type is quick_reply and parameter type is payload This is the Developer-defined payload that is returned when the button is clicked in addition to the display text on the button.

Returns

Returns a JSON response containing the API request ID and message UUID(s).

Response

HTTP Status Code: 202

{
"message": "message(s) queued",
"message_uuid": ["db3ce55a-7f1d-11e1-8ea7-1231380bc196"],
"api_id": "db342550-7f1d-11e1-8ea7-1231380bc196"
}

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.messages.create(
    src='<from_number>',
    dst='<destination_number>',
    text='Hello, this is sample text',
    url='https://<yourdomain>.com/sms_status/',
    )
print(response)
#prints only the message_uuid
print(response.message_uuid)

1
2
3
4
5
6
7
8
9
10
11
12
13
require "plivo"
include Plivo

api = RestClient.new("<auth_id>","<auth_token>")
response = api.messages.create(
	src: "<from_number>",
	dst:"<destination_number>",
	text:"Hello, this is sample text",
	url: "https://<yourdomain>.com/sms status/",
)
puts response
#Prints only the message_uuid
puts response.message_uuid

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
var plivo = require('plivo');
(function main() {
    'use strict';
    var client = new plivo.Client("<auth_id>", "<auth_token>");
    client.messages.create(
      { 
          src: "<from_number>", 
          dst: "<destination_number>",
          text: "Hello, this is sample text",
          url: "https://<yourdomain>.com/sms_status/"
      }
      ).then(function (response) {
        console.log(response);
    });
})();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");
$response = $client->messages->create(
  [  
    "src" => "<from_number>",
    "dst" => "<destination_number>",
    "text"  =>"Hello, this is sample text",
    "url"=>"https://<yourdomain>.com/sms_status/"
 ]
);
print_r($response);
// Prints only the message_uuid
print_r($response->getmessageUuid(0));
?>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
import java.io.IOException;
import java.net.URL;
import java.util.Collections;

import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.models.message.Message;
import com.plivo.api.models.message.MessageCreateResponse;

class MessageCreate
{
    public static void main(String [] args)
    {
        Plivo.init("<auth_id>","<auth_token>");
        try
        {
            MessageCreateResponse response = Message.creator("<from_number>","+12025551111",
                    "Hello, this is a test message")
                    .url(new URL("https://<yourdomain>.com/sms_status/") )
                    .create();
            System.out.println(response);
            // Prints only the message_uuid
            System.out.println(response.getMessageUuid());
        }

        catch (PlivoRestException | IOException e)
        {
            e.printStackTrace();
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
using System;
using System.Collections.Generic;
using Plivo;

namespace PlivoExamples
{
    internal class Program
    {
        public static void Main(string[] args)
        {
            var api = new PlivoApi("<auth_id>","<auth_token>");
            var response = api.Message.Create(
                src: "<from_number>",
                dst: "<destination_number>",
                text: "Hello, this is sample text",
                url: "https://<yourdomain>.com/sms_status/"
                );
            Console.WriteLine(response);
            // Prints the message_uuid
            Console.WriteLine(response.MessageUuid[0]);
        }
    }
}

1
2
3
4
curl -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    -d '{"src": "<from_number>","dst": "+12025551111", "text": "Hello, this is sample text", "url":"https://<yourdomain>.com/sms_status/"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Message/

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
package main

import (
	"fmt"

	"github.com/plivo/plivo-go/v7"
)

func main() {
	client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	response, err := client.Messages.Create(
		plivo.MessageCreateParams{
			Src:  "<from_number>",
			Dst:  "<destination_number>",
			Text: "Hello, this is sample text",
			URL:  "https://<yourdomain>.com/sms_status/",
		},
	)
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	fmt.Printf("Response: %#v\n", response)
	// Prints only the message_uuid
	fmt.Printf("Response: %#v\n", response.MessageUUID)
}

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
# -*- coding: utf-8 -*-
import plivo

auth_id = "Your AUTH_ID"
auth_token = "Your Auth_TOKEN"

p = plivo.RestAPI(auth_id, auth_token)

params = {
    'src': '1111111111', # Sender's phone number with country code
    'dst' : '2222222222', # Receiver's phone Number with country code
    'text' : u"Hello, how are you?", # Your SMS Text Message - English
    'url' : "https://example.com/report/", # The URL to which with the status of the message is sent
    'method' : 'POST' # The method used to call the url
}

response = p.send_message(params)

# Prints the complete response
print str(response)

# Sample successful output
# (202,
#       {
#               u'message': u'message(s) queued',
#               u'message_uuid': [u'b795906a-8a79-11e4-9bd8-22000afa12b9'],
#               u'api_id': u'b77af520-8a79-11e4-b153-22000abcaa64'
#       }
# )

# Prints only the status code
print str(response[0])

# Sample successful output
# 202

# Prints the message details
print str(response[1])

# Sample successful output
# {
#       u'message': u'message(s) queued',
#       u'message_uuid': [u'b795906a-8a79-11e4-9bd8-22000afa12b9'],
#       u'api_id': u'b77af520-8a79-11e4-b153-22000abcaa64'
# }

# Print the message_uuid
print str(response[1]['message_uuid'])

# Sample successful output
# [u'b795906a-8a79-11e4-9bd8-22000afa12b9']

# Print the api_id
print str(response[1]['api_id'])

# Sample successful output
# b77af520-8a79-11e4-b153-22000abcaa64

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
# encoding: utf-8
require 'rubygems'
require 'plivo'
include Plivo

AUTH_ID = "Your AUTH_ID"
AUTH_TOKEN = "Your AUTH_TOKEN"

p = RestAPI.new(AUTH_ID, AUTH_TOKEN)

# Send SMS
params = {
    'src' => '1111111111', # Sender's phone number with country code
    'dst' => '2222222222', # Receiver's phone Number with country code
    'text' => 'Hi, from Plivo', # Your SMS Text Message - English
    'url' => 'https://example.com/report/', # The URL to which with the status of the message is sent
    'method' => 'POST' # The method used to call the url
}
response = p.send_message(params)
puts response

# Sample Output
# [202,
#   {
#       "api_id"=>"492f5288-9f27-11e4-b153-22000abcaa64",
#       "message"=>"message(s) queued",
#       "message_uuid"=>["494b5c4e-9f27-11e4-b1a4-22000ac693b1"]
#   }
# ]

# Print the message message_uuid
puts response[1]['message_uuid']

# Sample successful output
# ["f58113a2-9fca-11e4-b1a4-22000ac693b1"]

# Print the api_id
puts response[1]['api_id']

# Sample successful output
# f566addc-9fca-11e4-ac1f-22000ac51de6

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
var plivo = require('plivo');
var p = plivo.RestAPI({
  authId: 'Your AUTH_ID',
  authToken: 'Your AUTH_TOKEN'
});

var params = {
    'src': '1111111111', // Sender's phone number with country code
    'dst' : '2222222222', // Receiver's phone Number with country code
    'text' : "Hi, text from Plivo", // Your SMS Text Message - English
    'url' : "https://example.com/report/", // The URL to which with the status of the message is sent
    'method' : "GET" // The method used to call the url
};

// Prints the complete response
p.send_message(params, function (status, response) {
    console.log('Status: ', status);
    console.log('API Response:\n', response);
    console.log('Message UUID:\n', response['message_uuid']);
    console.log('Api ID:\n', response['api_id']);
});

/*
Sample Output

Status:  202
API Response:
 { api_id: 'b91b8736-134b-11e5-b0d7-22000ac520cd',
  message: 'message(s) queued',
  message_uuid: [ '138ee55f-9efb-4fc3-8ad7-4d71219bf56c' ] }

Message UUID:
 [ '138ee55f-9efb-4fc3-8ad7-4d71219bf56c' ]
Api ID:
 b91b8736-134b-11e5-b0d7-22000ac520cd
*/

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
<?php
    require 'vendor/autoload.php';
    use Plivo\RestAPI;
    $auth_id = "Your AUTH_ID";
    $auth_token = "Your AUTH_TOKEN";

    $p = new RestAPI($auth_id, $auth_token);

    // Set message parameters
    $params = array(
        'src' => '1111111111', // Sender's phone number with country code
        'dst' => '2222222222', // Receiver's phone number with country code
        'text' => 'Hi, Message from Plivo', // Your SMS text message
        // To send Unicode text
        'url' => 'https://example.com/report/', // The URL to which with the status of the message is sent
        'method' => 'POST' // The method used to call the url
    );
    // Send message
    $response = $p->send_message($params);

    // Print the response
    echo "Response : ";
    print_r ($response['response']);

    // Print the Api ID
    echo "<br> Api ID : {$response['response']['api_id']} <br>";

    // Print the Message UUID
    echo "Message UUID : {$response['response']['message_uuid'][0]} <br>";

?>

<!--
Sample output
Response : Array
(
    [api_id] => 6debfaec-a25e-11e4-96e3-22000abcb9af
    [message] => message(s) queued
    [message_uuid] => Array ( [0] => 6dffe3ea-a25e-11e4-a6e4-22000afa12b0 )
)
Api ID : 6debfaec-a25e-11e4-96e3-22000abcb9af
Message UUID : 6dffe3ea-a25e-11e4-a6e4-22000afa12b0
-->

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
package com.plivo.test;

import java.util.LinkedHashMap;
import com.plivo.helper.api.client.*;
import com.plivo.helper.api.response.message.MessageResponse;
import com.plivo.helper.exception.PlivoException;

public class SendMessage {
    public static void main(String[] args) {
        String authId = "Your AUTH_ID";
        String authToken = "Your AUTH_TOKEN";
        RestAPI api = new RestAPI(authId, authToken, "v1");

        LinkedHashMap<String, String> parameters = new LinkedHashMap<String, String>();
        parameters.put("src", "1111111111"); // Sender's phone number with country code
        parameters.put("dst", "2222222222"); // Receiver's phone number with country code
        parameters.put("text", "Hi, text from Plivo"); // Your SMS text message
        // Send Unicode text
        parameters.put("url", "https://example.com/report/"); // The URL to which with the status of the message is sent
        parameters.put("method", "GET"); // The method used to call the url

        try {
            // Send the message
            MessageResponse msgResponse = api.sendMessage(parameters);

            // Print the response
            System.out.println(msgResponse);
            // Print the Api ID
            System.out.println("Api ID : " + msgResponse.apiId);
            // Print the Response Message
            System.out.println("Message : " + msgResponse.message);

            if (msgResponse.serverCode == 202) {
                // Print the Message UUID
                System.out.println("Message UUID : " + msgResponse.messageUuids.get(0).toString());
            } else {
                System.out.println(msgResponse.error);
            }
        } catch (PlivoException e) {
            System.out.println(e.getLocalizedMessage());
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
using System;
using System.Collections.Generic;
using System.Reflection;
using RestSharp;
using Plivo.API;

namespace Send_Sms
{
    class Program
    {
        static void Main(string[] args)
        {
            RestAPI plivo = new RestAPI("Your AUTH_ID", "Your AUTH_TOKEN");

            IRestResponse<MessageResponse> resp = plivo.send_message(new Dictionary<string, string>()
            {
                { "src", "1111111111" }, // Sender's phone number with country code
                { "dst", "2222222222" }, // Receiver's phone number wiht country code
                { "text", "Hi, text from Plivo." }, // Your SMS text message
                // To send Unicode text
                { "url", "https://example.com/report/"}, // The URL to which with the status of the message is sent
                { "method", "POST"} // Method to invoke the url
            });

            // Prints the message details
            Console.Write(resp.Content);

            // Print the message_uuid
            Console.WriteLine(resp.Data.message_uuid[0]);

            // Print the api_id
            Console.WriteLine(resp.Data.api_id);

            Console.ReadLine();
        }
    }
}

// Sample Output
/*
{
  "api_id": "e8f04d94-a0ae-11e4-b423-22000ac8a2f8",
  "message": "message(s) queued",
  "message_uuid": [
    "e908608c-a0ae-11e4-89de-22000ae885b8"
  ]
}
Message UUID : e908608c-a0ae-11e4-89de-22000ae885b8
Api ID : e8f04d94-a0ae-11e4-b423-22000ac8a2f8
*/

1
2
3
4
curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"src": "1111111111","dst": "2222222222", "text": "Hi, text from Plivo"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Message/

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
    package main

import (
	"fmt"

	"github.com/plivo/plivo-go/v7"
)

func main() {
	client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	response, err := client.Messages.Create(
		plivo.MessageCreateParams{
			Src:  "<from_number>",
			Dst:  "<destination_number>",
			Text: "Hello, this is sample text",
			URL:  "https://<yourdomain>.com/sms_status/",
		},
	)
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	fmt.Printf("Response: %#v\n", response)
	// Prints only the message_uuid
	fmt.Printf("Response: %#v\n", response.MessageUUID)
}

Rate this page

🥳 Thank you! It means a lot to us!