Mandar mensajes

Texto dentro de las 24 horas, plantillas fuera de ellas, y lo que frena un envío.

Con el permiso «Mandar mensajes», tu sistema le escribe a un cliente por WhatsApp. El mensaje sale firmado con el nombre de la clave —en Conversaciones se lee «API · Sistema de envíos»—, no gasta turnos del asistente y no le quita la conversación a nadie del equipo.

Texto o plantilla

• Texto, solo si la persona te escribió por esa línea en las últimas 24 horas. Si no, la API responde 409 window_closed: WhatsApp solo deja retomar con una plantilla aprobada.
• Plantilla, aprobada por Meta y de esa línea, por su nombre y su idioma. Los valores van en orden: el primero es {{1}}. Si la persona no tiene conversación, se le abre una.

curl -X POST https://app.koonni.com/api/v1/messages \
  -H "Authorization: Bearer kn_live_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+57 300 123 4567", "template": {"name": "aviso_de_guia", "language": "es", "variables": ["MV-1"]}, "idempotencyKey": "guia-MV-1-reparto"}'

A quién

Con contactId si ya lo tienes, o con phone: si ese teléfono no tiene ficha, se crea (con name, si lo das). Si tu empresa tiene varias líneas de WhatsApp, di por cuál con lineId.

Lo que frena un envío

• opted_out: la persona se dio de baja del marketing. Las plantillas de utilidad —un aviso de su pedido— sí le llegan.
• template_unavailable o missing_variables: la plantilla no existe, no está aprobada o le faltan valores.
• daily_limit_reached, meta_limit_reached y quality_paused: los límites.

Saber si salió

La API responde 202 con el mensaje en cola. Que salió de verdad lo cuenta el webhook message.sent, con authoredBy: "api".

Siguiente: Recibir leads →