Mensajes

/v1/messages

Usa el nodo messages para enviar mensajes de texto, objetos multimedia/documentos, plantillas de mensaje y mensajes grupales a tus clientes.

Este documento abarca lo siguiente:

Requisitos previos

  • Para usar la API de WhatsApp Business, antes debes autenticarte y recibir un token que te permite acceder al servicio. Consulta la Documentación sobre inicio de sesión y autenticación para obtener más información acerca del proceso.
  • Antes de que tu empresa pueda enviar un mensaje a un número, deberá verificar que el número de teléfono pertenezca a una cuenta de WhatsApp y obtener el identificador de usuario de WhatsApp. Consulta la documentación sobre contactos para obtener más información acerca del proceso.
  • El mensaje debe cumplir con los requisitos de servicio del control de corte.

Solicitud

Las llamadas a la API de mensajes se envían al extremo /messages independientemente del tipo de mensaje, pero el contenido del cuerpo del mensaje JSON difiere para cada tipo de mensaje (texto, imagen, etc.). Consulta la siguiente documentación para obtener información sobre los tipos de mensajes que quieres enviar:

POST /v1/messages
{
  "recipient_type": "individual" | "group",
  "to": "whatsapp-id" | "whatsapp-group-id",
  "type": "audio" | "contact" | "document" | "hsm" | "image" | "location" | "text" | "video",
  
  "audio": {
      "id": "your-media-id",
  }
  
  "document": {
      "id": "your-media-id",
      "caption": "your-document-caption-to-be-sent",
      "filename": "your-document-filename"
  }
  
  "document": {
      "link": "http(s)://the-url"
      "provider": {
          "name" : "provider-name"
      }
      "caption": "your-document-caption"
    }
  
  "video": {
      "link": "http(s)://the-url"
      "provider": {
          "name" : "provider-name"
      }
      "caption": "your-video-caption"
    }
  }

  "text": {
      "body": "your-message-content"
  }
}

En el ejemplo anterior, se muestran distintos objetos, como audio, documento y texto, solo con fines ilustrativos. Un cuerpo de solicitud válido contiene solo uno de esos objetos.

Respuesta

La respuesta incluye una combinación de los siguientes componentes: meta, messages (carga) y errors. Consulta la documentación sobre respuestas de la API para obtener más información.

El siguiente es un ejemplo de payload en una respuesta: los objetos "meta" y "error" se omiten por motivos de brevedad.

{
  "messages": [{ 
    "id": "message-id" 
  }]    
}

Si la solicitud se realiza correctamente, recibirás una respuesta con un identificador de mensaje. Si la solicitud devuelve una sección errors, verifica el mensaje que la originó y corrige los errores antes de volver a enviarla.

Para obtener más información sobre errores, consulta:

Ejemplo

Cuando se envía un mensaje en una solicitud, el cliente recibe un mensaje como el siguiente:

Mensajes recibidos

Esta imagen muestra mensajes de los siguientes tipos, en orden descendente:

  1. Mensaje de texto
  2. Mensaje de texto con una URL
  3. Plantilla de mensaje
  4. Mensaje multimedia

Control de corte

El control de corte previene que los mensajes se entreguen a los usuarios sobre la base de algunas condiciones. El siguiente es un resumen de los requisitos:

  • Los mensajes de texto o mensajes multimedia regulares (es decir, cualquier mensaje que no sea un mensaje de plantilla) solo pueden enviarse durante las 24 horas posteriores a la última vez en que un cliente envió un mensaje a tu empresa.
  • Los mensajes de plantilla no tienen esa restricción, por lo que deberían ser el medio predeterminado para contactar a un cliente.
  • La cuenta de la empresa debe cumplir con los requisitos para recibir pagos.

Si un mensaje no cumple con alguno de estos requisitos, se envía un código de error. Puedes obtener más información sobre los códigos de error aquí.