Envío de mensajes

En este documento, se explica cómo usar la API para enviar mensajes a usuarios de WhatsApp.

Tipos de mensajes

Puedes usar la API para enviar los tipos de mensajes que se describen a continuación. Todos estos tipos, excepto los mensajes de reacciones, se pueden enviar a un mensaje anterior como respuesta.

Los mensajes de dirección te permiten solicitar fácilmente una dirección de entrega de usuarios de WhatsApp.
Los mensajes de audio muestran un icono de audio y un enlace al archivo de audio. Cuando el usuario de WhatsApp toca el icono, el cliente de WhatsApp carga y reproduce el archivo de audio.
Los mensajes de contactos te permiten enviar a usuarios de WhatsApp, de forma directa, información de contacto completa, como nombres, números de teléfono, direcciones físicas y direcciones de correo electrónico.
En los mensajes de documentos, se muestra un icono de un documento que está vinculado a un documento y que un usuario de WhatsApp puede tocar para descargar.
En los mensajes de imágenes, se muestra una sola imagen y una descripción opcional.
Los mensajes con botones de URL de llamada a la acción interactivos te permiten asignar cualquier URL a un botón, de modo que no tengas que incluir URL largas o confusas y sin procesar en el cuerpo del mensaje.
Los mensajes de flujo interactivo te permiten enviar mensajes estructurados que son más naturales o cómodos para tus clientes. Por ejemplo, puedes usar WhatsApp Flows para reservar citas, explorar productos, recoger comentarios de los clientes, captar nuevos clientes potenciales para ventas o cualquier otro fin.
Los mensajes de lista interactivos te permiten proporcionar a los usuarios de WhatsApp una lista de opciones entre las que pueden hacer una selección.
Los mensajes de solicitud de ubicación interactivos contienen el texto del cuerpo y un botón para enviar la ubicación. Cuando un usuario de WhatsApp toca el botón, se muestra una pantalla que indica la ubicación que el usuario puede usar para compartir la ubicación.
Los mensajes interactivos con botones de respuesta te permiten enviar hasta tres respuestas predefinidas que deben seleccionar los usuarios.
Los mensajes de ubicación te permiten enviar las coordenadas de latitud y longitud de una ubicación a un usuario de WhatsApp.
Los mensajes de stickers muestran imágenes de sticker animadas o estáticas en un mensaje de WhatsApp.
Los mensajes de texto son mensajes que solo contienen un cuerpo de texto y una vista previa del enlace opcional.
Los mensajes de plantilla te permiten enviar plantillas de marketing, utilidades y autenticación a usuarios de WhatsApp. A diferencia de todos los demás tipos de mensajes, en el caso de los mensajes de plantilla, no es necesario un período de servicio al cliente de 24 horas entre tú y el destinatario para el envío.
Los mensajes de video muestran una vista previa en miniatura de una imagen del video con un título opcional. Cuando el usuario de WhatsApp toca la vista previa, se activa la carga del video y se lo muestra al usuario.
En el caso de los mensajes de reacciones, se trata de reacciones con emojis que puedes aplicar al mensaje anterior de un usuario de WhatsApp que hayas recibido.

Intervalos del servicio de atención al cliente

Cuando un usuario de WhatsApp te envía mensajes, se inicia un temporizador de 24 horas denominado "intervalo de servicio de atención al cliente".

Todos los tipos de mensajes, excepto los mensajes de plantillas, solo se pueden enviar a un usuario cuando hay un intervalo de servicio de atención al cliente abierto entre tú y el usuario.

Los mensajes de plantilla se pueden enviar a un usuario en cualquier momento, siempre que el usuario haya aceptado recibir tus mensajes.

Solicitudes

Todas las solicitudes de envío de mensajes usan el punto de conexión POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID/messages:

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

El cuerpo de la solicitud POST varía según el tipo de mensaje que deseas enviar, pero la carga útil utiliza la siguiente sintaxis común:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "type": "<MESSAGE_TYPE>",
  "<MESSAGE_TYPE>": {<MESSAGE_CONTENTS>}
}

