BonggaBongga bongga← Inicio

API pública: enviar mensajes desde tu sistema

Desde Configuración → API (/configuracion/api) puedes crear una API key para que tus propios sistemas envíen mensajes de WhatsApp a través de Bongga, sin pasar por el panel.

Crear una API key

Ponle un nombre (por ejemplo, el sistema que la va a usar) y créala. La clave completa se muestra una sola vez — cópiala y guárdala en un lugar seguro, porque después solo verás los primeros caracteres.

Enviar un mensaje

Una petición POST autenticada con la API key en el encabezado Authorization:

curl -X POST https://app.bongga.dev/api/v1/messages \
  -H "Authorization: Bearer bga_live_..." \
  -H "Content-Type: application/json" \
  -d '{"to": "573001234567", "text": "Hola desde mi sistema"}'

Si el contacto no existía todavía, Bongga lo crea automáticamente (igual que cuando alguien te escribe por primera vez). El mensaje aparece en tu Bandeja como cualquier otro.

Si tu organización tiene más de una bandeja conectada, agrega channelId para elegir por cuál notificar (lo encuentras en Configuración → API, junto a tus bandejas conectadas). Sin ese campo, se usa la primera bandeja conectada.

Texto libre solo funciona dentro de la ventana de 24 horas con ese contacto. Si nunca te ha escrito (o hace más de 24h que no lo hace), usa una plantilla aprobada en su lugar — ver abajo.

Enviar una plantilla aprobada

Para abrir una conversación nueva (o recontactar fuera de la ventana de 24h), envía una plantilla en vez de texto libre — igual que en Campañas, pero desde tu propio sistema. Las variables van en orden, como una lista ({{1}}, {{2}}…):

curl -X POST https://app.bongga.dev/api/v1/messages \
  -H "Authorization: Bearer bga_live_..." \
  -H "Content-Type: application/json" \
  -d '{"to": "573001234567", "templateId": "tpl_...", "variables": ["Juan", "mañana 3pm"]}'

Disparar una campaña

Un segundo endpoint envía una plantilla a todo un segmento de contactos (por etiqueta o etapa del embudo), igual que Campañas en el panel — pero se lanza de inmediato, sin quedar en borrador:

curl -X POST https://app.bongga.dev/api/v1/campaigns \
  -H "Authorization: Bearer bga_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Recontacto de julio",
    "templateId": "tpl_...",
    "segment": {"labelIds": ["lbl_..."]},
    "variableMapping": {"1": {"kind": "field", "value": "name"}}
  }'

La bandeja de la campaña es siempre la misma de la plantilla elegida — no hace falta indicarla aparte. Puedes ver el progreso y las métricas de la campaña como cualquier otra, desde Campañas en el panel.

Plantillas: listarlas y usarlas

Para enviar fuera de la ventana de 24 horas necesitas una plantilla aprobada. Puedes listar las que tienes:

curl "https://app.bongga.dev/api/v1/templates?status=approved" \
  -H "Authorization: Bearer bga_live_..."

Devuelve id, name, channelId, channelName, language, category, status, variableCount y body. Filtros opcionales: status y channelId.

Al enviar puedes referirte a la plantilla por templateName en vez de templateId, que es lo cómodo si vas a dejarlo fijo en tu código:

curl -X POST https://app.bongga.dev/api/v1/messages \
  -H "Authorization: Bearer bga_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+573001112233",
    "templateName": "recordatorio_cita",
    "variables": ["Ana", "martes 9:00"]
  }'

El nombre no es único: la misma plantilla puede existir en varios canales o idiomas. Si hay más de una coincidencia recibes un 409 con la lista de candidatas, y desambiguas añadiendo channelId o language. Preferimos eso a elegir una por ti: mandarle al cliente la plantilla equivocada es peor que un error.

Mensajes con botones y listas

El mismo /api/v1/messages acepta un campo interactive en vez de text. En WhatsApp salen como botones nativos, en Telegram como teclado en línea, y en el widget web se degradan a texto con las opciones listadas.

curl -X POST https://app.bongga.dev/api/v1/messages \
  -H "Authorization: Bearer bga_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+573001112233",
    "interactive": {
      "kind": "buttons",
      "body": "¿Confirmas tu cita del martes a las 9:00?",
      "buttons": [
        { "id": "confirmar", "title": "Sí, confirmo" },
        { "id": "cambiar",   "title": "Cambiar hora" }
      ]
    }
  }'

Los cuatro tipos, con los límites que impone WhatsApp:

  • buttons: hasta 3 botones, título de 20 caracteres. El id es lo que te llega de vuelta cuando el cliente toca.
  • list: hasta 10 filas, título de 24 y descripción opcional de 72.
  • cta_url: un botón que abre un enlace. No genera respuesta.
  • image: una imagen por URL con caption opcional.

Cuando el cliente toca un botón, su id entra como si hubiera escrito ese texto: dispara los flujos y llega al agente de IA igual que un mensaje normal, y lo recibes por el webhook message.received. No hay un evento aparte para los toques.

Aplica la misma ventana de 24 horas que el texto libre: fuera de ella hay que usar una plantilla aprobada.

Límites de la versión actual

  • 60 solicitudes por minuto por organización (aplica a ambos endpoints).
  • Puedes revocar una API key en cualquier momento; los sistemas que la usen dejan de funcionar de inmediato.