Casos de uso

El Canal API es deliberadamente genérico: enviás un mensaje y recibís la respuesta del bot. Lo que cambia entre integraciones es dónde vive la conversación y cómo entregás la respuesta al usuario final. Estos son los patrones más comunes.

1. Widget de chat en tu sitio web

El visitante chatea desde tu web sin que tu sk_live_ salga del backend.

1. Tu backend genera un token efímero csk_eph_* scoped al session_id del visitante.
2. El browser envía mensajes directo a POST /channel/message con ese token.
3. La respuesta del bot llega a tu webhook; la empujás al browser por WebSocket/SSE, o usás directamente streaming SSE para el efecto “typing”.

Claves: token en memoria (no localStorage), TTL bajo, session_id = un identificador opaco por visitante (cookie, UUID de sesión).

2. Chat dentro de tu app móvil

La app conversa contra tu backend; tu backend habla con el Canal API con la sk_live_ (server-to-server).

1. La app manda el texto del usuario a tu backend.
2. Tu backend hace POST /channel/message con session_id = el ID del usuario en tu sistema.
3. Recibís message.response en tu webhook y lo entregás a la app (push notification, WebSocket, long-polling).

Claves: un session_id estable por usuario mantiene el contexto entre sesiones de la app. Usá Idempotency-Key por mensaje para tolerar reintentos de red del móvil.

3. Agente embebido en tu CRM o help desk

Sumás una bandeja conversacional dentro de tu propio CRM/help desk.

1. Cada hilo del CRM mapea a un session_id.
2. Mostrás el historial con GET /channel/conversations/{session_id}/messages.
3. Cuando llega handoff.requested, marcás el hilo como “requiere humano” y lo asignás a un agente; usás conversation_url para abrir la conversación completa en el panel de Overtaker.

Claves: handoff.requested es tu señal de escalamiento — no esperes respuestas del bot después de recibirlo.

4. Bot dentro de tu SaaS multi-tenant

Ofrecés un asistente a tus usuarios finales dentro de tu producto.

• Un session_id por usuario final (no por cuenta) para que cada uno tenga su propio contexto.
• Enriquecé el lead pasando email cuando lo conozcas: el bot lo asocia al Lead correcto y podés leer el snapshot del lead para tu CRM interno.

5. Captura de leads + handoff a tu equipo

Una landing o formulario conversacional que califica antes de pasar a ventas.

1. El visitante conversa; el bot captura datos y emite lead.captured (granular).
2. Consolidás el lead completo con GET /channel/leads/{lead_id} — incluye qualification_score, funnel_stage, sentiment, value, tags.
3. Cuando el lead está listo, el bot emite handoff.requested y tu equipo lo toma.

Claves: los campos de fields en lead.captured solo traen lo que cambió; el snapshot trae todo. Decidí tu umbral de handoff con qualification_score.

6. Completar datos estructurados de a poco (formulario conversacional)

Una entrevista o encuesta conversacional que va llenando campos de un registro de tu sistema (un perfil, un proyecto, un onboarding) a medida que el usuario responde.

1. Creás la sesión con un session_id estable por entidad (ej. proyecto-<id>) → todos los datos se acumulan en un mismo contacto.
2. El agente captura cada respuesta y emite contact.updated con changes — solo lo nuevo/cambiado en esa interacción.
3. Mapeás el session_id del evento a tu registro y guardás cada campo de changes. Si el usuario corrige algo, llega un contact.updated con el valor actualizado.
4. Tu sistema decide cuándo está “completo” haciendo seguimiento de los campos que fue recibiendo (no hay un evento de “completado”).

Claves: las claves de changes son los nombres de campo que definís en la config del agente; usá un session_id estable para que sea 1 entidad = 1 contacto; event_id para idempotencia.

Nombrar el contacto desde el arranque

Si ya conocés el nombre de la entidad (cliente, empresa, proyecto), pasá contact_name en el mensaje para que el contacto sea legible en el panel desde el inicio — sin esperar a que el agente lo capture. Nombra mientras el contacto no tenga nombre; no pisa uno ya capturado.

Cómo configurar al agente para capturar estos campos

La captura la define quien administra el agente (en el panel), no la API. Hay dos modos:

• Inferencia automática: el agente capta datos personales que el usuario menciona y los guarda con claves descriptivas que elige el modelo. Sirve para no perder información, pero no controla el nombre exacto de la clave.
• Captura controlada por protocolo (recomendada para integraciones): el agente cuenta con la herramienta save_permanent_data, que persiste un dato en los datos permanentes del contacto bajo el nombre de variable exacto que se le indica. Un protocolo del agente define qué preguntar y, ante cada respuesta, llama a save_permanent_data con ese nombre. Ejemplo:

  save_permanent_data(variable="rubro", value="gastronomía")

  El nombre (rubro) es exactamente la clave que llega en changes del evento contact.updated. El agente además puede inferir respuestas de lo que el usuario ya dijo y preguntar solo lo que falta (no repite lo que ya tiene).

Como los protocolos se activan según la situación de la conversación, la entrevista puede correr por etapas: distintos protocolos para distintos momentos — el agente captura solo lo de esa etapa.

¿Quién configura esto?

El protocolo del agente y los nombres de variable los configura OvertakerAI (no se configuran por la API). Como integrador del Canal API, vos solo consumís los eventos contact.updated: las claves de changes ya vienen con los nombres definidos en el protocolo. Coordiná con OvertakerAI qué variables querés recibir.

7. Soporte con tickets integrado a tu sistema interno

Si el tenant tiene el módulo de Tickets activo (BotRole con goal support_ticket), el bot abre y mueve tickets que vos sincronizás con tu sistema.

1. ticket.created → creás el ticket en tu herramienta con ticket_number, category, urgency, description.
2. ticket.state_changed → reflejás el cambio de estado (NUEVO → ABIERTO → ... → CERRADO).
3. ticket.resolved → cerrás el ticket con el campo resolution.

8. Sandbox en CI/CD y wizards de setup

Validá tu integración sin gastar LLM ni cuota:

• GET /channel/ping en tu pipeline para verificar que la key es válida y el plan incluye Canal API.
• POST /channel/message/sandbox para simular el flujo completo (incluido el webhook firmado) sin orquestar una conversación real.
• POST /channel/webhooks/test para probar tu handler de cada tipo de evento.

Claves: el sandbox usa su propio bucket (600/min) y marca los payloads con "sandbox": true, así tu handler los distingue del tráfico real.