Enviar mensajes

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

Tipos de mensajes

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

Los mensajes de dirección te permiten solicitar fácilmente una dirección de entrega a los usuarios de WhatsApp.
Los mensajes de audio muestran un icono de audio y un enlace a un 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 contacto te permiten enviar información de contacto detallada directamente a los usuarios de WhatsApp, como nombres, números de teléfono, direcciones físicas y direcciones de correo electrónico.
Los mensajes de documento muestran un icono de documento vinculado a un documento que el usuario de WhatsApp puede descargar con un toque.
Los mensajes de imagen muestran una única imagen y una descripción opcional.
Los mensajes interactivos con botones de URL de llamada a la acción te permiten asignar una URL a un botón para no tener que incluir URL sin formato extensas o poco claras en el cuerpo del mensaje.
Los mensajes interactivos de Flows te permiten enviar mensajes estructurados que resultan más naturales o cómodos para los clientes. Por ejemplo, puedes usar WhatsApp Flows para reservar citas, explorar productos, obtener comentarios de los clientes y conseguir nuevos clientes potenciales de ventas, entre otras cosas.
Los mensajes interactivos de lista te permiten presentar a los usuarios de WhatsApp una lista de opciones entre las que elegir.
Los mensajes interactivos de solicitud de ubicación muestran un cuerpo de texto y un botón de envío de la ubicación. Cuando un usuario de WhatsApp toca el botón, aparece una pantalla que le permite compartir su ubicación.
Los mensajes interactivos de botones de respuesta te permiten enviar hasta tres respuestas predefinidas entre las que los usuarios pueden elegir.
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 sticker muestran stickers con animaciones o imágenes estáticas en mensajes de WhatsApp.
Los mensajes de texto son mensajes que solo contienen un cuerpo de mensaje y una vista previa del enlace opcional.
Los mensajes de plantilla te permiten enviar plantillas de marketing, utilidad y autenticación a los usuarios de WhatsApp. A diferencia de lo que ocurre con los demás tipos de mensajes, para enviar los de plantilla no es necesario abrir un periodo de atención al cliente de 24 horas entre tú y el destinatario del mensaje.
Los mensajes de vídeo muestran una vista previa del vídeo mediante una miniatura de una imagen del vídeo y una descripción opcional. Cuando el usuario de WhatsApp toca la vista previa, el vídeo se carga y se reproduce.
Los mensajes de reacción son reacciones mediante emoticonos que puedes aplicar a los mensajes recibidos de usuarios de WhatsApp.

Periodos de atención al cliente

Cuando un usuario de WhatsApp te envía un mensaje, se inicia (o actualiza) un temporizador de 24 horas denominado “periodo de atención al cliente”.

Todos los tipos de mensajes, excepto los mensajes de plantilla, se pueden enviar a un usuario cuando hay abierto un periodo de atención al cliente entre tú y él.

Los mensajes de plantilla se pueden enviar a un usuario en cualquier momento, siempre y cuando haya aceptado recibir mensajes tuyos.

Solicitudes

Todas las solicitudes de mensaje usan el extremo POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID/messages:

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

El cuerpo de la solicitud POST varía en función del tipo de mensaje que quieras enviar, pero la carga útil usa 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 va a enviar y se debe incluir una propiedad que coincida con dicho tipo y que describa el contenido del mensaje.

Por ejemplo, a continuación se incluye una solicitud para enviar un mensaje de texto a un usuario de WhatsApp. Ten en cuenta que el valor de type se establece en text, seguido de 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/"
  }
}'

A continuación, se muestra el aspecto que tendrá el mensaje en el cliente de WhatsApp si el mensaje de texto se entregó correctamente al usuario de WhatsApp:

Respuestas

La API enviará la siguiente respuesta si acepta correctamente tu solicitud de mensaje sin detectar errores en la propia 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ó correctamente la solicitud, no indica que el mensaje se haya entregado correctamente. El estado de entrega de los mensajes se comunica mediante el webhooks de mensajes.

La propiedad message_status solo se incluye al enviar mensajes de plantilla que usan una plantilla cuya frecuencia se está regulando.

