Send a Long SMS (over the character limit)

A standard SMS contains at most 160 characters (note: the limit is 70 characters when sending Unicode messages). Even though text messages are limited in length, most mobile handsets can display messages longer than the text limit. To the sender and receiver, it is a seamless user experience and feels like you are sending and receiving entire messages at once regardless of the length. In order to ensure that long messages are delivered in its entirety, the SMS service provider needs to support the automatic splitting and concatenation of long SMS messages.

Plivo API’s support sending SMS in all text based languages (e.g., English, French, Chinese, Arabic, etc.). All of Plivo Helper Libraries automatically encode messages into Unicode UTF-8 as needed.

Note: Plivo’s Message API breaks long SMS text messages into multiple SMS and adds a concatenation header to each message so that it can be stitched together (i.e., concatenated) at receiver’s mobile device. Though, some carriers and handsets do not support long SMS concatenation.

SMS Message Length Limits

Depending on the language you are sending in, SMS text messages are limited to either 70 or 160 characters in length. This is because a standard SMS message can contain a maximum of 1120 bits. Latin-based languages such as English, French, and Spanish use GSM encoding, which equates to 7 bits per character; limiting 1 SMS to at most 160 characters. Languages that use Unicode Transformation Format (UTF) encoding such as Chinese, Arabic, or Japanese uses 16 bits per character; limiting 1 SMS to a maximum of 70 characters. Messages containing more than the allowed characters are automatically split and concatenated on the receivers end.

Long Message Delivery Reports

When checking Message Logs and Delivery Reports for long SMS messages that are split, look for the ParentMessageUUID, which is the same in all split messages and identical to the UUID of the first message in the split sequence of messages. Check out our guide on Handling SMS Delivery Reports for details on how to receive delivery reports.

To send an SMS, make an HTTP POST request to the Message API.

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

Advanced Hack: Check out our Message API docs to see how you can get the details of a single message or all your messages in a single GET request.

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. You may send SMS text messages to multiple destinations by using the “<” character (e.g., 2222222222<3333333333).
    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.
    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
# -*- coding: utf-8 -*-
import plivo

auth_id = "Your AUTH_ID"
auth_token = "Your AUTH_TOKEN"

p = plivo.RestAPI(auth_id, auth_token)

# SMS containing more than 160 standard characters, is automatically split as a long SMS.
# SMS containing more than 70 Unicode characters, is automatically split as a long SMS.
# Information about split SMSes are sent to the url and are also reported in the Message Logs in the Account Dashboard.

