Enviar mensajes

Envía plantillas, textos y archivos por WhatsApp desde tu sistema, uno por destinatario.

Todos los envíos usan POST https://api.whapi.chat/waba-api/messages/send. Cada request envía un WhatsApp a una persona: para un envío masivo, haz un request por destinatario.

¿Plantilla o texto libre?

WhatsApp solo permite mensajes libres dentro de las 24 horas siguientes al último mensaje del cliente. Fuera de esa ventana, solo puedes enviar plantillas aprobadas.

Si envías texto fuera de la ventana, la respuesta es 403 con code: waba_session_window_expired. En ese caso, usa una plantilla.

Enviar una plantilla

Indica el nombre, el idioma y el valor de cada variable. Con variables por nombre, cada parámetro lleva parameter_name:

curl https://api.whapi.chat/waba-api/messages/send \
  --header 'Authorization: Bearer TU_CLAVE' \
  --header 'Content-Type: application/json' \
  --data '{
    "wabaPhoneNumberId": 3,
    "number": "51987654321",
    "template": {
      "name": "acceso_postulante",
      "language": "es",
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "parameter_name": "correo_postulante", "text": "[email protected]" },
            { "type": "text", "parameter_name": "contrasena_postulante", "text": "Temp1234" }
          ]
        }
      ]
    }
  }'

Con variables por posición ({{1}}, {{2}}), omite parameter_name y envía los parámetros en orden.

number es el teléfono del destinatario con código de país y solo dígitos. wabaPhoneNumberId solo es obligatorio si tienes más de una línea.

Plantillas con imagen, video o PDF en el encabezado

Si la plantilla lleva un archivo en el encabezado, tienes tres opciones:

1. Adjuntarlo: envía el request como multipart/form-data, con el archivo en medias y template como texto JSON.
2. Pasar un enlace en template.components:

   {
     "type": "header",
     "parameters": [
       { "type": "document", "document": { "link": "https://tu-sitio.com/cotizacion.pdf" } }
     ]
   }

3. Usar el archivo predeterminado que se guardó al crear la plantilla, con "useDefaultHeaderMedia": true.

Si no envías ninguno, la respuesta es 400 con code: waba_template_header_media_missing. El campo hasDefault indica si la plantilla tiene un archivo predeterminado que podrías usar.

Enviar texto

curl https://api.whapi.chat/waba-api/messages/send \
  --header 'Authorization: Bearer TU_CLAVE' \
  --header 'Content-Type: application/json' \
  --data '{
    "number": "51987654321",
    "body": "Gracias por escribirnos, ¿en qué te ayudamos?"
  }'

Enviar un archivo

curl https://api.whapi.chat/waba-api/messages/send \
  --header 'Authorization: Bearer TU_CLAVE' \
  --form number=51987654321 \
  --form 'body=Te envío la cotización' \
  --form [email protected]

Se envía un archivo por request.

La respuesta

{
  "wamid": "wamid.HBgMNTE5ODc2NTQzMjEVAgASGBQzQUYxRjQ",
  "ticketId": 42,
  "contactId": 18,
  "leadId": 9,
  "wabaPhoneNumberId": 3,
  "mode": "template",
  "headerMediaSource": null
}

• Un 200 significa que Meta aceptó el mensaje, no que llegó. La entrega se confirma después por el webhook waba.message.status (ver Recibir mensajes y estados).
• Guarda el wamid: es el id con el que llegan esos estados.
• El mensaje queda en Whapi como si lo hubiera enviado un agente. Si el número no existía, se crean el contacto, el ticket y el lead.

Errores frecuentes

Todos los campos y errores: referencia de envío.