API · bot

GET /bot

Personalidad vigente (owner/manager)

• Autenticación: Clave de API o sesión del panel
• Scopes: config:read

Respuestas

PUT /bot

Guardar personalidad versionada (owner/manager, CSRF)

version opcional permite control optimista (409 bot_version_conflict). Texto del dueño es una preferencia no confiable; nunca cambia reglas, tools ni datos críticos.

• Autenticación: Clave de API o sesión del panel
• Scopes: config:write

Parámetros

Cuerpo de la solicitud (obligatorio)

• application/json: BotConfig

Respuestas

GET /bot/channel-policies

Política del bot por canal (owner/manager)

Una entrada por canal (webchat, whatsapp); sin fila guardada devuelve los defaults del canal con is_default=true y versión 0.

• Autenticación: Clave de API o sesión del panel
• Scopes: config:read

Respuestas

PUT /bot/channel-policies/{channel}

Guardar la política de un canal (owner/manager, CSRF)

version opcional para control optimista (409 channel_policy_version_conflict). contact_gate distinto de never exige required_contact y solo existe en canales con formulario (webchat; 422 en los demás). unknown_contact_policy = filtered no existe en webchat (422 policy_not_available_for_channel). contact_gate_turns solo aplica a after_turns y no puede superar max_bot_turns. Modo de atención (ADR 0056): attention_mode = by_schedule da 422 attention_mode_not_available hasta que existan las franjas. Los textos libres son preferencias no confiables. Auditado (bot.channel_policy_updated, sin copiar el texto).

• Autenticación: Clave de API o sesión del panel
• Scopes: config:write

Parámetros

Cuerpo de la solicitud (obligatorio)

• application/json: ChannelPolicyIn

Respuestas

GET /bot/conversations/{conversation_id}/path

Recorrido de una conversación por el árbol de atención (flows:read; API key config:read)

Cada tramo de la conversación del bot de clientes (ADR 0040 §4.4, F3-724): por qué rama pasó (y la sub-salida, si el ítem siguió un flujo distinto del habitual) y dónde se cortó: task_created (con el id de la tarea), answered, handoff, abandoned (con el último paso que el bot pidió, p. ej. destination), expired o in_progress. Del tramo más viejo al más nuevo (los últimos 50). Los nombres salen del árbol de hoy. Sin texto del cliente ni datos personales. 404 si la conversación no es de este proyecto.

• Autenticación: Clave de API o sesión del panel
• Scopes: flows:read, config:read

Parámetros

Respuestas

GET /bot/offer

Qué ofrece el bot por chat hoy (bot:read; API key config:read)

La misma regla que usa el bot (ADR 0047): tipo habilitado en «Qué vende el bot» (sells), ítem con bot_offered y activo; nunca el servicio de sistema de la membresía. Sin cliente ni conversación: no aplica la cobertura por zona del cliente. Sin flow_id/stage tampoco aplica la etapa del flujo (narrowed_by null). Con flow_id y stage (juntos; uno solo da 422 bot_offer_stage_incomplete) devuelve lo que el bot ofrecería a un cliente con su tarea en esa etapa: el bot_offers de la versión vigente del flujo, con la misma regla que la conversación (solo achica; narrowed_by null si la etapa hereda). Flujo que no es del proyecto o etapa que no está en su versión vigente: 404 (service_stages_not_found, detalle flow_not_found o stage_not_found). stages lista las etapas de los flujos activos cuyo bot_offers achica la lista (vacío: ninguna). Productos: hasta 500 por modalidad de pedido, en el orden del catálogo.

• Autenticación: Clave de API o sesión del panel
• Scopes: bot:read, config:read

Parámetros

Respuestas

GET /bot/tree

Árbol de atención del bot (bot:read; API key config:read)

La raíz «Atención del bot» y un nivel de ramas (ADR 0040 §4.4, F3-723), calculadas del catálogo, de «Qué vende el bot» (sells), de la base de conocimiento y de los flujos; no se guarda nada. Ramas estándar: services, products, subscriptions (aparecen solas si el negocio tiene algo para ofrecer), faq (si la base de conocimiento tiene algún ítem activo), mine y handoff (siempre); y una rama flow:<id> por cada flujo por intención activo. Las ramas de catálogo salen de la misma regla del bot (ADR 0047) sin el nivel de «Qué vende el bot», así que una rama pausada se sigue viendo (paused: true). La pausa de services, products y subscriptions es sells (bookings, orders, plans): se escribe con PUT /bot (permiso bot:configure), el mismo campo que «Qué vende el bot». Una rama propia se pausa con customer_can_start de su flujo. faq, mine y handoff no se pausan (pausable false). exit es la tarea que crea la rama y su flujo (faq, mine y handoff: null); sub_exits, los ítems con un flujo distinto del habitual; sources, de dónde salen los productos (una integración es fuente, no rama). El orden es el que guardó el dueño en la raíz (order, F3-467; PATCH /flows/{flow_id} con flows:write) o, sin él, el de §4.4; una rama que aparece después entra en su lugar por defecto. El bot usa este mismo orden, sin las pausadas, para la bienvenida, el menú sin IA, la lista cerrada de la elección y customer.offer.

• Autenticación: Clave de API o sesión del panel
• Scopes: bot:read, config:read, flows:write

Respuestas

GET /bot/tree/funnel

Embudo de cada rama del árbol de atención (flows:read; API key config:read)

Recorrido de las conversaciones por el árbol de atención (ADR 0040 §4.4, «Recorrido de cada conversación», F3-724), por rama, en los últimos days días locales del proyecto (hoy incluido): cuántos tramos entraron, crearon tarea (task_created), se respondieron sin tarea (answered), derivaron a una persona (handoff), se abandonaron (abandoned; también un tramo quieto más de 30 minutos), vencieron (expired, el TTL de la corrida) o siguen en curso, y en qué paso se cortaron los abandonados y vencidos (cuts). Sin pruebas (simulador y clientes de prueba), con el mismo criterio de días que el uso de flujos. Solo vienen las ramas con algún tramo; root cuenta los que no eligieron rama. Sin texto del cliente ni datos personales. Permiso flows:read (owner y manager) mientras no exista el de uso de flujos.

• Autenticación: Clave de API o sesión del panel
• Scopes: flows:read, config:read

Parámetros

Respuestas