params = {
    'src': '2222222222', # Sender's phone number
    'dst' : '1111111111', # Receiver's phone Number
    #'text' : u"Ce texte généré aléatoirement peut-être utilisé dans vos maquettes (webdesign, sites internet,livres, affiches...) gratuitement. Ce texte est entièrement libre  de droit. N'hésitez pas à faire un lien sur ce site en utilisant l'image ci-dessous ou en faisant un simple lien texte",
    # Long text in French
    #'text' : u"This randomly generated text can be used in your layout (webdesign , websites, books, posters ... ) for free. This text is entirely free of law. Feel free to link to this site by using the image below or by making a simple text link",
    # Long text in English
    'text' : u"このランダムに生成されたテキストは、自由のためのあなたのレイアウト(ウェブデザイン、ウェブサイト、書籍、ポスター...)で使用することができます。このテキストは、法律の完全に無料です。下の画像を使用して、または単純なテキストリンクを作ることで、このサイトへのリンクフリーです",
    # Long text in Japanese
    'url' : "http://morning-ocean-4669.herokuapp.com/report/", # The URL to which with the status of the message is sent
    'method' : 'GET' # he 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'dcfc1510-9260-11e4-b1a4-22000ac693b1'],
#   u'api_id': u'dce8fb42-9260-11e4-b932-22000ac50fac'
#   }
# )

# Print the Message UUID
uuid = str(response[1]['message_uuid'][0])
# print "Message_uuid : %s " % (uuid)

# Output
# Message_uuid : 2d97bbfe-9262-11e4-9bd8-22000afa12b9'

# To get the SMS split units

params1 = {
    'message_uuid': uuid
}

response1 = p.get_message(params1)

# print "Your SMS was split into %s units" % response1[1]['units']

# Output for Japanese
# Your SMS was split into 3 units

# Output for English
# Your SMS was split into 2 units

# Output for French
# Your SMS was split into 5 units
 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
# 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)

# SMS containing more than 160 standard characters, is automatically split as a long SMS.
# SMS containing more than 70 Unicode characters, is automatically split as a long SMS.
# Information about split SMSes are sent to the url and are also reported in the Message Logs in the Account Dashboard.

# Send SMS
params = {
    'src' => '1111111111', # Sender's phone number with country code
    'dst' => '2222222222', # Receiver's phone Number with country code
    'text' => 'This randomly generated text can be used in your layout (webdesign , websites, books, posters ... ) for free. This text is entirely free of law. Feel free to link to this site by using the image below or by making a simple text link'
    # Your SMS Text Message - English
    #'text' => 'Ce texte généré aléatoirement peut-être utilisé dans vos maquettes (webdesign, sites internet,livres, affiches...) gratuitement. Ce texte est entièrement libre de droit. N'hésitez pas à faire un lien sur ce site en utilisant l'image ci-dessous ou en faisant un simple lien texte',
    # Your SMS Text Message - French
    #'text' => 'このランダムに生成されたテキストは、自由のためのあなたのレイアウト(ウェブデザイン、ウェブサイト、書籍、ポスター...)で使用することができます。このテキストは、法律の完全に無料です。下の画像を使用して、または単純なテキストリンクを作ることで、このサイトへのリンクフリーです',
    # Long text in Japanese
    }

response = p.send_message(params)
# puts response

# Sample Output
# [202, {
#       "api_id"=>"8d982c40-9fa6-11e4-a2d1-22000ac5040c",
#       "message"=>"message(s) queued",
#       "message_uuid"=>["8daae286-9fa6-11e4-a77d-22000ae383ea"]
#   }
# ]

uuid = response[1]['message_uuid'][0]

params1 = {
    'record_id' => uuid
}

response = p.get_message(params1)

# puts "You SMS was split into #{response[1]['units']} units"

# Output for Japanese
# Your SMS was split into 3 units

# Output for English
# Your SMS was split into 2 units

# Output for French
# Your SMS was split into 5 units
 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
var plivo = require('plivo');
var p = plivo.RestAPI({
    "authId": "Your AUTH_ID",
    "authToken": "Your AUTH_TOKEN",
});

// SMS containing more than 160 standard characters, is automatically split as a long SMS.
// SMS containing more than 70 Unicode characters, is automatically split as a long SMS.
// Information about split SMSes are sent to the url and are also reported in the Message Logs in the Account Dashboard.

var params = {
    'src': '1111111111', // Sender's phone number with country code
    'dst' : '2222222222', // Receiver's phone Number with country code
    // Your SMS Text Message - English
    'text' : "This randomly generated text can be used in your layout (webdesign , websites, books, posters ... ) for free. This text is entirely free of law. Feel free to link to this site by using the image below or by making a simple text link"
    // Your SMS Text Message - French
    // 'text' : "Ce texte généré aléatoirement peut-être utilisé dans vos maquettes (webdesign, sites internet,livres, affiches...) gratuitement. Ce texte est entièrement libre de droit. N'hésitez pas à faire un lien sur ce site en utilisant l'image ci-dessous ou en faisant un simple lien texte"
    // Your SMS Text Message - Japanese
    // 'text' : "このランダムに生成されたテキストは、自由のためのあなたのレイアウト(ウェブデザイン、ウェブサイト、書籍、ポスター...)で使用することができます。このテキストは、法律の完全に無料です。下の画像を使用して、または単純なテキストリンクを作ることで、このサイトへのリンクフリーです"
};

p.send_message(params, function (status, response) {
    console.log('Status: ', status);
    console.log('API Response:\n', response);
    var uuid = response['message_uuid'];
    var params1 = {'record_id': uuid};
    p.get_message(params1, function(status, response1){
      console.log("Your SMS was split into " + response1['units'] + ' units');
    });
});

/* 
Sample Output

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

Output for Japanese
Your SMS was split into 3 units

Output for English
Your SMS was split into 2 units

Output for French
Your SMS was split into 5 units
*/
 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
<?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);

    # SMS containing more than 160 standard characters, is automatically split as a long SMS.
    # SMS containing more than 70 Unicode characters, is automatically split as a long SMS.
    # Information about split SMSes are sent to the url and are also reported in the Message Logs in the Account Dashboard.
    
    $params = array(
            'src' => '1111111111', # Sender's phone number
            'dst' => '2222222222', # Receiver's phone Number
            # Long text in English
            'text' => 'This randomly generated text can be used in your layout (webdesign , websites, books, posters ... ) for free. This text is entirely free of law. Feel free to link to this site by using the image below or by making a simple text link'
            # Long text in Japanese
            #'text' => "このランダムに生成されたテキストは、自由のためのあなたのレイアウト(ウェブデザイン、ウェブサイト、書籍、ポスター...)で使用することができます。このテキストは、法律の完全に無料です。下の画像を使用して、または単純なテキストリンクを作ることで、このサイトへのリンクフリーです"
            # Long text in French
            #'text' => "Ce texte généré aléatoirement peut-être utilisé dans vos maquettes (webdesign, sites internet,livres, affiches...) gratuitement. Ce texte est entièrement libre de droit. N'hésitez pas à faire un lien sur ce site en utilisant l'image ci-dessous ou en faisant un simple lien texte"
        );
    $response = $p->send_message($params);

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

    // Print the Message UUID
    $uuid = $response['response']['message_uuid'][0];
    // print $uuid;

    $params = array(
            'record_id' => $uuid // The Message UUID
        );

    // To get the SMS split units
    $r = new RestAPI($auth_id, $auth_token);
    $response = $r->get_message($params);
    $units = $response['response']['units'];

    // Print the response
    print "Your sms was split into : {$units} units";

