API de Chatflow

En la app, entra al negocio que quieres conectar y ve a API y Webhooks. Crea una llave, marca solo los permisos que tu integración necesita y cópiala: se muestra una sola vez.

Todas las rutas viven en https://chatapp.chatflow.mx/api/v1, reciben y devuelven JSON.

curl "https://chatapp.chatflow.mx/api/v1/leads?limit=5" \
  -H "Authorization: Bearer TU_LLAVE"

En API y Webhooks agrega la URL de tu servidor (https) y elige los eventos. Con el botón Probar te llega un evento de prueba en menos de un minuto, para comprobar tu URL y la verificación de la firma antes de que pase algo real. Ver Webhooks.

Una llave solo ve y toca el negocio donde se creó. Si tu cuenta tiene varios negocios, crea una llave en cada uno.

El servidor revisa el permiso en cada petición. Sin el permiso responde 403 y dice cuál falta.

Desde la misma pantalla. La llave deja de funcionar en ese momento.

Un POST a tu URL con este cuerpo. data cambia según el evento; lo demás es igual para todos.

{
  "id": "uuid del evento",
  "type": "lead.stage_changed",
  "created_at": "2026-10-01T17:04:12.345Z",
  "lead_id": "uuid",
  "conversation_id": null,
  "agent_id": "uuid",
  "data": { "stage": "Calificado", "changed_by": "human" }
}

Sin verificarla, cualquiera que conozca tu URL puede inventarte eventos. Calcula el HMAC-SHA256 de `${timestamp}.${cuerpo}` con tu secreto y compáralo con la firma. Usa el cuerpo tal como llegó, antes de convertirlo a JSON: cualquier espacio de diferencia cambia la firma.

import crypto from 'node:crypto'

// En Express usa express.raw({ type: 'application/json' }) en esta ruta:
// la firma se calcula sobre el cuerpo exacto, antes de convertirlo a JSON.
app.post('/chatflow', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.header('X-ChatFlow-Timestamp')
  const signature = req.header('X-ChatFlow-Signature')
  const body = req.body.toString('utf8')

  const expected = crypto
    .createHmac('sha256', process.env.CHATFLOW_WEBHOOK_SECRET)
    .update(`${timestamp}.${body}`)
    .digest('hex')

  const valid =
    signature?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  // Rechaza también lo viejo: evita que alguien reenvíe un evento capturado.
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300

  if (!valid || !fresh) return res.status(401).end()

  const event = JSON.parse(body)
  res.status(200).end()          // responde rápido...
  handle(event)                  // ...y procesa después (descarta ids ya vistos)
})

import hashlib, hmac, os, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["CHATFLOW_WEBHOOK_SECRET"].encode()

@app.post("/chatflow")
def chatflow():
    timestamp = request.headers.get("X-ChatFlow-Timestamp", "")
    signature = request.headers.get("X-ChatFlow-Signature", "")
    body = request.get_data(as_text=True)

    expected = hmac.new(SECRET, f"{timestamp}.{body}".encode(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(signature, expected):
        abort(401)
    if abs(time.time() - int(timestamp)) > 300:
        abort(401)

    event = request.get_json()
    # ... descarta event["id"] si ya lo procesaste
    return "", 200

¿Perdiste el secreto? En la pantalla del webhook, Generar secreto nuevo. El anterior deja de valer en ese momento.

Responde con un código 2xx en menos de 10 segundos; si tu proceso tarda, responde primero y procesa después. Si no responde o responde con error, se reintenta a 1, 5, 30 y 120 minutos; después del quinto intento se marca como fallido. En la pantalla del webhook ves cada entrega con su código de respuesta.

1. Tu agente propone un mensaje con POST /whatsapp/messages.
2. Alguien del negocio lo aprueba en la pantalla Propuestas, o con otra llave que tenga proposals:decide.
3. Chatflow lo envía cuando el número tiene cupo, en horario hábil.
4. Si el contacto no era lead, queda registrado con fuente whatsapp_outbound.
5. Cuando contesta, te llega message.received con lo que dijo, y la respuesta queda en la misma conversación.

• Conecta tu número de WhatsApp Business (Meta) en Integraciones, desde el negocio que va a enviar.
• Crea y aprueba tus plantillas en tu cuenta de Meta. El primer contacto siempre va con plantilla.
• Crea una llave con whatsapp:propose.

Un número nuevo que manda mucho de golpe termina bloqueado por Meta. Por eso cada número tiene un tope diario que crece mientras se calienta: 5, 10 y 20 mensajes al día las primeras tres semanas, en horario hábil (9 a 18, lunes a viernes, hora de la Ciudad de México) y con huecos irregulares entre envíos. El tope cuenta todo lo que sale del número, campañas incluidas. Un envío aprobado espera en queued hasta su turno.

Te llega message.received con el texto y in_reply_to (el envío al que contesta). La respuesta queda en la misma conversación aunque llegue días después, y el chatbot de Chatflow no contesta en conversaciones que abrió tu agente. Desde ese momento tienes 24 horas para responder con mode: "text". Si escribe "baja" o "stop", te llega contact.opted_out y ese teléfono ya no recibe envíos.

Los errores traen un código estable para tu programa y un mensaje para una persona.

{ "error": "missing_scope", "required": "leads:write", "message": "Esta llave no tiene el permiso \"leads:write\"." }

100 peticiones por minuto por llave. Los envíos de WhatsApp, además, salen al ritmo de su número.