> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Send SMS/MMS/WhatsApp

> Send outbound SMS, MMS, or WhatsApp messages via the API

This API enables you to send messages via Plivo’s SMS service.

### API Endpoint

```sh POST theme={null}
https://api.plivo.com/v1/Account/{auth_id}/Message/
```

## Arguments

<table>
  <tbody>
    <tr>
      <td><strong>src <span>string</span> <span>Required — Conditional</span></strong></td>

      <td>
        <p>The sender ID you want to use, which may be a phone number, a short code, or an alphanumeric string. For a WhatsApp message, use the phone number associated with your WhatsApp Business Account and mapped to your Plivo account.</p>
        <p>You may use either src or powerpack\_uuid but not both.</p>
        <p>All characters other than A-Z, a-z, and 0-9 are stripped off automatically as part of the sanitization process.</p>
        <p>Sanitized phone numbers must begin with the international country code (for example, 14152828726), and should be \<= 14 characters in length.</p>
        <p>Sanitized alphanumeric sender IDs should be \<= 11 characters in length. Support for alphanumeric sender IDs is <a href="https://support.plivo.com/hc/en-us/articles/360041360512">disabled by default</a>.</p>
        <p>You must have a Plivo phone number to send messages to the US or Canada. You can buy a Plivo number from Phone Numbers > <a href="https://cx.plivo.com/phone-numbers">Buy Numbers</a> on the Plivo console or via the <a href="/numbers/phone-numbers#buy-a-phone-number">Numbers API</a>.</p>
      </td>
    </tr>

    <tr>
      <td><strong>powerpack\_uuid <span>string</span> <span>Required — Conditional</span></strong></td>
      <td><p>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.</p></td>
    </tr>

    <tr>
      <td><strong>dst <span>string</span> <span>Required</span></strong></td>

      <td>
        <p>The phone number to which the message is to be delivered.</p>
        <p>The following characters are stripped off automatically as part of the sanitization process: /, -, ., +, (, ), and white spaces.</p>
        <p>Sanitized phone numbers must begin with the international country code (for example, 14152828726), and should be \<= 14 characters in length.</p>
        <p>To send messages to multiple numbers, separate your destination phone numbers with the delimiter \< — for example, 14156667777\<14157778888\<14158889999.</p>
        <p>When you send WhatsApp messages to multiple destination numbers in a single request, each destination number will result in a unique conversation and will be tracked separately.</p>
      </td>
    </tr>

    <tr>
      <td><strong>text <span>string</span> <span>Required - Conditional</span></strong></td>

      <td>
        <p>The content of the text message.</p>
        <p>For SMS Messages containing only <a href="https://en.wikipedia.org/wiki/GSM_03.38#GSM_7-bit_default_alphabet_and_extension_table_of_3GPP_TS_23.038_.2F_GSM_03.38">GSM 03.38</a> 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.</p>
        <p>Messages containing one or more <a href="https://en.wikipedia.org/wiki/Universal_Coded_Character_Set">UCS-2</a> 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.</p>
        <p>Multiunit messages are automatically stitched back together and delivered as a single message in countries where mobile networks support <a href="https://docs.plivo.com/docs/messaging/concepts/encoding-and-concatenation#concatenation">long message concatenation</a>.</p>
        <p>For WhatsApp messages</p>
        <p>You can send messages with this field when sending freeform messages. Non-templated messages can only be sent when an active conversation is ongoing. If no conversation is ongoing, such messages will fail with error 340.</p>
        <p>Use this parameter when you’re sending freeform (non-templated) text messages. These messages may be no longer than 4,096 characters.</p>
        <p>When sent along with media, this text will be displayed in WhatsApp as a media caption. When sent with media, text may be no longer than 1,024 characters.</p>
      </td>
    </tr>

    <tr>
      <td><strong>type <span>string</span></strong></td>
      <td><p>Allowed values: sms for SMS messages, mms for MMS messages, or whatsapp for WhatsApp messages. Defaults to sms.</p></td>
    </tr>

    <tr>
      <td><strong>media\_urls <span>string</span> <span>Required — Conditional</span></strong></td>

      <td>
        <p>For MMS messages</p>
        <p>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.</p>
        <p>Up to 10 media files may be included in a single MMS message.</p>
        <p>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.</p>
        <p>You may include other media types (audio, video, vcards), but attachments of these types are not optimized for device compatibility.</p>
        <p>The total size of the MMS must not exceed 5MB. Messages exceeding this limit will be marked as Failed with error code 120.</p>
        <p>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.</p>
        <p>For WhatsApp messages</p>
        <p>Use only a single media URL per message. Image, video, documents, and audio files are supported. For valid file types and maximum file size accepted refer to <a href="https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types">Meta documentation</a>.</p>
      </td>
    </tr>

    <tr>
      <td><strong>template <span>object</span> <span>Required — Conditional</span></strong></td>

      <td>
        <p>JSON object to send templated WhatsApp messages when type is whatsapp.</p>
        <p>Message templates are used to initiate conversations with customers. Templated messages are the only types of message that you can send 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.</p>
        <p>You can create templates using WhatsApp Manager.</p>
        <p>Templates are uniquely identified by a combination of template name and language code. Components are used if dynamic variables are sent within a template.</p>
        <p>Here are the arguments sent in the <a href="#template-object">Template object</a>.</p>
      </td>
    </tr>

    <tr>
      <td><strong>interactive <span>object</span> <span>optional</span></strong></td>

      <td>
        <p>JSON object to send interactive WhatsApp messages when type is whatsapp.</p>
        <p>Interactive messages are non-templated messages and cannot be sent unless there is an active conversation. Interactive messages include <a href="https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-messages#list-messages">list buttons</a>, <a href="https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-messages#reply-buttons">reply buttons</a>, <a href="https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-messages#cta-url-buttons">click-to-action url buttons</a>.</p>
        <p>Here are the arguments sent in the <a href="#interactive-object">Interactive object</a>.</p>
      </td>
    </tr>

    <tr>
      <td><strong>location <span>object</span> <span>optional</span></strong></td>

      <td>
        <p>JSON object to define location attributes when type is whatsapp. Location attributes that can be passed are:</p>

        <ul>
          <li>latitude - Location latitude in decimal degrees. Required.</li>
          <li>longitude - Location longitude in decimal degrees. Required.</li>
          <li>name - Location name. Optional</li>
          <li>address - Location address. Optional</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><strong>message\_expiry <span>string</span></strong></td>

      <td>
        <p>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.</p>
        <p>Defaults to 10,800 seconds (3 hours).</p>
      </td>
    </tr>

    <tr>
      <td><strong>url <span>string</span></strong></td>

      <td>
        <p>Set this parameter to the fully qualified URL to which status update callbacks for the message should be sent. Read more about the <a href="https://docs.plivo.com/docs/messaging/api/message">message attributes passed to this callback URL</a>.</p>
      </td>
    </tr>

    <tr>
      <td><strong>dlt\_entity\_id <span>string</span> <span>Deprecated</span></strong></td>

      <td>
        <p>Deprecated. Plivo no longer supports domestic India SMS via DLT; messages to India are delivered over international (ILDO) routes.</p>
      </td>
    </tr>

    <tr>
      <td><strong>dlt\_template\_id <span>string</span> <span>Deprecated</span></strong></td>

      <td>
        <p>Deprecated. Plivo no longer supports domestic India SMS via DLT; messages to India are delivered over international (ILDO) routes.</p>
      </td>
    </tr>

    <tr>
      <td><strong>dlt\_template\_category <span>string</span> <span>Deprecated</span></strong></td>

      <td>
        <p>Deprecated. Plivo no longer supports domestic India SMS via DLT; messages to India are delivered over international (ILDO) routes.</p>
      </td>
    </tr>

    <tr>
      <td><strong>method <span>string</span></strong></td>

      <td>
        <p>The HTTP method to be used when calling the URL defined above.</p>
        <p>Allowed values: GET, POST. Defaults to POST.</p>
      </td>
    </tr>

    <tr>
      <td><strong>trackable <span>boolean</span></strong></td>

      <td>
        <p>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 <a href="https://docs.plivo.com/docs/messaging/concepts/conversion-feedback">Conversion Feedback API</a>.</p>
        <p>Defaults to false.</p>
      </td>
    </tr>

    <tr>
      <td><strong>log <span>string</span></strong></td>

      <td>
        <p>Possible values: true, false, content\_only, number\_only</p>
        <p>Defaults to true.</p>
        <p>If set to true, this message’s phone number and content data (text and media) will be logged on Plivo’s infrastructure.</p>
        <p>If set to false, this message's phone number and content data (text and media) will not be logged on Plivo’s infrastructure, and the value will be masked (for example, +141XXXXX528). Media URLs will not be logged for MMS messages, and the message's media sub-resource will return an empty list.</p>
        <p>If set to content\_only, this message's content data (text and media) will be logged on Plivo’s infrastructure. Phone number data will be masked.</p>
        <p>If set to number\_only, the phone number data of this message will be logged on Plivo’s infrastructure. Content data (text and media) will be masked.</p>
        <p>The customer agrees and acknowledges that Plivo may need to override this setting and log the content of some messages from time to time to ensure compliance with the applicable local laws or to monitor and debug for service quality.</p>
      </td>
    </tr>
  </tbody>
