Send SMS/MMS/WhatsApp
This API enables you to send messages via Plivo’s SMS service.
API Endpoint
Arguments
src string Required — Conditional | 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. You may use either If you’re sending a message toward India and are registered on a DLT portal, use the registered DLT header that’s mapped to the template you’re sending. All characters other than Sanitized phone numbers must begin with the international country code (for example, 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. You must have a Plivo phone number to send messages to the US or Canada. You can buy a Plivo number from Phone Numbers > Buy Numbers on the Plivo console or via the Numbers API. |
powerpack_uuid string Required — Conditional | Set this to the UUID of the SMS Powerpack you wish to use for this message. You may use either |
dst string Required | The phone number to which the message is to be delivered. The following characters are stripped off automatically as part of the sanitization process: Sanitized phone numbers must begin with the international country code (for example, 14152828726), and should be <= 14 characters in length. To send messages to multiple numbers, separate your destination phone numbers with the delimiter 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. |
text string Required - Conditional | The content of the text message. For SMS Messages containing only GSM 03.38 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. 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. Multiunit messages are automatically stitched back together and delivered as a single message in countries where mobile networks support long message concatenation. For WhatsApp messages 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. Use this parameter when you’re sending freeform (non-templated) text messages. These messages may be no longer than 4,096 characters. 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. |
type string | Allowed values: |
media_urls string Required — Conditional | For MMS messages 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 Up to 10 media files may be included in a single MMS message. Images of type You may include other media types (audio, video, vcards), but attachments of these types are not 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, but the ordering cannot be guaranteed. For WhatsApp messages 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 Meta documentation. |
template object Required — Conditional | JSON object to send templated WhatsApp messages when type is 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. You can create templates using WhatsApp Manager. Templates are uniquely identified by a combination of template name and language code. Components are used if dynamic variables are sent within a template. Here are the arguments sent in the Template object. |
interactive object optional | JSON object to send interactive WhatsApp messages when type is Interactive messages are non-templated messages and cannot be sent unless there is an active conversation. Interactive messages include list buttons, reply buttons, click-to-action url buttons Here are the arguments sent in the Interactive object. |
location object optional | JSON object to define location attributes when type is latitude - Location latitude in decimal degrees. Required.longitude - Location longitude in decimal degrees. Required.name - Location name. Optionaladdress - Location address. Optional |
message_expiry string | 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. Defaults to 10,800 seconds (3 hours). |
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. |
dlt_entity_id string Required — Conditional | The DLT entity ID that was generated during the DLT registration process. Used only by customers with India DLT registrations that have their Plivo accounts configured to support India DLT traffic. For more information see DLT Registration Process for Sending SMS to India. Your message will fail with Plivo error code 160 if you pass this parameter incorrectly. |
dlt_template_id string Required — Conditional | The DLT template ID that was generated during template creation in DLT portal. Used only by customers that have their Plivo accounts configured to support India DLT traffic. For more information see DLT Registration Process for Sending SMS to India. The template should be associated with the DLT header that’s passed as the Your message will fail with Plivo error code 160 if you pass this parameter incorrectly. |
dlt_template_category string Required — Conditional | The DLT template category from the DLT portal. Used only by customers that have their Plivo accounts configured to support India DLT traffic. Incorrect tagging of this parameter might result in message failures due to DND scrubbing. Allow values: |
method string | The HTTP method to be used when calling the URL defined above. Allow values: |
trackable boolean | Set this parameter to Defaults to |
log string | Possible values: Defaults to If set to If set to If set to If set to 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. |
Arguments sent in Template Object
name string Required | Name of the template |
language string Required | string indicating locale by combining language in ISO 639-1 format and region in ISO 3166-1 format. Ex: en_US, en, en_GB |
components object optional | If you have defined dynamic variables in your template, you need to set this object. Array of components objects containing the dynamic parameters of the message. This specifies where the dynamic variables appear in your template and the values against those variables. Review the Components object. Review the Components object. |
Arguments sent in Components Object
type string Required | Describes the component type. Supported values are
|
sub_type string Required — Conditional | Required when component type=button. This further defines the type of button. Not used for the other types. Supported values are : quick_reply : Refers to a quick reply button that allows for the customer to return a predefined message.url : Refers to a button that allows the customer to visit the URL generated by appending the text parameter to the predefined prefix URL in the template. |
index string Required — Conditional | Required when component type is |
parametersobject Required | Parameters object describes the parameters and the values that need to replace the dynamic variables defined in your template. Pass the parameters array in the same order in which you have defined this in your templates. Review the Parameters object. |
Arguments sent in Parameters Object
type string Required | Describes the parameter type. Supported values: text media (only supported when component type is header )payload (only supported when component type is button ) |
text string Required — Conditional | This parameter is required when parameter type is When component type is When component type is When component type is |
media string Required — Conditional |
This parameter can only be passed for component type is Supports images, documents and videos only.For valid file types and maximum file size accepted refer to Meta documentation |
payloadstring Required — Conditional |
This parameter is required when component type is This is the Developer-defined payload that is returned when the button is clicked in addition to the display text on the button. |
Arguments sent in Interactive Object
type string Required | Required for all interactive messages; this specifies the type of interactive message you want to send. Possible values: |
body object Required | Required for all interactive messages. This object specifies the body of the message and contains the following argument:
|
footer object optional | This object specifies the footer section of the message and contains the following argument:
|
header object optional | This object specifies the header section of the message and contains the following argument:
|
action object Required | This object specifies the nature of interactive messages and supports the following arguments:
id : Unique identifier for your button. This ID is returned in the callback response on your webhook when the reply button is clicked by the user. Maximum length: 256 characters. This is required for reply title : Title of your button. This can be up to 20 chars. This is required for all interactive message types.cta_url : Valid url. This is required for cta_url buttons.
rows (array of objects): Contains a list of rows. You can have a total of 10 rows across your sections. Each row must have:
description : This is an optional field. Maximum length: 72 characters.title : This is required if the message has more than one section. The title of the section can be a maximum of 24 characters. |
Returns
Returns a JSON response containing the API request ID and message UUID(s).