Enviar mensajes

Vas a mandar un mensaje a un contacto desde uno de tus números, guardar su id y enterarte de qué pasó con él. El envío pide el permiso conversations:send y pasa por las reglas de WhatsApp: la ventana de 24 horas en los números de WhatsApp Cloud, los frenos contra spam y el ritmo por número.

Lo que necesitásCopiar el enlace a esta sección

• Una clave con conversations:send para mandar y conversations:read para consultar el mensaje después. Si además querés el aviso message.status_changed, webhooks:write para suscribirte.
• El id del contacto (Listar contactos) y el device_id del número por el que sale (Listar números). Si respondés a un mensaje que te llegó, message.received ya trae los dos.

Qué operaciones de envío existenCopiar el enlace a esta sección

• Enviar un mensaje a un contacto: texto, un archivo por URL, botones o lista, desde uno de tus números.
• Enviar un mensaje: lo mismo, con el contacto y el número en el cuerpo.
• Enviar una plantilla: una plantilla aprobada por Meta, con sus variables.
• Enviar un formulario: un formulario de WhatsApp ya publicado, por un número de WhatsApp Cloud.
• Enviar una tarjeta de contacto
• Reenviar un mensaje
• Reaccionar a un mensaje y quitar una reacción

Qué puede mandar cada número lo dice su ficha, en capabilities.messages: ver Mensajes.

curl -X POST "https://api.funnelchat.com/api/v1/contacts/2001/message" \
  -H "Authorization: Bearer <id>|fc_live_..." \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": 3,
    "contact_id": 2001,
    "text": "¡Hola! Tu pedido ya salió.",
    "client_reference": "pedido-1001"
  }'

{
  "message": {
    "id": 1001,
    "contact_id": 2001,
    "device_id": 3,
    "direction": "outbound",
    "type": "text",
    "status": "queued",
    "error": null,
    "client_reference": "pedido-1001",
    "created_at": "2026-10-22T12:00:00Z",
    "updated_at": "2026-10-22T12:00:00Z"
  }
}

Si una regla lo frenaCopiar el enlace a esta sección

El envío no sale ni queda registrado, y la respuesta es { "error": "<código>", "message": "<explicación>" }:

Decidí por el código y por error, no por el texto de message. El detalle está en Reglas de WhatsApp.

Si la llamada no respondeCopiar el enlace a esta sección

Con un error 5xx o sin respuesta no sabés si el mensaje quedó registrado. No reintentes enseguida: esperá al menos un minuto y buscá tu client_reference en el historial del contacto.

• Si aparece, el mensaje quedó registrado: no lo reenvíes; su resultado llega por message.status_changed o por la consulta del mensaje.
• Si no aparece, no salió nada y podés reintentar.

Repetir la misma client_reference no evita duplicados: dos llamadas con la misma referencia registran dos mensajes. Las tarjetas de contacto y los reenvíos tienen sus propias reglas para este caso: están en la página de cada endpoint.

Lo que sigue cerradoCopiar el enlace a esta sección

• Lo que puede producir muchos mensajes con una sola llamada (ejecutar una difusión, arrancar un flujo, disparadores, agregar o quitar etiquetas a contactos, porque una etiqueta puede disparar un flujo): queda fuera del piloto y responde 403 route_not_available con cualquier permiso. Ver Qué está abierto a claves.
• Grupos (communities): en v0, una clave lee grupos y participantes; por la API solo se les escribe a personas. Ver Grupos.

RelacionadoCopiar el enlace a esta sección

• Armá tu propio flujo: un flujo completo, del mensaje que entra a la respuesta.
• Mensajes: qué podés mandar, archivos por URL, plantillas y formularios.
• Reglas de WhatsApp: la ventana, los frenos, el ritmo por número y las bajas.
• Permisos: qué habilita cada permiso en cada dominio.