Webhooks

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

Mensajes de comercio

Los mensajes de comercio son mensajes interactivos que se usan 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á encima del nuevo mensaje, citado en una burbuja contextual.

Limitaciones

La burbuja contextual no aparecerá encima del mensaje entregado que se envía como respuesta en los siguientes casos:

• El mensaje anterior se ha eliminado o movido a un almacenamiento a largo plazo (los mensajes se suelen mover al almacenamiento a largo plazo una vez transcurridos 30 días, a menos que hayas activado el almacenamiento local).
• Respondes con un mensaje de audio, imagen o vídeo y el usuario de WhatsApp ejecuta KaiOS.
• Utilizas el cliente de WhatsApp para responder con un mensaje de pulsar para hablar y el usuario de WhatsApp ejecuta KaiOS.
• 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 solicitud POST

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!"
  }
}'

Activos multimedia

Debes subir los activos multimedia enviados en los mensajes al número de teléfono de empresa que enviará el mensaje o alojar los activos en un servidor público e incluir la URL en la solicitud de envío de mensaje.

Para reducir la probabilidad de errores y evitar solicitudes innecesarias al servidor público, te recomendamos que subas los activos multimedia y utilices los identificadores correspondientes al enviar mensajes.

Almacenamiento en caché HTTP de contenido multimedia

La API de nube de WhatsApp admite el almacenamiento en caché HTTP de contenido multimedia. Si utilizas un enlace (link) a un activo de contenido multimedia de tu servidor (en lugar del identificador, id, de un activo que hayas subido a nuestros servidores), puedes indicarnos que almacenemos en caché el activo para volver a utilizarlo con mensajes futuros; para ello, incluye los encabezados siguientes en la respuesta del servidor cuando solicitemos el activo. 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 gestionar el almacenamiento en caché del activo. Admitimos las siguientes directivas:

• max-age=n: indica cuántos segundos (n) se debe almacenar en caché el activo. Volveremos a utilizar el activo almacenado en caché en las llamadas posteriores hasta que se supere este tiempo; después, solicitaremos de nuevo el activo si es necesario. Ejemplo: Cache-Control: max-age=604800.
• no-cache: indica que el activo se puede almacenar en caché, pero se debe actualizar 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 debe almacenar en caché. Ejemplo: Cache-Control: no-store.
• private: indica que el activo se ha personalizado para el destinatario y no se debe 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 Cache-Control: no-cache se incluye en la respuesta, actualizaremos nuestra versión del activo almacenada en caché 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 una versión concreta 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 tu propia lógica interna (que no revelaremos).

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 varios mensajes

Al enviar varios mensajes, no se garantiza que el orden de entrega coincida con el orden de las solicitudes a la API. Si necesitas asegurarte de que los mensajes se entregan en una secuencia determinada, confirma la recepción del estado delivered en un webhook de mensajes antes de enviar el siguiente mensaje de la secuencia.

Duración

Si no podemos entregar un mensaje a un usuario de WhatsApp, seguiremos intentando entregar el mensaje durante un periodo de tiempo que se conoce como duración (TTL) o periodo de validez del mensaje. Si no podemos entregar un mensaje durante un periodo de tiempo que supere el valor de TTL, dejaremos de intentarlo y eliminaremos el mensaje.

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

Para personalizar estos valores predeterminados, establece un valor de TTL personalizado en las plantillas de autenticación y las plantillas de utilidad. Consulta Personalizar la duración.

Si envías un mensaje, pero no recibes el webhook de mensajes correspondiente que indica que el mensaje se entregó antes de que se superase el valor de TTL, debes asumir que el mensaje se ha eliminado.

Ten en cuenta que, si se produce un error en un mensaje por algún motivo no relacionado y activa un webhook de mensajes de error de entrega, podría producirse un breve retraso antes de recibir el webhook, por lo que es posible que quieras crear en un pequeño búfer antes de asumir una eliminación.

Solución de problemas

Si tienes problemas con la entrega de mensajes, consulta Mensaje no entregado.