El valor de la propiedad type de la carga útil del cuerpo de la solicitud POST indica el tipo de mensaje que se enviará, y se debe incluir una propiedad que coincida con ese tipo y que describa el contenido del mensaje.

Por ejemplo, la siguiente es una solicitud para enviar un mensaje de texto a un usuario de WhatsApp. Observa que type se configuró en text y le sigue un objeto text, que describe el contenido del mensaje:

curl 'https://graph.facebook.com/v20.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "As requested, here'\''s the link to our latest product: https://www.meta.com/quest/quest-3/"
  }
}'

Así se vería el mensaje en el cliente de WhatsApp si el mensaje de texto se entregara correctamente a usuario de WhatsApp:

Respuestas

La API enviará la siguiente respuesta si acepta correctamente tu solicitud de envío de mensaje y no encuentra errores en dicha solicitud:

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "<WHATSAPP_USER_PHONE_NUMBER>",
      "wa_id": "<WHATSAPP_USER_ID>"
    }
  ],
  "messages": [
    {
      "id": "<WHATSAPP_MESSAGE_ID>"
      "message_status": "<PACING_STATUS>"
    }
  ]
}

Ten en cuenta que esta respuesta solo indica que la API aceptó tu solicitud correctamente, no que tu mensaje se entregó correctamente. El estado de entrega de los mensajes se comunica a través de webhooks de mensajes.

La propiedad message_status solo se incluye cuando se envían mensajes de plantilla que utilizan una plantilla que se va a pausar.

Webhooks

Los mensajes enviados a usuarios de WhatsApp activan webhooks de mensajes, por lo que debes asegurarte de suscribirte a este tema para recibir notificaciones de estado de mensajes.

Mensajes comerciales

Los mensajes comerciales son mensajes interactivos que se usan junto con un catálogo de productos. Consulta Compartir productos con los clientes para ver cómo usar estos tipos de mensajes.

Respuestas

Puedes enviar cualquier tipo de mensaje como respuesta a un mensaje anterior. El mensaje anterior aparecerá en la parte superior del nuevo mensaje, citado dentro de una burbuja de contexto.

Limitaciones

La burbuja de contexto no aparecerá en la parte superior del mensaje enviado como respuesta en los siguientes casos:

• Si el mensaje anterior se eliminó o se guardó en el almacenamiento a largo plazo (por lo general, los mensajes se guardan en el almacenamiento a largo plazo después de 30 días, a menos que hayas activado el almacenamiento local).
• Si respondes con un mensaje de audio, imagen o video y el usuario de WhatsApp utiliza KaiOS.
• Si usas el cliente de WhatsApp para responder con un mensaje de tipo presionar para hablar y el usuario de WhatsApp utiliza KaiOS.
• Si respondes con un mensaje de plantilla.

Sintaxis de la solicitud

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

Cuerpo de la solicitud POST

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "context": {
    "message_id": "WAMID_TO_REPLY_TO"
  },

  /* Message type and type contents goes here */

}

Parámetros del cuerpo de la publicación

Ejemplo de solicitud

Ejemplo de un mensaje de texto enviado como respuesta a un mensaje anterior.

curl 'https://graph.facebook.com/v19.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "context": {
    "message_id": "wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQTdCNTg5RjY1MEMyRjlGMjRGNgA="
  },
  "type": "text",
  "text": {
    "body": "You'\''re welcome, Pablo!"
  }
}'

Recursos multimedia

Los recursos multimedia enviados en mensajes deben cargarse al número de teléfono del negocio que enviará el mensaje, o bien debes alojar el recurso de un servidor público e incluir su URL en la solicitud de envío de mensajes.

Para reducir la probabilidad de errores y evitar solicitudes innecesarias a tu servidor público, te recomendamos que subas tus recursos multimedia y uses sus identificadores al enviar mensajes.

Almacenamiento de contenido multimedia en caché HTTP

