Se actualizó este documento.
La traducción en español no está disponible todavía.
Actualización del documento en inglés: 9 de mar.
Actualización del documento en español: 20 feb. 2020

Interactive Message Templates

Interactive message templates expand the content you can send recipients beyond the standard message template and media messages template types to include interactive buttons using the components object.

There are two types of predefined buttons offered:

  • Call-to-Action — Allows your customer to call a phone number and visit a website
  • Quick Reply — Allows your customer to return a simple text message

These buttons can be attached to text messages or media messages. Once your interactive message templates have been created and approved, you can use them in notification messages as well as customer service/care messages.

Request

POST /v1/messages
{
    "to": "recipient_wa_id",
    "ttl": "P4D" | "3600" | 3600, # The "ttl" field will be deprecated in v2.35.
    "type": "template",
    "template": {
        "namespace": "your-namespace",
        "language": {
            "policy": "deterministic",
            "code": "your-language-and-locale-code"
        },
        "name": "your-template-name",
        "components": [
            {
                "type" : "header",
                "parameters": [
                    {
                        "type": "text",
                        "text": "replacement_text"
                    }
                ]
            # end header
            },
            {
                "type" : "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "replacement_text"
                    },
                    {
                        "type": "currency",
                        "currency" : {
                            "fallback_value": "$100.99",
                            "code": "USD",
                            "amount_1000": 100990
                        }
                    },
                    {
                        "type": "date_time",
                        "date_time" : {
                            "fallback_value": "February 25, 1977",
                            "day_of_week": 5,
                            "day_of_month": 25,
                            "year": 1977,
                            "month": 2,
                            "hour": 15,
                            "minute": 33, #OR
                            "timestamp": 1485470276
                        }
                    },
                    {
                        ...
                        # Any additional template parameters
                    }
                ] 
            # end body
            },

            # The following part of this code example includes several possible button types, 
            # not all are required for an interactive message template API call.
            {
                "type": "button",
                "sub_type" : "quick_reply",
                "index": "0", 
                "parameters": [
                    {
                        "type": "payload",
                        # Business Developer-defined payload
                        "payload":"aGlzIHRoaXMgaXMgY29vZHNhc2phZHdpcXdlMGZoIGFTIEZISUQgV1FEV0RT"
                    }
                ]
            },
            {
                "type": "button",
                "sub_type" : "url",
                "index": "1", 
                "parameters": [
                    {
                        "type": "text",
                        # Business Developer-defined dynamic URL suffix
                        "text": "9rwnB8RbYmPF5t2Mn09x4h"
                    }
                ]
            },
            {
                "type": "button",
                "sub_type" : "url",
                "index": "2",
                "parameters": [
                    {                    
                        "type": "text",
                        # Business Developer-defined dynamic URL suffix
                        "text": "ticket.pdf"
                    }
                ]
            }
        ]
    }
}

Parameters

Nombre Descripción

type

Obligatorio para las plantillas de mensaje.

El tipo de mensaje que se envía.
Opciones:

  • text: valor predeterminado
  • image
  • audio
  • document
  • template: se usa para enviar un mensaje de plantilla con contenido multimedia
  • hsm

to

Obligatorio.

El identificador de WhatsApp a quien se envía el mensaje.

ttl
Quedará obsoleto en la v2.35

Opcional.

A partir de la v2.21.3: Duración del tiempo de vida (TTL).
Valor predeterminado: 7 días
Otras opciones: Las duraciones mínima y máxima compatibles oscilan entre 1 y 30 días (ambos valores incluidos).


Acepta una cadena con el formato de duración ISO-8601 o simplemente en segundos. Las duraciones deben especificarse con un múltiplo exacto de días. Cualquier otro valor intermedio se redondeará automáticamente al día más próximo. Consulta la sesión del objeto ttl para obtener más información.

recipient_type

Opcional.

Valor:individual

template

Obligatorio para los mensajes template.

Contiene toda la información de la plantilla.

hsm

Obligatorio para las plantillas de mensaje.

