API: crear y consultar leads desde tu sistema

Además de enviar mensajes, la API deja crear leads, consultarlos y moverlos de etapa. La autenticación es la misma API key de Configuración → API.

Permisos

Al crear una key eliges qué puede hacer: leer leads, crearlos, actualizar contactos, enviar mensajes, disparar flujos. Dale solo lo que necesite: una key para que tu web mande leads no tiene por qué poder enviar WhatsApp a nombre del negocio.

Crear un lead

curl -X POST https://app.bongga.dev/api/v1/leads \
  -H "Authorization: Bearer bga_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-9912" \
  -d '{
    "phone": "+573001112233",
    "name": "Ana Pérez",
    "email": "ana@ejemplo.com",
    "extra": { "id_en_mi_erp": "CLI-9912" }
  }'

El Idempotency-Key es importante: si tu sistema reintenta la petición (porque se cayó la red, por ejemplo), con la misma clave no se crea un lead duplicado ni se vuelven a disparar los flujos. Usa algo estable de tu lado, como el id del pedido.

Sincronizar cambios

curl "https://app.bongga.dev/api/v1/leads?updatedSince=2026-08-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer bga_live_..."

La respuesta trae nextCursor. Vuelve a pedir con ?cursor=... hasta que llegue null. No uses número de página: si un lead se actualiza mientras paginas, con páginas te saltarías otro.

Mover de etapa

curl -X PATCH https://app.bongga.dev/api/v1/leads/ld_abc123 \
  -H "Authorization: Bearer bga_live_..." \
  -H "Content-Type: application/json" \
  -d '{"stageKey": "calificado"}'

Un cambio hecho por API dispara los flujos de cambio de etapa igual que si lo hubiera arrastrado alguien en el embudo, y queda en Auditoría.

Disparar un flujo

Crea un flujo con el disparador Webhook entrante y llámalo desde tu sistema. Lo que mandes queda disponible dentro del flujo como {{webhook.campo}}.

curl -X POST https://app.bongga.dev/api/v1/flows/fl_abc/trigger \
  -H "Authorization: Bearer bga_live_..." \
  -H "Content-Type: application/json" \
  -d '{"phone": "+573001112233", "pedido": {"total": 90000}}'

Límites

60 peticiones por minuto por API key. Si te pasas recibes un 429 con la cabecera Retry-After diciéndote cuántos segundos esperar.