Enviar mensaje en WhatsApp, con una API

Envía un mensaje desde un número de teléfono comercial y devuelve su id en messages[0].id. Los tipos libres (text, image, video, document, audio) solo llegan a quien escribió al número en las últimas 24 horas; para iniciar una conversación, envía el tipo template con una plantilla aprobada de Listar plantillas de mensaje. Meta cobra los mensajes a la cuenta según sus precios de WhatsApp.

Identificador
whatsapp_send_message

La llamada

POST https://connect.reportei.com/api/tools/whatsapp_send_message/execute
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Content-Type: application/json
Accept: application/json

{
  "customer_toolkit": "<connection UUID>",
  "arguments": {
    "phone_number_id": "<phone_number_id>",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "<recipient_number_with_country_code>",
    "type": "text",
    "text": {
      "body": "Hello! This is an example message.",
      "preview_url": false
    }
  }
}

Tu sistema envía el id de la conexión de tu cliente y los argumentos de la tool. Los headers son los mismos de toda la API de Connect: el token de tu producto y el token de tu cliente.

Ejemplo ilustrativo. Sustituye los tokens, el UUID de la conexión y los datos de destino por los tuyos. Esta página no ejecuta la petición.

Antes de ejecutar

  • Para type=text, incluye text.body. El número de destino debe contener el código de país y solo dígitos. Usa el phone_number_id de la cuenta comercial conectada.
  • El texto libre se usa dentro de las 24 horas posteriores al mensaje del usuario. Fuera de esa ventana, inicia la conversación con type=template y una plantilla aprobada, language y sus parámetros requeridos.
  • El ID devuelto identifica un mensaje aceptado por la API, pero no confirma su entrega. Consulta api_error.body en los errores HTTP del proveedor.

Parámetros

Las descripciones de los parámetros siguen la documentación oficial de la app, en inglés.

ParámetroTipoObligatorioDescripción
phone_number_idstringSíId of the business phone number that sends, from List phone numbers.
messaging_productstringSíAlways whatsapp.Valores: whatsapp
recipient_typestringSíindividual for a person, group for a WhatsApp group of the number.Valores: individual, group
tostringSíPhone number of the person with country code, digits only, for example 5511987654321, or the id of the group.
typestringSíKind of message. Send the object with the same name, such as text or template.Valores: text, template, image, video, document, audio
textobjectSí, si type=textFor type text.
templateobjectSí, si type=templateFor type template.
imageobjectSí, si type=imageFor type image: a JPEG or PNG at a public URL.
videoobjectSí, si type=videoFor type video: an MP4 or 3GP at a public URL.
documentobjectSí, si type=documentFor type document: a file at a public URL, such as a PDF.
audioobjectSí, si type=audioFor type audio: an audio file at a public URL.

Conexiones posibles

Tu cliente conecta su cuenta de WhatsApp una sola vez, con uno de los modos de abajo. La misma conexión sirve para todas las tools del toolkit.

Clave de API

Tu cliente pega la clave de la app en una pantalla de Connect, o tu sistema envía la clave con POST /api/customer-toolkits, sin pantalla.

La respuesta

Si la llamada tiene éxito, Connect conserva el status y el cuerpo de la respuesta de la app. Los errores HTTP devueltos por la app usan el objeto {error, api_error}; la autenticación o validación pueden fallar antes de la ejecución. El header X-Toolkit-Execution-Id identifica la ejecución registrada, disponible en GET /api/tools/executions/{uuid}.

Formato ilustrativo de éxito

{
  "messaging_product": "whatsapp",
  "messages": [
    {
      "id": "wamid.EXAMPLE"
    }
  ]
}

El contenido es un ejemplo, no una ejecución registrada. Guarda X-Toolkit-Execution-Id cuando se devuelva para consultar la ejecución. Connect no aplica reintentos ni idempotencia: repetir un POST puede repetir el envío.

Lista para agentes de IA

El input de esta tool es un JSON Schema, disponible en GET /api/tools/whatsapp_send_message. Se convierte en la definición de tool de tu agente sin conversión.

Otras tools de WhatsApp

Ver las 10 tools

Toolkits de la misma categoría

Ver los 100 toolkits

Mira Connect aplicado a tu producto.

Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.