Send MMS

    You can send and receive MMS (media messages) in the United States and Canada by using a Plivo phone number that is MMS-enabled.

    In this guide, we’ll see how to use Plivo APIs to send MMS messages to Canada and US from your web application. Let’s have a look at some prerequisites before we dive into the code.

    • Plivo Auth Id and Auth Token: You will find your Plivo Auth Id and Auth Token on the home screen of your Plivo Console. Click here to sign-up for a Plivo account if you haven’t already!
    • Plivo Server-side SDK: The code in this tutorial uses Plivo’s Python Server-side SDK. To get started with the SDK in the language of your choice, visit the Server SDKs page.
    • Plivo Phone Number: Currently, Plivo offers MMS-enabled long code phone numbers in the US and Canada. You must have an MMS enabled valid Plivo phone number to send messages to the US and Canada. You can purchase MMS enabled numbers from the Numbers section of your Plivo Management Console. It is also possible to purchase numbers using the Numbers API.

    Sending MMS Using Plivo REST API

    This tutorial will show you how to send an outbound Multimedia Message Service (MMS) (i.e., picture message) using Plivo’s REST API. This can be used in any web or mobile application that requires communication with end users via MMS messages.

    MMS on Plivo offers full support for common image file types: png, jpeg, and gif and Unicode UTF-8 encoded texts, which means that you can send messages in any language. Delivery reports are also automatically supported in networks where they are provided by the operator.

    To send an MMS, we’ll need to make an HTTP POST request to the Message API.

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

    Getting Started

    1. Sign up for a Plivo trial account.
    2. Check out our server SDKs page and install the right helper based on the programming language you want to use.
    3. Buy an MMS enabled Plivo phone number . You can buy a US or Canadian MMS enabled 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 mms 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 Console.
    3. Add your 'src' (source) phone number. This will show up as your Sender ID.
      Note: In order to send MMS messages to phones in the US or Canada, you will need to purchase a US or Canadian phone number from Plivo which is MMS enabled and use it as the 'src' number. You can buy a Plivo number from the Buy Numbers tab on your Plivo Console. Be sure that the phone number is in E.164 format (e.g., +14153336666).
    4. Add your 'dst' (destination) phone numbers. This is the phone number you will be sending MMS messages to. Be sure that the phone number is in E.164 format (e.g., +15671234567).
      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 text message.
    6. Set Type as MMS. This field is optional for sending SMS and mandatory for sending MMS.
    7. Add the media to be sent via MMS through mediaURLs parameter. This field is optional for sending SMS and mandatory for sending MMS.
    8. Make the 'HTTP POST' request to Plivo. If successful, Plivo will queue your MMS and 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

    import plivo
client = plivo.RestClient("<auth_id>", "<auth_token>")

response = client.messages.create(
    src='<from_number>',
    dst='<to_number>',
    media_ids=['*******-****-****-****-6282a4a96ebe', '*******-****-****-****-6282a4a96ebe', '*******-****-****-****-6282a4a96ebe',
               '*******-****-****-****-6282a4a96ebe'],
               media_urls=['https://media.giphy.com/media/26gscSULUcfKU7dHq/source.gif'],
               type_='mms')
