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

    srcConditionalstring

    Set this parameter to the sender ID you wish to use. This could a phone number, shortcode or alphanumeric string.

    All characters other than A-Z, a-z, 0-9 are stripped off automatically as part of the sanitization process.

    Sanitized phone numbers must begin with the international country code (ex: 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. Learn more about alphanumeric sender ID whitelisting here.

    Note that a Plivo phone number is required for sending messages to the U.S. or Canada. You can buy a Plivo number from the Buy Numbers tab on your Plivo dashboard or via the Numbers API.

    powerpack_uuidConditionalstring

    Set this to the UUID of the SMS Powerpack you wish to use for this SMS. The src request parameter should not be included when sending messages using Powerpack.

    dstRequiredstring

    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 (ex: 14152828726), and should be <= 14 characters in length.

    To send messages to multiple numbers, separate your destination phone numbers with the delimiter <. (e.g. 14156667777<14157778888<14158889999).

    textRequiredstring

    Set this parameter to the content of the text message.

    Messages containing only GSM03.38 7 bit characters have a maximum limit of 1600 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.

    Multi-unit messages are automatically stitched back together and delivered as a single message in countries where mobile networks support long message concatenation.

    type string

    Set this parameter either assms for SMS messages or as mms for MMS messages. Defaults to sms.

    media_urlsConditionalstring

    A comma separated list of URL encoded hyperlinks to the images or gifs 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.

    Images of type gif, png, and jpeg will be formatted correctly for device compatibility before being forwarded downstream. Plivo may also resize the image if the original attachment exceeds the max size supported by the destination network.

    Other media types (audio, video, vcards) can also be included however it will not be 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. The actual ordering however cannot be guaranteed.

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

    method string

    The HTTP method to be used when calling the url defined above. Defaults to POST when not specified. Note that only GET and POST are presently supported.

    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 (e.g., +141XXXXX528). For mms messages, media URLs will not be logged, and the message’s Media Subresource will return an empty list. This parameter defaults to true when not specified.

    trackable boolean

    Set this parameter to true for messages that have a trackable user action, for example, 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. Read our guide on Providing Conversion Feedback for trackable SMS messages for details. This parameter defaults to false when no specified.

    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(
        powerpack_uuid='your_powerpack_uuid',
        dst='+14152223333',
        text='Hello, this is a sample text',
        url='http://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
    
    require "plivo"
    include Plivo
    
    api = RestClient.new("auth_id", "auth_token")
    response = api.messages.create(
        nil, #from
        ["+14152223333"], #to
        "Hello, this is a sample text", #text
        { url: "http://foo.com/sms_status/"},
        "your_powerpack_uuid",
      )
      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
    
    var plivo = require('plivo');
    
    (function main() {
        'use strict';
        var client = new plivo.Client("auth_id","auth_token");
        client.messages.create(
            null,
            "+14151112222, //dst
            "Hello, this is a sample text from Plivo", // text
            {method: "GET",url:"http://foo.com/sms_status/"},
            "your_powerpack_uuid" //powerpack_uuid
    
          ).then(function (response) {
            console.log(response);
            //Prints only the message_uuid
            console.log(response.messageUuid);
          },);
        })();
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    
    <?php
    require 'vendor/autoload.php';
    use Plivo\RestClient;
    
    $client = new RestClient("auth_id", "auth_token");
    $response = $client->messages->create(
      null, #from
      ['+14152223333'], #to
      "Hello, this is a sample text", #text
      ["url"=>"http://foo.com/sms_status/"],
      'your_powerpack_uuid'
    );
    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(Collections.singletonList("+14151112222"),
                        "Hello, this is test message","your_powerpack_uuid")
                        .url(new URL("http://foo.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(
                    powerpack_uuid: "your_powerpack_uuid",
                    dst: new List<String> { "+14151112222" },
                    text: "Hello, this is sample text",
                    url: "http://foo.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 '{"powerpack_uuid": "your_powerpack_uuid","dst": "+14152223333", "text": "Hello, this is test message", "url":"http://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
    
    package main
    
    import "fmt"
    import "github.com/plivo/plivo-go"
    
    func main() {
    	client, err := plivo.NewClient("auth_id", "auth_token", &plivo.ClientOptions{})
    	if err != nil {
    		panic(err)
    	}
    	response, err := client.Messages.Create(
    		plivo.MessageCreateParams{
    			PowerpackUUID: "your_powerpack_uuid",
    			Dst:       "+14151112222",
    			Text:      "Hello, this is a sample text",
    			URL:       "http://foo.com/sms_status/",
    		},
    	)
    	if err != nil {
    		panic(err)
    	}
    	fmt.Printf("Response: %#v\n", response)
    	// Prints only the message_uuid
    	fmt.Printf("Response: %#v\n", response.MessageUUID)
    }