La API de la nube de WhatsApp admite el almacenamiento de archivos multimedia en caché HTTP. Si usas un enlace (link) que te dirige a un recurso multimedia de tu servidor (a diferencia de un identificador [id] de un recurso que subiste a nuestros servidores), puedes solicitarnos almacenar en caché el recurso para reutilizarlo en el futuro en otros mensajes. Para ello, incluye los encabezados que se muestran a continuación en la respuesta al servidor cuando solicitemos el recurso. Si no se incluye ninguno de estos encabezados, no almacenaremos en caché el activo.

Cache-Control: <CACHE_CONTROL>
Last-Modified: <LAST_MODIFIED>
ETag: <ETAG>

Cache-Control

El encabezado Cache-Control nos indica cómo controlar el almacenamiento en caché de los activos. Admitimos las siguientes directivas:

• max-age=n: indica cuántos segundos del activo (n) se deben almacenar en caché. Reutilizaremos el activo almacenado en caché en los siguientes mensajes hasta que se supere el tiempo. Con posterioridad, volveremos a solicitarlo, si es necesario. Ejemplo: Cache-Control: max-age=604800.
• no-cache: indica que el activo se puede almacenar en caché, pero que deberá actualizarse si el valor del encabezado Last-Modified es diferente al de una respuesta anterior. Requiere el encabezado Last-Modified. Ejemplo: Cache-Control: no-cache.
• no-store: indica que el activo no se deberá almacenar en caché. Ejemplo: Cache-Control: no-store.
• private: indica que el activo está personalizado para el destinatario y que no se debería almacenar en caché.

Last-Modified

Indica cuándo se modificó el activo por última vez. Se usa con Cache-Control: no-cache. Si el valor de Last-Modified es diferente al de una respuesta anterior y se incluye Cache-Control: no-cache en la respuesta, actualizaremos nuestra versión almacenada en caché del activo con el activo de la respuesta. Ejemplo: Date: Tue, 22 Feb 2022 22:22:22 GMT.

ETag

El encabezado ETag es una cadena única que identifica la versión específica de un activo. Ejemplo: ETag: "33a64df5". Este encabezado se ignora, a menos que los encabezados Cache-Control y Last-Modified no se incluyan en la respuesta. En este caso, almacenaremos en caché el activo según nuestra lógica interna (que no divulgamos).

Ejemplo de respuesta con encabezados

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 1024
Date: Tue, 22 Feb 2022 22:22:22 GMT
ETag: "33a64df5"
Cache-Control: max-age=604800

<IMAGE_PAYLOAD>

Secuencia de entrega de mensajes múltiples

Cuando envías una serie de mensajes, no se garantiza que el orden en que se entregan los mensajes coincida con el orden de tus solicitudes de la API. Si debes asegurarte de que los mensajes se entreguen en una secuencia determinada, cuando envíes uno, confirma la recepción del estado delivered en un webhook de mensajes antes de enviar el siguiente mensaje de la secuencia.

Tiempo de duración

Si no podemos entregar un mensaje a un usuario de WhatsApp, seguiremos tratando de entregarlo durante un período de tiempo conocido como "período de validez" (TTL), o período de validez del mensaje. Si no podemos entregar un mensaje durante un tiempo que supera al TTL, dejaremos de intentarlo y omitiremos el mensaje.

• El TTL de todos los mensajes, excepto los mensajes de plantilla que incluyen una plantilla de autenticación, es de 30 días.
• Los mensajes de plantilla que utilizan una plantilla de autenticación tienen un TTL predeterminado de 10 minutos.

Puedes personalizar estos valores predeterminados configurando un TTL en las plantillas de autenticación y de utilidad. Consulta Personalizar el período de validez.

Si envías un mensaje, pero no recibes el webhook de mensajes correspondiente, que indica que el mensaje se entregó antes de que se superara el TTL, asumiremos que el mensaje se omitió.

Ten en cuenta que si falla el envío de un mensaje por un motivo no relacionado y se activa un webhook de falla de envío de mensajes, es posible que haya una breve demora antes de que recibas el webhook, por lo que te conviene incorporar un breve período de espera antes de asumir que se omitió el mensaje.

Solución de problemas

Si tienes problemas con la entrega de mensajes, consulta No se entregó el mensaje.