print(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

    require 'rubygems'
require 'plivo'

include Plivo
include Plivo::Exceptions

api = RestClient.new("auth_id", "auth_token")

begin
  response = api.messages.create(
      'src',
      ['dest1'],
      'message_text',
       { 
         url: "http://plivobin.non-prod.plivops.com/1olfi6s1",
         method: "POST",
         trackable: true,
         media_urls:["media_url"],
         type: "mms",
         media_ids:["media_id1","media_id2"]
       }
  )
  puts response
rescue PlivoRESTError => e
  puts 'Exception: ' + e.message
end

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

    let plivo = require('plivo');
let client = new plivo.Client('<auth_id>', '<auth_token>');
client.messages.create(
  " < from number > ", //from
  " < to number > ", // to
  "< text > ", // text
  {
    type: "mms",
    method: "GET",
    url: "http://foo.com/sms_status/",
      media_urls: ["https://media0.giphy.com/media/cmwNV9sYalHK3twjsf/giphy.gif?cid=790b7611241311531367a66f916c7ce5199d4aa61812adbf&rid=giphy.gif", "https://www.cbronline.com/wp-content/uploads/2016/06/what-is-URL-770x503.jpg"],
    media_ids: [" < media_id > "]
  }


).then(function (message_created) {
  console.log(message_created)
}).catch(function (error) {
  console.log(error);
});

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

    <?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("AUTH_ID", "AUTH_TOKEN");
$client->client->setTimeout(40);
try
{

    $mediaURLs = ["<media_url_1>", "<media_url_2>"];
    $mediaIDs = ["<media_id_1>"];
    $response = $client
        ->messages
        ->create("<source_number>", #from
        ["<dest_number>"], #to
        'sample text mms test sdk', 
        ['type' => 'mms', 'media_urls' => $mediaURLs, 'media_ids' => $mediaIDs, 'url' => '<callback_url>']);
    print_r($response);
}
catch(PlivoRestException $ex)
{
    print_r($ex);
}

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

    package com.plivo.api;
import java.io.IOException;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.models.media.Media;

public class Test {
    public static void main(String[] args) {
      Plivo.init("AUTH_ID", "AUTH_TOKEN");
      try {
        System.out.println("'Before Media upload");
        MessageCreateResponse response = Message.creator("src_number",Collections.singletonList("dst_number"),
          "text_message").type(MessageType.MMS)
          .media_urls(new String[]{"media_url"})
          .media_ids(new String[]{"media_id1","media_id2"})
          .create();
        System.out.println(response);
      } catch (IOException e) {
        e.printStackTrace();
      } catch (PlivoRestException 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

    package main

import (
        "fmt"

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

func main() {

        // MAIN ACCOUNT
        client, err := plivo.NewClient("AUTH_ID","AUTH_TOKEN",
                &plivo.ClientOptions{})
        if err != nil {
                panic(err)
        }
        // Send MMS
        createResp, err := client.Messages.Create(plivo.MessageCreateParams{
                Src:  "<source_number>",
                Dst:  "<destination_number>",
                URL:  "<destination_number>",
                Text: "Hi Hello Test - Renold",
                Type: "mms",
                MediaUrls: []string{"<media_url_1>",
                        "<media_url_2>"},
                MediaIds: []string{"<media_uuid_1>"},
        })
        if err != nil {
                panic(err)
        }

    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

    using System;
using System.Collections.Generic;
using Plivo;
using Plivo.Exception;

namespace SdkTestDotnet
{
    class Program
    {
        static void Main(string[] args)
        {
            var api = new PlivoApi("AUTH_ID", "AUTH_TOKEN");
            try
            {
                var response = api.Message.Create(
                    src:"<source_number>",
                    dst:new List<String>{"<detination_number>"},
                    text:"Hello, world!",
                    type:"mms",
                    media_urls: new string[]{"media_url"},
                    media_ids: new String[]{"media_id1","media_id2"}
                );
                Console.WriteLine(response);
            }
            catch (PlivoRestException e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}

    1
2
3
4

    curl -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    -d '{"src": "your_src_number","dst": "+14152223333", "text": "Hello, this is test message","type":"mms","media_urls":["http://www.pdf995.com/samples/pdf.pdf"], "url":"http://foo.com/sms_status/"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Message/

    Send MMS using Powerpack

    You can choose to send MMS using a powerpack that will help you have a consistent high message delivery rate. Using Powerpacks, you can distribute your MMS traffic across a group of phone numbers in your account for improved delivery. Refer to the Powerpack Detailed reference for more information.

    Example

    1
2
3
4
5
6
7
8
9
10
11

    import plivo
client = plivo.RestClient("<auth_id>", "<auth_token>")

response = client.messages.create(
    powerpack_uuid='<your_powerpack_uuid>',
    dst='<to_number>',
    media_ids=['*******-****-****-****-6282a4a96ebe', '*******-****-****-****-6282a4a96ebe', '*******-****-****-****-6282a4a96ebe',
               '*******-****-****-****-6282a4a96ebe'],
               media_urls=['https://media.giphy.com/media/26gscSULUcfKU7dHq/source.gif'],
               type_='mms')
print(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

    require 'rubygems'
require 'plivo'

include Plivo
include Plivo::Exceptions

api = RestClient.new("auth_id", "auth_token")

begin
  response = api.messages.create(
      nil, #from
      ['dest1'],
      'message_text',
       { 
         url: "http://plivobin.non-prod.plivops.com/1olfi6s1",
         method: "POST",
         trackable: true,
         media_urls:["media_url"],
         type: "mms",
         media_ids:["media_id1","media_id2"]
       },
       "your_powerpack_uuid", #Powerpack_UUID
  )
  puts response
rescue PlivoRESTError => e
  puts 'Exception: ' + e.message
end

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

    let plivo = require('plivo');
let client = new plivo.Client('<auth_id>', '<auth_token>');
client.messages.create(
    null, //from
  " < to number > ", // to
  "< text > ", // text
  {
    type: "mms",
    method: "GET",
    url: "http://foo.com/sms_status/",
      media_urls: ["https://media0.giphy.com/media/cmwNV9sYalHK3twjsf/giphy.gif?cid=790b7611241311531367a66f916c7ce5199d4aa61812adbf&rid=giphy.gif", "https://www.cbronline.com/wp-content/uploads/2016/06/what-is-URL-770x503.jpg"],
    media_ids: [" < media_id > "]
  },
  "your_powerpack_uuid" //powerpack_uuid

).then(function (message_created) {
  console.log(message_created)
}).catch(function (error) {
  console.log(error);
});

    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

    <?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient("AUTH_ID", "AUTH_TOKEN");
$client->client->setTimeout(40);
try
{

    $mediaURLs = ["<media_url_1>", "<media_url_2>"];
    $mediaIDs = ["<media_id_1>"];
    $response = $client
        ->messages
        ->create(null, #from
        ["<dest_number>"], #to
        'sample text mms test sdk', 
        ['type' => 'mms', 'media_urls' => $mediaURLs, 'media_ids' => $mediaIDs, 'url' => '<callback_url>',
        'your_powerpack_uuid' #powerpack_uuid
        ]);
    print_r($response);
}
catch(PlivoRestException $ex)
{
    print_r($ex);
}

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

    package com.plivo.api;
import java.io.IOException;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.models.media.Media;

public class Test {
    public static void main(String[] args) {
      Plivo.init("AUTH_ID", "AUTH_TOKEN");
      try {
        System.out.println("'Before Media upload");
        MessageCreateResponse response = Message.creator(Collections.singletonList("dst_number"),
          "text_message", "your_powerpack_uuid").type(MessageType.MMS)
          .media_urls(new String[]{"media_url"})
          .media_ids(new String[]{"media_id1","media_id2"})
          .create();
        System.out.println(response);
      } catch (IOException e) {
        e.printStackTrace();
      } catch (PlivoRestException 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

    package main

import (
        "fmt"

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

func main() {

        // MAIN ACCOUNT
        client, err := plivo.NewClient("AUTH_ID","AUTH_TOKEN",
                &plivo.ClientOptions{})
        if err != nil {
                panic(err)
        }
        // Send MMS
        createResp, err := client.Messages.Create(plivo.MessageCreateParams{
				PowerpackUUID: "your_powerpack_uuid",
                Dst:  "<destination_number>",
                URL:  "<destination_number>",
                Text: "Hi Hello Test - Renold",
                Type: "mms",
                MediaUrls: []string{"<media_url_1>",
                        "<media_url_2>"},
                MediaIds: []string{"<media_uuid_1>"},
        })
        if err != nil {
                panic(err)
        }

    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

    using System;
using System.Collections.Generic;
using Plivo;
using Plivo.Exception;

namespace SdkTestDotnet
{
    class Program
    {
        static void Main(string[] args)
        {
            var api = new PlivoApi("AUTH_ID", "AUTH_TOKEN");
            try
            {
                var response = api.Message.Create(
                    powerpack_uuid: "your_powerpack_uuid",
                    dst:new List<String>{"<detination_number>"},
                    text:"Hello, world!",
                    type:"mms",
                    media_urls: new string[]{"media_url"},
                    media_ids: new String[]{"media_id1","media_id2"}
                );
                Console.WriteLine(response);
            }
            catch (PlivoRestException e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}

    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","type":"mms","media_urls":["http://www.pdf995.com/samples/pdf.pdf"], "url":"http://foo.com/sms_status/"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Message/