Send Multiple (Bulk) SMS

An unique feature of Plivo’s REST APIs is that you can send bulk (multiple) SMS using a single API request. To send bulk SMS, make an HTTP POST request to the Message API similar to sending a single outbound SMS, with the additional step of adding multiple dst destination numbers by separating each phone number with the "<" character.

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

Prerequisites

  1. Sign up for a free Plivo trial account.
  2. Check out our Helper Libraries page and install the right helper based on the programming language you want to use.
  3. Buy a Plivo phone number (optional).
    Note: A phone number is required only for sending SMS to US and Canadian phone numbers. However, country-specific carrier conditions may still apply. You can buy a US or Canadian phone number through the Buy Numbers tab on your Plivo account UI.
  4. Use a web hosting service to host your web application. There are many inexpensive cloud hosting providers that you can use for just a few dollars a month. Follow the instructions of your hosting provider to host your web application.
    Note: If you are using a Plivo Trial account for this example, you can only send sms to phone numbers that have been verified with Plivo. Phone numbers can be verified at the Sandbox Numbers page.

Implementation

  1. Copy the relevant code below into a text file and save it.
  2. Replace Your AUTH_ID and Your AUTH_TOKEN with the AUTH ID and AUTH TOKEN found on your Plivo dashboard.
  3. Add your src (source) phone number. This will show up as your Sender ID. Be sure that all phone numbers include country code, area code, and phone number without spaces or dashes (e.g., 14153336666).
    Note: You can send SMS text messages to any country using the Message API and set any src number except for US and Canadian numbers. In order to send text messages to phones in the US or Canada, you will need to purchase a US or Canadian phone number from Plivo and use it as the src number. You can buy a Plivo number from the Buy Numbers tab on your Plivo account dashboard.
  4. Add your dst (destination) phone numbers. These are the phone numbers you wish to send SMS text messages to. To send messages in bulk, separate your destination phone numbers with the delimiter "<" (e.g., 14156667777<14157778888<14158889999).
    Note: If you are using a trial account, your destination number needs to be verified with Plivo. Phone numbers can be verified at the Sandbox Numbers page.
  5. Edit the text field with your SMS text message.
    Note: text messages that are longer than 160 characters are concatenated and billed separately as individual text messages.
  6. Make the HTTP POST request to Plivo. If successful, Plivo will queue your SMS deliver it to your recipients at a base rate of 1 message per second.
    Note: delivery is handled separately for each message.
    Advanced hack: Check out our full Message API docs to see all the parameters and functionalities you can use.

Code

 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
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
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<3333333333', # Receivers' phone numbers with country code. The numbers are separated by "<" delimiter.
    'text' : "Hi, from Plivo" # Your SMS Text Message
}

response = p.send_message(params)

# Print the entire response
print str(response)

# Sample sucessful output
# (202, {
#       u'message': u'message(s) queued',
#       u'message_uuid': [
#               u'2d55d550-8a73-11e4-9bd8-22000afa12b9',
#               u'2d5617e0-8a73-11e4-89de-22000ae885b8'
#       ],
#       u'api_id': u'2d30af46-8a73-11e4-96e3-22000abcb9af'
#       }
# )

# Print only the status code
print response[0]

# Sample successful output
# 202

# Print the message uuid
print response[1]['message_uuid']

# Sample successful output
#[
#       u'2d55d550-8a73-11e4-9bd8-22000afa12b9',
#       u'2d5617e0-8a73-11e4-89de-22000ae885b8'
#]

# Loop through the message uuids

# for uuid in response[1]['message_uuid']:
#     print uuid

# Sample successful output
#       2d55d550-8a73-11e4-9bd8-22000afa12b9
#       2d5617e0-8a73-11e4-89de-22000ae885b8

# When an invalid number is given as dst parameter, an error will be thrown and the message will not be sent

# params = {
#     'src': '1111111111', # Sender's phone number with country code
#     'dst' : '2222222222<333333', # Receivers' phone numbers with country code. The numbers are separated by "<" delimiter.
#     'text' : "Hi, from Plivo" # Your SMS Text Message
# }

# response = p.send_message(params)

# Print the entire response
# print str(response)

# Sample output
# (400, {
#   u'api_id': u'6b07a5de-8f7f-11e4-b932-22000ac50fac',
#   u'error': u'1111111 is not a valid phone number'
#   }
# )
 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
58
59
60
61
62
63
64
65
66
67
# 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<3333333333', # Receivers' phone numbers with country code. The numbers are separated by "<" delimiter.
    'text' => 'Hi, from Plivo' # Your SMS Text Message - English
}
response = p.send_message(params)
puts response