El elemento de contención del contenido del mensaje. Indica que el mensaje está altamente estructurado. Los parámetros que contiene proporcionan la estructura.

The template object

NombreDescripción

namespace

Obligatorio.

Espacio de nombres de la plantilla.


A partir de la versión v2.27.8, este debe ser el espacio de nombres asociado a la cuenta de WhatsApp Business que posee el número de teléfono correspondiente al cliente de la API de WhatsApp Business actual, o el mensaje no se enviará.

name

Obligatorio.

Nombre de la plantilla.

language

Obligatorio.

Especifica el lenguaje en que se puede representar la plantilla. Solo funciona la política de lenguaje deterministic con los mensajes de plantilla multimedia. Consulta la sección Idioma para obtener más información.

components

Opcional.

Matriz que incluye los parámetros del mensaje.

The components object

NombreDescripción

type

Obligatorio.

Describe el tipo component
Valores:header, body, footer

parameters

Opcional.

Matriz que incluye el contenido del mensaje.

The parameters object

NombreDescripción

type

Obligatorio.

Describe el tipo parameter.
Valores:text, currency, date_time, image, document, video


Los tipos de contenido multimedia (image, document y video) siguen el mismo formato que los que se usan en mensajes multimedia estándar; consulta la documentación sobre contenido multimedia para obtener más información. Actualmente, las plantillas de mensajes multimedia solo admiten documentos PDF.


Para obtener más información sobre currency y date_time, consulta la sección sobre parámetros localizables. Los parámetros currency y date_time para mensajes de template usan fallback_value en lugar de default. Consulta el ejemplo anterior de solicitud para ver un modelo.

The button type

NameDescription

sub_type

Required.

Type of button being created.
Values: quick_reply, url

index

Required.

Position index of the button. You can have up to 3 buttons using index values of 0-2.

parameters

Required.

The parameters for the button, which are set at creation time in your Business Manager.

The sub_type parameter

NameDescription

quick_reply

Optional.

Refers to a previously created quick reply button that allows for the customer to return a predefinied message. See Callback from a Quick Reply Button Click below for an example of a response from a quick reply button.

url

Optional.

Refers to a previously created button that allows the customer to visit the URL generated by appending the text parameter to the pre-defined prefix URL in the template.

The parameters object

NameDescription

type

Required.

Indicates the type of parameter for the button.
Values: payload, text

payload

Required for quick_reply buttons.

Developer-defined payload that will be returned when the button is clicked in addition to the display text on the button. See Callback from a Quick Reply Button Click below for an example of a response from a quick reply button.

text

Required for url buttons.

Developer provided suffix that will be appended to a previously created dynamic URL button.

Response

A successful response includes a messages object with an id.

{
  "messages": [{
    "id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
  }]
}

An unsuccessful response will contain an error object that will contain an error string, error code and other information.

If a template is sent to an account that is incapable of receiving the template, the 1026 (ReceiverIncapable) error will be sent in the error object to the configured Webhook server.

See Error and Status Codes for more information on errors.

Callback from a Quick Reply Button Click

Se envía una respuesta cuando un cliente hace clic en el botón de respuesta rápida. A continuación, se incluye un ejemplo del formato de devolución de llamada. Nota: Los clientes no pueden hacer clic en un botón, responder al mensaje interactivo, ni enviarte un mensaje. Asegúrate de que este tipo de situaciones también se encuentren admitidas. Consulta la documentación de Webhooks para obtener más información.
{
    "contacts": [
        {
            "profile": {
                "name": "Kerry Fisher"
            },
            "wa_id": "16505551234"
        }
    ],
    "messages": [
        {
            "button": {
                "payload": "No-Button-Payload",
                "text": "No"
            },
            "context": {
                "from": "16315558007",
                "id": "gBGGFmkiWVVPAgkgQkwi7IORac0"
            },
            "from": "16505551234",
            "id": "ABGGFmkiWVVPAgo-sKD87hgxPHdF",
            "timestamp": "1591210827",
            "type": "button"
        }
    ]
    # If there are any errors, an errors field (array) will be present        
    "errors": [ { ... } ]
}