Kommo: cómo funciona

Kommo conecta tu espacio con tu cuenta del CRM Kommo. Hace dos cosas:

• Chat automático: los mensajes que tus clientes escriben por Kommo (por WhatsApp, por ejemplo) le llegan a Bentho, que contesta en el mismo chat con el agente de Ventas del espacio. Si lo enciendes, también entiende notas de voz y recoge comprobantes de pago.
• Etapas sincronizadas: cuando un cliente cambia de estado en Bentho (nuevo, contactado, ganado…), su tarjeta se mueve a la etapa que elijas de tu embudo en Kommo.

Por API conectas la cuenta, eliges las etapas, enciendes o apagas cada pieza y vigilas los envíos a Kommo. También puedes hacerlo desde la consola: entra al Estudio de un espacio con el módulo activo y abre Kommo.

Antes de empezar

• El espacio tiene que tener el módulo Kommo: kommo sale en sus módulos en GET /api/companies. Si no, cada ruta responde 403 módulo no habilitado para este espacio.
• Cambiar la configuración, probar la conexión, sincronizar, procesar o reintentar envíos, reiniciar chats y borrar piden una clave escribe. Leer vale con cualquier clave.
• Las rutas cuelgan de /api/mod/kommo/{espacio}/, con la misma clave y los mismos límites que el resto de la API.
• Necesitas una cuenta de Kommo con permiso para crear integraciones, y el acceso a la consola de Bentho para copiar las direcciones que se pegan en Kommo (más abajo).

Conectar tu cuenta, paso a paso

1. En Kommo, crea una integración privada y copia su token de larga duración.
2. Guárdalo con PATCH config, junto con tu subdominio y el canal (modo_canal).
3. Prueba la conexión: tiene que responder ok: true.
4. Lee tus embudos y etapas y guarda en mapeo_estados a qué etapa va cada estado.
5. Pega en Kommo las direcciones de tu espacio.
6. Prueba con un chat tuyo: ponlo en chat_allowlist y enciende bot_activo. Cuando conteste bien, vacía la lista para atender a todos.
7. Si quieres, enciende sync_leads_activo, audio_activo y adjuntos_activo.

{
  "subdomain": "tiendaaurora",
  "auth_mode": "long_lived",
  "token_expires_at": 0,
  "credenciales": { "access_token": "TU_TOKEN_DE_LARGA_DURACION" },
  "modo_canal": "salesbot"
}

Las credenciales no salen nunca en las respuestas: credenciales_set dice cuáles hay guardadas. OAuth (client_id y client_secret en credenciales) no se completa con una clave: la autorización en Kommo pide una sesión de la consola. Por API, usa el token de larga duración.

Las direcciones que pegas en Kommo

Kommo avisa a Bentho llamando a una dirección propia de tu espacio. No la llamas tú: la pegas en Kommo. Está en la consola, en el panel de Kommo del Estudio, bajo Direcciones para pegar en Kommo:

• Dirección del canal de chat: https://bentho.org/api/hooks/kommo/inbound/<token>. El token identifica tu espacio.
• Dirección de retorno: https://bentho.org/api/hooks/kommo/oauth/callback. Solo para OAuth: es la dirección de redirección de tu integración en Kommo.

Dónde pegar la del canal de chat depende de cómo lleguen los mensajes:

• modo_canal: "salesbot", para los canales oficiales de Kommo como WhatsApp: un paso Widget de tu Salesbot (el widget de Bentho) le pasa cada mensaje a esa dirección, y un paso «Mensaje» muestra la respuesta, que vuelve en {{json.message}}.
• modo_canal: "custom": los mensajes llegan por el canal de chat de Bentho conectado a tu cuenta (scope_id). Esos llegan firmados.
• En los dos casos, pega la misma dirección en los webhooks de tu cuenta de Kommo, con los eventos de cambio de etapa del lead (para traer los cambios que hagas a mano) y de mensaje entrante (para no perder ningún texto y para las notas de voz y los comprobantes).

Bentho contesta a Kommo enseguida con {"ok": true} y hace el trabajo después. Con un token que no es el de tu espacio, 401 No autorizado.; si no puede atenderlo en ese momento, 502, y Kommo lo reintenta.

Trata esa dirección como una contraseña: quien la tenga puede mandar mensajes a tu espacio. Leerla o cambiarla por otra (la anterior deja de valer al momento) pide una sesión de la consola: con una clave bth_, la ruta que la da responde 403 Esta operación requiere una sesión de usuario.

Estados y etapas

Cada cliente que llega por el chat tiene un estado en Bentho. En mapeo_estados dices a qué etapa de Kommo (pipeline_id y status_id) corresponde cada uno:

• De Bentho a Kommo: con sync_leads_activo, cada cambio de estado mueve la tarjeta (o la crea si aún no existe). Para forzar una pasada, sincroniza las etapas.
• De Kommo a Bentho: si mueves a mano una tarjeta a la etapa de contactado o de cerrado, Bentho actualiza al cliente (llega por el webhook de cambio de etapa). ganado lo decide la venta en Bentho, no la tarjeta.
• Cuando un cliente pide una persona, el bot se calla en ese chat pausa_humano_ttl_s segundos (una hora por defecto). Si mapeaste handoff, la tarjeta pasa a esa etapa, asignada a responsable_handoff_id. El bot también se calla cuando escribe alguien de tu equipo.

Los envíos a Kommo

Todo lo que Bentho hace en Kommo es un envío: contestar un chat, mover una tarjeta, entregar un comprobante. Si uno falla, se reintenta solo, hasta 5 veces; después queda descartado para que lo mires.

pending → processing → done
                    ↘ failed → (se reintenta solo) → processing
                    ↘ dead            (5 intentos: descartado)
dead | failed → (reintentar) → pending

1. Mira cuántos hay en cada estado en estado de envíos.
2. Si hay descartados, léelos en envíos con ?estado=dead: motivo_error dice qué pasó.
3. Arregla la causa (un token caducado, una etapa borrada en Kommo) y reinténtalo.
4. Para no esperar, procesa los envíos ahora.

Los mensajes seguidos de un mismo cliente se contestan juntos, cuando deja de escribir (debounce_s), y dentro de un chat todo sale en orden.

Probar sin molestar a tus clientes

• Con ids en chat_allowlist, el bot solo contesta a esos chats. Con el Salesbot, el id de un chat es el del lead en Kommo.
• Para repetir una prueba desde cero, reinicia los chats de prueba: se borra su carrito y su pedido abierto. Solo funciona con la lista llena, para no tocar nunca a un cliente de verdad.
• Con bot_activo: false el chat automático se apaga del todo; lo demás sigue.

Créditos

• Las rutas de este módulo no gastan créditos.
• Las respuestas del chat automático las escribe Ventas: gastan créditos de la bolsa de tu cuenta como sus conversaciones.
• El saldo, en la bolsa de créditos.

Rutas