?>

<!--
Sample Output
(
    [api_id] => dd294730-a262-11e4-b153-22000abcaa64
    [message] => message(s) queued
    [message_uuid] => Array ( [0] => dd4ba604-a262-11e4-a6e4-22000afa12b0 )
)

# Output for Japanese
# Your SMS was split into 3 units

# Output for English
# Your SMS was split into 2 units

# Output for French
# Your SMS was split into 5 units
-->
 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
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 LongMessage {
    public static void main(String[] args) {
        String authId = "Your AUTH_ID";
        String authToken = "Your AUTH_TOKEN";
        RestAPI api = new RestAPI(authId, authToken, "v1");

        // SMS containing more than 160 standard characters, is automatically split as a long SMS.
        // SMS containing more than 70 Unicode characters, is automatically split as a long SMS.
        // Information about split SMSes are sent to the url and are also reported in the Message Logs in the Account Dashboard.

        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", "This randomly generated text can be used in your layout "
                + "(webdesign , websites, books, posters ... ) for free. This text is entirely free of law. "
                + "Feel free to link to this site by using the image below or"
                + " by making a simple text link"); // Your SMS text message

        /*parameters.put("text", "このランダムに生成されたテキストは、自由のためのあなたのレイアウト("
                + "ウェブデザイン、ウェブサイト、書籍、ポスター...)で使用することができます。このテキストは、"
                + "法律の完全に無料です。下の画像を使用して、または単純なテキストリンクを作ることで、"
                + "このサイトへのリンクフリーです"); // Your SMS text message - English
        */
        /*parameters.put("text", "Ce texte généré aléatoirement peut-être utilisé dans vos maquettes"
                + " (webdesign, sites internet,livres, affiches...) gratuitement. "
                + "Ce texte est entièrement libre de droit. N'hésitez pas à faire un "
                + "lien sur ce site en utilisant l'image ci-dessous"
                + "ou en faisant un simple lien texte"); // Your SMS text message - French
        */

        try {
            // Send the Message
            MessageResponse msgResponse = api.sendMessage(parameters);
            // Print the response
            System.out.println(msgResponse);
            // Send the Api ID
            System.out.println("Api ID : " + msgResponse.apiId);
            // Send the Response Message
            System.out.println("Message : " + msgResponse.message);
            if (msgResponse.serverCode == 202) {
                // Print the Message UUID
                String uuid = msgResponse.messageUuids.get(0).toString();
                System.out.println("Message UUID : " + uuid);

                RestAPI apis = new RestAPI(authId, authToken, "v1");

                LinkedHashMap<String, String> params = new LinkedHashMap<String, String>();
                // Message UUID for which the details have to be retrieved
                params.put("record_id", uuid);
                // Get the details of the sent message
                Message msg = apis.getMessage(params);

                // Print the number of units
                System.out.println("Units : " + msg.units);
            } 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
51
52
53
54
55
56
57
58
59
60
61
using System;
using System.Collections.Generic;
using System.Reflection;
using RestSharp;
using Plivo.API;

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

            // SMS containing more than 160 standard characters, is automatically split as a long SMS.
            // SMS containing more than 70 Unicode characters, is automatically split as a long SMS.
            // Information about split SMSes are sent to the url and are also reported in the Message Logs in the Account Dashboard.

            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", "This randomly generated text can be used to test the splitting of Long SMS. SMS splitting information will be present in the url and also in the message logs." } // Your SMS text message - English
                //{ "text", "このランダムに生成されたテキストは、自由のためのあなたのレイアウト(ウェブデザイン、ウェブサイト、書籍、ポスター...)で使用することができます。このテキストは、法律の完全に無料です。下の画像を使用して、または単純なテキストリンクを作ることで、このサイトへのリンクフリーです" } // Your SMS text message - Japanese
                //{ "text", "Ce texte généré aléatoirement peut-être utilisé dans vos maquettes (webdesign, sites internet,livres, affiches...) gratuitement. Ce texte est entièrement libre de droit. N'hésitez pas à faire un lien sur ce site en utilisant l'image ci-dessous ou en faisant un simple lien texte"} // Your SMS text message - French
            });

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

            // Get the details of the sent message
            string uuid = resp.Data.message_uuid[0];

            RestAPI plivo1 = new RestAPI("Your AUTH_ID", "Your AUTH_TOKEN");

            IRestResponse<Message> response = plivo1.get_message(new Dictionary<string, string>()
            {
                { "record_id", uuid } // Message UUID
            });

            Console.WriteLine("Number of units : {0}", response.Data.units);
        }
    }
}

// Sample output
/*
(202, {
   u'message': u'message(s) queued',
   u'message_uuid': [u'dcfc1510-9260-11e4-b1a4-22000ac693b1'],
   u'api_id': u'dce8fb42-9260-11e4-b932-22000ac50fac'
   }
)

For English
Number of units : 2
For Japanese
Number of units : 3
For French
Number of units : 5
*/
1
2
3
4
curl -i --user AUTH_ID:AUTH_TOKEN
    -H "Content-Type: application/json"
    -d '{"src": "1111111111","dst": "2222222222", "text": "This randomly generated text can be used to test the splitting of Long SMS. SMS splitting information will be present in the url and also in the message logs."}'
    https://api.plivo.com/v1/Account/{auth_id}/Message/

Sample Response

(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'
    }
)

Your SMS was split into 2 units

Next Step

Learn how to send multiple (bulk) SMS with a single API request.

  1. Send a Single SMS

  2. Send Multiple (Bulk) 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