Send a Message | Plivo API Reference

Latest Legacy

Send SMS/MMS

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

srcstringRequired — Conditional	Set this parameter to the sender ID you wish to use. This could a phone number, a short code, or an alphanumeric string. For a WhatsApp message, make sure you are using the phone number associated to 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 towards 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. Note that 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_uuidstringRequired — 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.
dststringRequired	Set this parameter to 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 WhatsApp messages are sent to multiple destination numbers in a single request, each destination number will result in a unique conversation and will be tracked separately.
textstringRequired - Conditional	Set this parameter to 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 while sending non-templated messages (refer 'template' argument below). Non-templated messages can only be sent when an active conversation is ongoing. If there is no conversation ongoing, such messages will fail with error 340. Use this parameter when you are sending free form (non-templated) text messages. This can be a max of 4096 characters long. When sent along with media, this will be displayed in WhatsApp application as a media caption. When sent with media, this can be a max of 1024 characters long only.
type_ string	Set this parameter to sms for SMS messages or as mms for MMS messages or as whatsapp for WhatsApp messages. Defaults to sms.
media_urlsstringRequired — 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 Media Messages Use only a single media_url per message. Supports image, video, documents and audio files. For valid file types and maximum file size accepted refer to Meta documentation
templatejsonRequired — Conditional	Set this json object to send templated whatsApp messages and when type is whatsapp. Message templates are used to initiate conversations with customers. Unlike other types of messages, message templates are the only type of message that can be sent 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 on WhatsApp template manager. A template is uniquely identified using combination of template name and language code. Components are used if dynamic variables are sent within the templates. Here are the arguments sent in the json. name (required) - string language (required) - string indicating language ex: en_US format components (optional) - defines where your dynamic variables appear in your template header - Supports dynamic variables of type - text or media. Text can be max of 60 chars. body -Supports dynamic variables of type - text. Text can be max of 1024 chars.
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_idstringRequired — 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_idstringRequired — 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_categorystringRequired — 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
log boolean	If set to false, the text and media content of this message will not be logged on Plivo infrastructure, and the dst value will be masked (for example, +141XXXXX528). For MMS messages, media URLs will not be logged, and the message’s Media subresource will return an empty list. Defaults to true.
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.

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
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
import plivo
from plivo.utils.template import Template

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.messages.create(   
        src="+14151112221",
        dst="+14151112222",
        type_="whatsapp",
        template=Template(**{ 
            "name": "sample_purchase_feedback",
            "language": "en_US",
            "components": [
                {
                    "type": "header",
                    "parameters": [
                        {
                            "type": "media",
                            "media": "https://plivo.com/s3/img1.jpg"
                        }
                    ]
                },
                {
                    "type": "body",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "Livpure Water Purifier"
                        }
                    ]
                }
            ]
          }
       ),
        url="https://foo.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
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
require "plivo"
include Plivo

api = RestClient.new("<auth_id>","<auth_token>")
response = api.messages.create(
	src: "+14151112221",
  dst: "+14151112222",
  type: "whatsapp",
  template: {
    "name": "sample_purchase_feedback",
    "language": "en_US",
    "component": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "media",
            "media": "https://plivo.com/s3/img1.jpg"
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Livpure Water Purifier"
          }
        ]
      }
    ]
    },
    url: "https://foo.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
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
var plivo = require('plivo');
(function main() {
    'use strict';
    var client = new plivo.Client("<auth_id>", "<auth_token>");
    client.messages.create(
      { 
          src: "+14151112221",
          dst: "+14151112222",
          type_: "whatsapp",
          template: {
            "name": "sample_purchase_feedback",
            "language": "en_US",
            "component": [
              {
                "type": "header",
                "parameters": [
                  {
                    "type": "media",
                    "media": "https://plivo.com/s3/img1.jpg"
                  }
                ]
              },
              {
                "type": "body",
                "parameters": [
                  {
                    "type": "text",
                    "text": "Livpure Water Purifier"
                  }
                ]
              }
            ]
          },
          url: "https://foo.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
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("<auth_id>","<auth_token>");
$response = $client->messages->create(
  [  
    "src" => "+14151112221",
    "dst" => "+14151112222",
    "type_" => "whatsapp",
    "template" => [
      "name" => "sample_purchase_feedback",
      "language" => "en_US",
      "component" => [
        [
          "type" => "header",
          "parameters" => [
            [
              "type" => "media",
              "media" => "https://plivo.com/s3/img1.jpg"
            ]
          ]
        ],
        [
          "type" => "body",
          "parameters" => [
            [
              "type" => "text",
              "text" => "Livpure Water Purifier"
            ]
          ]
        ]
      ]
    ],
    "url" => "https://foo.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
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
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: "+14151112221",
                dst: "+14151112222",
                type_: "whatsapp",
                template: {
                  name: sample_purchase_feedback",
                  language: "en_US",
                  component: [
                    {
                     type : "header",
                     parameters: [
                      {
                        type: "media",
                        media: "https://plivo.com/s3/img1.jpg"
                      }
                    ]
                  },
                    {
                      type : "body",
                      parameters: [
                        {
                          type: "text",
                          text: "Livpure Water Purifier"
                        }
                      ] 
                  },
                ] 
               }
              url: "https://foo.com/sms_status/"
                );
            Console.WriteLine(response);
            // Prints the message_uuid
            Console.WriteLine(response.MessageUuid[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
32
curl -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    -d '{
          "src": "+14151112221",
          "dst": "+14152223333", 
          "type": "whatsapp", 
          "template": {
            "name": "sample_purchase_feedback",
            "language": "en_us"
            "components": [
              {
                "type" : "header",
                "parameters": [
                {
                  "type": "media",
                  "media": "https://plivo.com/s3/img1.jpg"
                }
                ]
              },
              {
                "type" : "body",
                "parameters": [
                  {
                    "type": "text",
                    "text": "Livpure Water Purifier"
                  }
                ] 
                },
              ]
            },
          "url":"https://foo.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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
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: "+14151112221",
      Dst: "+14151112222",
      Type_: "whatsapp",
      Template: plivo.Template{
          Name: "sample_purchase_feedback",
          Language: "en_US",
          Component: []plivo.Component{
              {
                  Type: "header",
                  Parameters: []plivo.Parameter{
                      {
                          Type: "media",
                          Media: "https://plivo.com/s3/img1.jpg",
                      },
                  },
              },
              {
                  Type: "body",
                  Parameters: []plivo.Parameter{
                      {
                          Type: "text",
                          Text: "Livpure Water Purifier",
                      },
                  },
              },
          },
      },
      Url: "https://foo.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!