</table>

## Returns

Returns a JSON response containing the API request ID and message UUID(s).

<RequestExample>
  ```py Python theme={null}
  import plivo

  client = plivo.RestClient('<auth_id>','<auth_token>')
  response = client.messages.create(
      powerpack_uuid='<powerpack_uuid>',
      dst='+12025551111<+12025552222',
      text='Hello, this is sample text',
      url='https://<yourdomain>.com/sms_status/',
  )
  print(response)
  #prints only the message_uuid
  print(response.message_uuid)
  ```

  ```ruby Ruby theme={null}
  require "plivo"
  include Plivo

  api = RestClient.new("<auth_id>","<auth_token>")
  response = api.messages.create(
  	src: "+12025550000",
  	dst:"+12025551111"<"+12025552222",
  	text:"Hello, this is sample text",
  	url: "https://<yourdomain>.com/sms status/",
  )
  puts response
  #Prints only the message_uuid
  puts response.message_uuid
  ```

  ```js Node theme={null}
  var plivo = require('plivo');
  (function main() {
      'use strict';
      var client = new plivo.Client("<auth_id>", "<auth_token>");
      client.messages.create(
        {
            src: "+12025550000", 
            dst: "+12025551111<+12025552222",
            text: "Hello, this is sample text",
            url: "https://<yourdomain>.com/sms_status/"
        }
      ).then(function (response) {
          console.log(response);
      });
  })();
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';
  use Plivo\RestClient;

  $client = new RestClient("<auth_id>","<auth_token>");
  $response = $client->messages->create(
    [  
      "src" => "+12025550000",
      "dst" => "+12025551111<+12025552222",
      "text"  =>"Hello, this is sample text",
      "url"=>"https://<yourdomain>.com/sms_status/"
   ]
  );
  print_r($response);
  // Prints only the message_uuid
  print_r($response->getmessageUuid(0));
  ?>
  ```

  ```java Java theme={null}
  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("+12025551111<+12025552222"),
                      "Hello, this is a test message","<powerpack_uuid>")
                      .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();
          }
      }
  }
  ```

  ```csharp .NET theme={null}
  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: "<powerpack_uuid>",
                  dst: new List<String> { "+12025551111<+12025552222" },
                  text: "Hello, this is sample text",
                  url: "https://<yourdomain>.com/sms_status/"
                  );
              Console.WriteLine(response);
              // Prints the message_uuid
              Console.WriteLine(response.MessageUuid[0]);
          }
      }
  }
  ```

  ```go Go theme={null}
  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{
  			PowerpackUUID: "<powerpack_uuid>",
  			Dst:           "+12025551111<+12025552222",
  			Text:          "Hello, this is sample text",
  			URL:           "https://<yourdomain>.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)
  }
  ```

  ```sh cURL theme={null}
  curl -i --user auth_id:auth_token \
      -H "Content-Type: application/json" \
      -d '{"powerpack_uuid": "<powerpack_uuid>","dst": "+12025551111<+12025552222", "text": "Hello, this is sample text"}' \
      https://api.plivo.com/v1/Account/{auth_id}/Message/
  ```
</RequestExample>

### Response

```json theme={null}
{
"message": "message(s) queued",
"message_uuid": ["db3ce55a-7f1d-11e1-8ea7-1231380bc196"],
"api_id": "db342550-7f1d-11e1-8ea7-1231380bc196"
}
```