# Sample Output
# [202, {
#       "api_id"=>"30bff606-9f97-11e4-b423-22000ac8a2f8",
#       "message"=>"message(s) queued",
#       "message_uuid"=>[
#           "30ea0cd4-9f97-11e4-b1a4-22000ac693b1",
#           "30e974ae-9f97-11e4-9bd8-22000afa12b9"
#       ]
#   }
# ]

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

# Sample Output
#["a31c2166-9f97-11e4-a77d-22000ae383ea", "a31bfd58-9f97-11e4-9bd8-22000afa12b9"]

# Loop through the message uuids

for uuid in response[1]['message_uuid']
    puts uuid
end

# Sample Output
# a31c2166-9f97-11e4-a77d-22000ae383ea
# a31bfd58-9f97-11e4-9bd8-22000afa12b9

# When an invalid number is given as dst parameter, an error will be thrown and the message will not be sent

# params1 = {
#     'src' => '1111111111', # Sender's phone number with country code
#     'dst' => '2222222222<333333', # Receivers' phone numbers with country code. The numbers are separated by "<" delimiter.
#     'text' => "Hi, from Plivo" # Your SMS Text Message
# }

# response = p.send_message(params1)

# Print the entire response
# puts response

# Sample output
# (400, {
#   u'api_id': u'6b07a5de-8f7f-11e4-b932-22000ac50fac',
#   u'error': u'333333 is not a valid phone number'
#   }
# )
 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
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<3333333333', // Receiver's phone Number with country code
    'text' : "Hi, message from Plivo" // Your SMS Text Message
};

p.send_message(params, function (status, response) {
    console.log('Status: ', status);
    console.log('API Response:\n', response);
    for (var uuid in response['message_uuid']){
        console.log('Message UUID : ', response['message_uuid'][uuid] );
    }
});

// When an invalid number is given as dst parameter, an error will be thrown and the message will not be sent

var params1 = {
    'src': '1111111111', // Sender's phone number with country code
    'dst' : '2222222222<33333', // Receiver's phone Number with country code
    'text' : "Hi, message from Plivo" // Your SMS Text Message
};

p.send_message(params1, function (status, response) {
    console.log('Status: ', status);
    console.log('API Response:\n', response);
});

/*
Sample Output

Status:  202
API Response:
 { api_id: '816e4650-7195-11e5-bfb4-22000afc235b',
  message: 'message(s) queued',
  message_uuid:
   [ '2b59a36d-9368-4a63-8578-82ab4e74c163',
     'eeca2f78-e20a-45d6-a5d0-a9c0a19c1605' ] }
Message UUID :  2b59a36d-9368-4a63-8578-82ab4e74c163
Message UUID :  eeca2f78-e20a-45d6-a5d0-a9c0a19c1605

Sample Output for invalid number
Status:  400
API Response:
 { api_id: '92bc9f68-7195-11e5-8620-22000af98256',
  error: '33333 is not a valid phone number' }
*/
 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
<?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);
    // Send a message
    $params = array(
            'src' => '1111111111', // Sender's phone number with country code
            'dst' => '2222222222<3333333333', // receiver's phone number with country code
            'text' => 'Hi, Message from Plivo' // Your SMS text message
        );
    // Send message
    $response = $p->send_message($params);

    // Print the response
    print_r ($response['response']);

    // Loop throught the message uuids
    $uuids = $response['response']['message_uuid'];

    // Print the uuids
    foreach($uuids as $value){
        print_r ("Message UUID : {$value} <br>");
    }

    // When an invalid number is given as dst parameter, an error will be thrown and the message will not be sent
    $r = new RestAPI($auth_id, $auth_token);

    $params = array(
            'src' => '1111111111', // Sender's phone number with country code
            'dst' => '2222222222<33333', // receiver's phone number with country code
            'text' => 'Hi, Message from Plivo' // Your SMS text message
       );
    // Send message
    $response = $r->send_message($params);

    // Print the response
    print_r ($response['response']);
?>

<!--
Sample Output
(
    [api_id] => 266dd470-a262-11e4-b153-22000abcaa64
    [message] => message(s) queued
    [message_uuid] => Array ( [0] => 2698aefc-a262-11e4-890b-22000aec819c [1] => 26989ff2-a262-11e4-b328-22000afd044b )
)
    Message UUID : 2698aefc-a262-11e4-890b-22000aec819c
    Message UUID : 26989ff2-a262-11e4-b328-22000afd044b

Sample Output for invalid destination number
(
    [api_id] => 24239bca-a878-11e4-b932-22000ac50fac
    [error] => 33333 is not a valid phone number
)
-->
 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
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
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 BulkMessage {
    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<3333333333"); // Receivers' phone numbers with country code. The numbers are separated by "<" delimiter.
        parameters.put("text", "Hi, from Plivo"); // Your SMS text message

        try {
            // Send the messages
            MessageResponse msgResponse = api.sendMessage(parameters);
            // Print the response
            System.out.println(msgResponse);
            // Loop through the Message UUID
            if (msgResponse.serverCode == 202) {
                int count = msgResponse.messageUuids.size();
                for (int i = 0 ; i < count ; i++){
                    // Print the Message UUID
                    System.out.println("Message UUID : " + msgResponse.messageUuids.get(i).toString());
                }
            } else {
                System.out.println(msgResponse.error);
            }
        } catch (PlivoException e) {
            System.out.println(e.getLocalizedMessage());
        }

        // When an invalid number is given as dst parameter, an error will be thrown and the message will not be sent
        LinkedHashMap<String, String> parameters = new LinkedHashMap<String, String>();
        parameters.put("src", "1111111111"); // Sender's phone number with country code
        parameters.put("dst", "2222222222<33333"); // Receivers' phone numbers with country code. The numbers are separated by "<" delimiter.
        parameters.put("text", "Hi, from Plivo"); // Your SMS text message

        try {
            // Send the messages
            MessageResponse msgResponse = api.sendMessage(parameters);
            // Print the response
            System.out.println(msgResponse);
        } catch (PlivoException e) {
            System.out.println(e.getLocalizedMessage());
        }

    }
}

// Sample output
/*
MessageResponse [
    serverCode=202,
    message=message(s) queued,
    messageUuids=[7e026888-c713-11e4-a564-22000ac6807d, 7e02984e-c713-11e4-8672-22000aff09d1],
    error=null,
    apiId=7de80790-c713-11e4-b423-22000ac8a2f8
]
Message UUID : 7e026888-c713-11e4-a564-22000ac6807d
Message UUID : 7e02984e-c713-11e4-8672-22000aff09d1
Sample Output for invalid number
MessageResponse [
    serverCode=400,
    message=null,
    messageUuids=null,
    error=1111 is not a valid phone number,
    apiId=a7265314-c713-11e4-b423-22000ac8a2f8
]
1111 is not a valid phone number
*/
 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
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
using System;
using System.Collections.Generic;
using System.Reflection;
using RestSharp;
using Plivo.API;

namespace Bulk_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<3333333333" }, // Receiver's phone number wiht country code
                { "text", "Hi, text from Plivo." } // Your SMS text message
            });

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

            // Loop through the message_uuid
            int count = resp.Data.message_uuid.Count;
            for (int i = 0; i < count; i++)
            {
                Console.WriteLine("Message UUID : {0}", resp.Data.message_uuid[i]);
            }

            // Print the api_id
            Console.WriteLine("Api ID : {0}", resp.Data.api_id);

            // When an invalid number is given as a dst parameter, an error will be thrown and the message will not be sent
            IRestResponse<MessageResponse> response = plivo.send_message(new Dictionary<string, string>()
            {
                { "src", "1111111111" }, // Sender's phone number with country code
                { "dst", "111111<2222222222" }, // Receiver's phone number wiht country code
                { "text", "Hi, text from Plivo." } // Your SMS text message
            });

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

            Console.ReadLine();
		}
	}
}

// Sample output
/*
{
  "api_id": "a6d93290-a0b3-11e4-96e3-22000abcb9af",
  "message": "message(s) queued",
  "message_uuid": [
    "a6f4f17e-a0b3-11e4-89de-22000ae885b8",
    "a6f4eeae-a0b3-11e4-9bd8-22000afa12b9"
  ]
}
Message UUID : a6f4f17e-a0b3-11e4-89de-22000ae885b8
Message UUID : a6f4eeae-a0b3-11e4-9bd8-22000afa12b9
Api ID : a6d93290-a0b3-11e4-96e3-22000abcb9af
*/

// Sample Output for an invalid number
/*
{
  "api_id": "e5f6c53c-a0b3-11e4-a2d1-22000ac5040c",
  "error": "111111 is not a valid phone number"
}
*/
1
2
3
4
curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"src": "1111111111","dst": "2222222222<3333333333", "text": "Hi, text from Plivo"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Message/

Sample Response

(202,
    {
        u'message': u'message(s) queued',
        u'message_uuid': [
            u'2d55d550-8a73-11e4-9bd8-22000afa12b9',
            u'2d5617e0-8a73-11e4-89de-22000ae885b8'
        ],
        u'api_id': u'2d30af46-8a73-11e4-96e3-22000abcb9af'
    }
)

Next Step

Learn how to customize your SMS sender ID with alphanumeric characters.

  1. Send a Single SMS
  2. Send a Long SMS

  3. Send an SMS with Alphanumeric Sender ID
  4. Receive an SMS
  5. Reply to an Incoming SMS
  6. Forward an Incoming SMS
  7. Get Details of all Messages
  8. Get Details of a Single Message
  9. Handling SMS Delivery Reports
  10. Forward SMS to Email