# Documentación oficial de Orkestal

Fuente: https://orkestaliq.com/docs · Última actualización: 2026-11-04.
Orkestal es una plataforma en español para atender clientes con un agente de IA en WhatsApp, Instagram, Messenger y Telegram.
Si algo de este texto contradice lo que ves en la cuenta del usuario, manda lo que ve el usuario: pídele que lo confirme o que escriba a soporte@orkestaliq.com.


# Empezar


## Qué es Orkestal

> Orkestal conecta tus canales de mensajería con un agente de IA que conoce tu negocio, y deja a tu equipo intervenir cuando hace falta.
Fuente: https://orkestaliq.com/docs/empezar/que-es-orkestal

Orkestal es una plataforma para **atender a tus clientes por mensajería con un agente de inteligencia artificial** que conoce tu negocio. El agente contesta preguntas, recomienda productos, agenda citas, manda enlaces de pago y pasa la conversación a una persona de tu equipo cuando corresponde. Todo llega a una sola bandeja compartida.

Funciona con **WhatsApp, Instagram, Messenger y Telegram**.

### Cómo viaja un mensaje

1. Un cliente te escribe por alguno de tus canales.
2. Orkestal guarda el mensaje en la bandeja y revisa si el agente debe contestar. No contesta si la IA está apagada o pausada en ese chat, si el chat ya lo atiende una persona, si estás fuera del horario que definiste, si falta la clave de IA o si la cuenta tiene un pago pendiente. La [guía de solución de problemas](/docs/ayuda/solucion-de-problemas) recorre estas revisiones en orden.
3. Si el agente debe contestar, redacta la respuesta con lo que tú le enseñaste: tu [base de conocimiento](/docs/conocimiento/base-de-conocimiento), tu [inventario](/docs/conocimiento/inventario) y las [integraciones](/docs/integraciones/resumen) que conectaste.
4. En paralelo, los [flujos](/docs/flujos/introduccion) pueden etiquetar al contacto, avisar a tu equipo, mandar una plantilla o guardar los datos en una hoja de cálculo.
5. Si la conversación necesita a una persona, una [regla de escalamiento](/docs/agente/relevo-humano) la entrega a tu equipo y pausa la IA en ese chat para que no escriba encima de nadie.

### Las piezas del producto

| Pieza | Para qué sirve | Dónde está |
| --- | --- | --- |
| Canales | Conectar WhatsApp, Instagram, Messenger y Telegram | Canales |
| Agente IA | Nombre, estilo de lenguaje, objetivo, horario y reglas de escalamiento | Agente IA |
| Base de Conocimiento | Documentos con precios, políticas y preguntas frecuentes | Base de Conocimiento |
| Inventario | Productos y servicios con precio, existencias, fotos y videos | Inventario |
| Archivos Contexto | Catálogos, menús o mapas que el agente envía al cliente cuando se los piden | Archivos Contexto |
| Flujos | Automatizaciones «Cuando → Hacer» | Flujos |
| Conversaciones | La bandeja donde tu equipo atiende, asigna y etiqueta | Conversaciones |
| Contactos (CRM) | Tus clientes, con etiquetas, etapas y oportunidades | Contactos (CRM) |
| Campañas | Plantillas de WhatsApp y envíos masivos | Campañas |
| Integraciones | Google Calendar, Google Sheets, Stripe, WooCommerce, Mercado Libre, Notion y más | Integraciones |
| Equipo | Invitar personas, asignar roles y repartir conversaciones | Equipo |
| Orki | El asistente que te ayuda a instalar y configurar tu cuenta | Asistente Orki |

### Lo que necesitas para empezar

- **Un canal** donde ya hablas con tus clientes, normalmente WhatsApp.
- **Una clave de API de un proveedor de IA** (OpenAI o Google Gemini). La clave es tuya y el consumo de IA lo cobra tu proveedor directamente; no está incluido en el plan de Orkestal. Detalle en [Clave de IA](/docs/agente/clave-de-ia).
- **Información de tu negocio**: precios, horarios, políticas, preguntas frecuentes y, si vendes productos, tu catálogo.

### Qué hace el agente y qué no

El agente **solo responde con lo que tiene a la mano**: lo que cargaste en tu base de conocimiento, inventario y archivos, y lo que las integraciones conectadas le permiten consultar. Si no encuentra la respuesta, no debe inventarla: la pregunta queda registrada en las **brechas de conocimiento** para que la cubras.

Las herramientas del agente dependen de lo que conectes:

| Si conectas… | El agente puede… |
| --- | --- |
| [Google Calendar](/docs/integraciones/google-calendar) | Proponer horarios libres, agendar, reagendar y cancelar citas |
| [Stripe](/docs/integraciones/stripe) | Crear un enlace de pago y revisar si ya se pagó |
| [Google Sheets](/docs/integraciones/google-sheets) | Consultar valores de tus hojas |
| [Cotización Inteligente](/docs/integraciones/cotizacion-inteligente) | Armar una cotización en PDF con los precios de tu inventario |
| [WooCommerce](/docs/integraciones/woocommerce) | Consultar el estado de un pedido |
| [Envia.com](/docs/integraciones/envia) | Consultar el rastreo de un envío |

> [!NOTA]
> Cada acción del agente cambia lo que ven tus clientes. Por eso Orkestal pide que **tú decidas** cuándo debe usar cada herramienta: las [reglas de uso](/docs/integraciones/resumen#reglas-de-uso-para-el-agente) de cada integración lo controlan.

### Quién puede hacer qué

Orkestal tiene tres roles: **Admin**, **Manager** y **Agente**. Un Agente solo ve las conversaciones que le asignaron; un Manager configura canales, flujos, conocimiento y equipo; un Admin además administra facturación y configuración. Detalle en [Equipo y roles](/docs/atencion/equipo-y-roles).

### Siguiente paso

Sigue la guía [Primeros pasos](/docs/empezar/primeros-pasos): te lleva por la configuración en el orden que evita más tropiezos.


## Primeros pasos

> La configuración de tu cuenta en el orden que evita más tropiezos, desde el registro hasta encender a tu agente.
Fuente: https://orkestaliq.com/docs/empezar/primeros-pasos

Esta guía te lleva de una cuenta nueva a un agente respondiendo a clientes reales. Sigue el orden: cada paso depende del anterior, y el último es **encender la IA**, a propósito, cuando ya probaste que todo funciona.

> [!CONSEJO]
> No tienes que hacerlo solo. **Orki**, el asistente de instalación, te entrevista sobre tu negocio, te pide la clave de IA en un campo seguro y te ayuda a armar tu base de conocimiento. Mira [Orki](/docs/empezar/orki).

### 1. Crea tu cuenta

1. Entra a [orkestaliq.com](https://orkestaliq.com) y elige **Empezar gratis**.
2. Regístrate con tu correo y una contraseña de al menos 8 caracteres, o con **Google**.
3. Si usaste correo, abre el mensaje de confirmación que te enviamos y haz clic en el enlace.
4. Registra tu tarjeta para iniciar la **prueba gratis**. El primer cobro llega cuando termina la prueba; los días de prueba y la fecha de tu primer cobro aparecen en **Facturación**.

Quien se registra obtiene una cuenta de **administrador** con su propio espacio de trabajo. Si te invitaron a un equipo, no te registres: usa el enlace del correo de invitación.

### 2. Conecta tu clave de IA

Sin clave, el agente no puede responder: verás el aviso «Tu agente de IA no está activo».

1. Abre **Configuración** (solo administradores).
2. En **Proveedor de IA** elige OpenAI o Google Gemini.
3. Pega tu clave y pulsa **Guardar Credenciales**.

Cómo obtener la clave y cuánto cuesta, en [Clave de IA](/docs/agente/clave-de-ia).

### 3. Conecta un canal

En **Canales** conecta el canal donde hablas con tus clientes. Tu plan incluye un número limitado de canales; consulta [Canales: resumen](/docs/canales/resumen).

- **WhatsApp**: la forma recomendada es escanear un QR y seguir usando tu app de WhatsApp Business. Mira [WhatsApp](/docs/canales/whatsapp).
- **Instagram y Messenger**: inicias sesión con Meta y eliges tu cuenta o Página. Mira [Instagram y Messenger](/docs/canales/instagram-y-messenger).
- **Telegram**: con el token de tu bot. Mira [Telegram](/docs/canales/telegram).

### 4. Enséñale a tu agente

Cuanto mejor sea la información, mejores serán las respuestas. Empieza por lo que tus clientes más preguntan.

1. **Base de Conocimiento**: sube documentos con precios, políticas, horarios y preguntas frecuentes (PDF, TXT, CSV o Excel). Mira [Base de conocimiento](/docs/conocimiento/base-de-conocimiento).
2. **Inventario**: si vendes productos o servicios, cárgalos con precio y existencias. Mira [Inventario](/docs/conocimiento/inventario).
3. **Archivos Contexto**: si hay archivos que el agente debe *enviar* (un catálogo en PDF, un menú, un mapa), configúralos con la situación en que se mandan. Mira [Archivos de contexto](/docs/conocimiento/archivos-de-contexto).

¿No sabes qué va dónde? Lee [Qué fuente usar para cada cosa](/docs/conocimiento/que-fuente-usar).

### 5. Define cómo habla tu agente

En **Agente IA** configura:

- El **nombre** del agente y de tu negocio.
- El **estilo de lenguaje**.
- El **objetivo de conversión**: la acción a la que lleva al cliente (agendar, cotizar, comprar).
- El **horario de atención** y el mensaje de fuera de horario, si quieres que no conteste 24/7.

Detalle en [Perfil y estilo](/docs/agente/perfil-y-estilo).

### 6. Decide cuándo entra una persona

En la misma pantalla, crea **reglas de escalamiento**: situaciones en las que el agente debe pasar la conversación a tu equipo (una queja, una cotización grande, un cliente que pide hablar con alguien). Mira [Relevo humano](/docs/agente/relevo-humano).

Después invita a tu equipo en **Equipo** y activa la **asignación automática** si quieres que las conversaciones escaladas se repartan solas. Mira [Equipo y roles](/docs/atencion/equipo-y-roles).

### 7. Conecta tus herramientas (opcional)

En **Integraciones** puedes conectar Google Calendar, Stripe, Google Sheets, WooCommerce y más. Cada una le da al agente una capacidad nueva. Mira [Integraciones: resumen](/docs/integraciones/resumen).

### 8. Pruébalo antes de encender

En **Conversaciones**, el **Simulador** te deja hablar con tu agente como si fueras un cliente, sin gastar mensajes de WhatsApp. Prueba las preguntas más comunes, una queja, una petición de hablar con una persona y, si conectaste calendario o pagos, una cita y un pago. Mira [Simulador](/docs/agente/simulador).

Revisa en **Base de Conocimiento → Brechas de Conocimiento** qué preguntas no supo contestar y cúbrelas.

### 9. Enciende la IA

Cuando estés conforme, activa el interruptor **IA Global** en Conversaciones. Desde ese momento el agente contesta en tus canales.

> [!IMPORTANTE]
> El interruptor global lo apaga todo de inmediato si algo sale mal. Además, puedes pausar la IA **en un chat concreto** cuando quieras atenderlo tú.

### 10. Revisa a diario las primeras semanas

- Lee las conversaciones del día en **Conversaciones**.
- Revisa las **brechas de conocimiento** y cúbrelas.
- Ajusta tus reglas de escalamiento según lo que veas.
- Vigila el aviso de calidad de tu número de WhatsApp si vas a mandar campañas.

Si algo no se comporta como esperas, la guía de [solución de problemas](/docs/ayuda/solucion-de-problemas) está organizada por síntoma.


## Orki, el asistente de instalación

> Orki te ayuda a instalar y configurar tu cuenta, resuelve dudas sobre la plataforma y prepara cambios que tú apruebas.
Fuente: https://orkestaliq.com/docs/empezar/orki

**Orki** es el asistente de Orkestal dentro de tu panel. No es el agente que habla con tus clientes: es el que te ayuda **a ti** a dejar la cuenta lista y a entender qué está pasando en ella.

Lo encuentras en **Asistente Orki**, en el menú lateral. En una cuenta nueva también aparece como una burbuja de instalación.

### Qué hace Orki

#### Instalar tu cuenta

- Te **entrevista** sobre tu negocio: a qué te dedicas, qué vendes, cómo atiendes.
- Te pide la **clave de IA** con un campo seguro (nunca la escribas en el chat; ver abajo).
- Te ayuda a redactar y subir tu **base de conocimiento**.
- Te da un **tour guiado** por el panel: pide «Dame un tour» y Orki resalta cada pantalla mientras te la explica.

#### Responder dudas sobre la plataforma

Orki conoce el catálogo completo de funciones de Orkestal y sabe, para cada una, **hasta dónde llega él**: qué puede operar, qué solo puede explicarte y qué te toca hacer a ti. Si le preguntas por algo que existe, no te dirá que no existe; y si te pide hacer algo que él no puede ejecutar, te lo dice y te lleva a la pantalla correcta.

#### Diagnosticar con datos de tu cuenta

En las cuentas que lo tienen habilitado, Orki puede **leer** el estado real de tu cuenta, sin modificar nada:

- Por qué la IA no contestó en un chat concreto (suscripción, interruptor, canal, pausa, horario, clave).
- El estado de recepción de tu WhatsApp, consultado en vivo a Meta, y los mensajes que tu equipo envió pero no se confirmaron.
- Estadísticas de conversaciones, resultados de campañas y consumo de tus mensajes gratis de WhatsApp.
- Un panorama de tus contactos y etiquetas, y el resumen de tus links de pago.

#### Preparar cambios para que tú los apruebes

Cuando Orki propone un cambio, **no lo aplica**: te muestra una tarjeta con el «antes → después» y un botón para aceptarla. Hoy puede preparar:

| Área | Qué puede proponer |
| --- | --- |
| Agente | Cambios de perfil (nombre, estilo, longitud, jerga, emojis, horario) y encender o pausar la IA |
| Reglas de escalamiento | Crear reglas nuevas y editar las existentes |
| Flujos | Crear un flujo, editar los bloques de uno existente, renombrarlo, activarlo o pausarlo |
| Base de Conocimiento | Documentos nuevos o reemplazos de uno existente |
| Contactos | Agregar o quitar etiquetas del catálogo a un contacto |
| Conversaciones | Asignar un chat a una persona del equipo |
| Inventario | Precio y existencias de un producto |

Al aceptar, Orkestal vuelve a leer ese dato. Si **alguien lo cambió mientras tanto**, la propuesta se rechaza para no pisar el cambio hecho a mano, y Orki te propone una versión actualizada.

> [!NOTA]
> Algunas de estas funciones avanzadas de Orki (diagnóstico y cambios con aprobación) se habilitan por cuenta. Si no las ves en la tuya, escríbenos a soporte@orkestaliq.com.

### Lo que Orki no hace

- **No responde a tus clientes** ni reanuda la IA en un chat pausado.
- **No envía campañas** ni plantillas a revisión de Meta.
- **No cambia tu suscripción** ni tu método de pago.
- **No reconecta canales**: te explica cómo y lo haces tú.
- **No borra** flujos, reglas ni productos.
- **No sube ni borra** archivos de contexto, y no invita ni cambia roles del equipo.

### Credenciales: siempre por el campo seguro

Cuando Orki necesita una clave o un token (la clave de tu proveedor de IA, el token de un bot de Telegram), abre un **campo enmascarado**. Lo que escribes ahí se guarda en el lugar correcto de tu cuenta y **Orki nunca lo ve**.

No pegues claves, tokens ni contraseñas en el chat. Todo lo que se escribe en una conversación queda en el historial.

### Lo que Orki recuerda

Orki guarda entre sesiones las **preferencias, decisiones y restricciones** que le pides recordar («siempre escribe de usted», «no tocar las etiquetas de ventas»). Se tratan como notas, no como órdenes, y tienen un tope de 50 notas de 400 caracteres cada una. Orki nunca guarda secretos.

En el panel **Lo que Orki recuerda** puedes ver todo lo guardado y borrar lo que quieras.

### Buenas prácticas

- **Sé específico.** «Cambia el estilo a más formal y no uses emojis» funciona mejor que «hazlo más profesional».
- **Revisa antes de aceptar.** La tarjeta muestra exactamente qué cambia.
- **Una cosa a la vez** cuando se trata de cambios que afectan a tus clientes.
- **Si Orki dice que no puede**, es un límite real, no cortesía: te indicará el paso manual.


## Glosario

> Los términos que usa Orkestal, explicados en una línea y con un enlace a la guía donde se usan.
Fuente: https://orkestaliq.com/docs/empezar/glosario

### A–C

**Agente (de IA)** — La IA que contesta a tus clientes en tus canales. Su nombre, estilo y objetivo se definen en **Agente IA**. No confundir con el rol «Agente» del equipo ni con Orki. → [Perfil y estilo](/docs/agente/perfil-y-estilo)

**Archivos de contexto** — Archivos (catálogos, menús, mapas, fotos) que el agente **envía** al cliente cuando se cumple una situación que tú describes. No son una fuente de consulta. → [Archivos de contexto](/docs/conocimiento/archivos-de-contexto)

**Asignación automática** — Ajuste de **Equipo** que reparte las conversaciones nuevas o escaladas entre las personas conectadas. → [Equipo y roles](/docs/atencion/equipo-y-roles)

**Base de Conocimiento (KB)** — Documentos que el agente consulta para responder con hechos: precios, políticas, preguntas frecuentes. → [Base de conocimiento](/docs/conocimiento/base-de-conocimiento)

**Brecha de conocimiento** — Pregunta de un cliente que el agente no pudo contestar con ninguna de sus fuentes. Aparece en la pestaña «Brechas de Conocimiento» para que la cubras.

**Canal** — Cada servicio de mensajería conectado: WhatsApp, Instagram, Messenger o Telegram. → [Canales](/docs/canales/resumen)

**Clave de IA (API key)** — La llave de tu cuenta con OpenAI o Google Gemini. Orkestal la usa para que tu agente piense y conteste; tu proveedor te cobra el consumo. → [Clave de IA](/docs/agente/clave-de-ia)

**Coexistencia** — Forma de conectar WhatsApp en la que tu número sigue funcionando en la app de WhatsApp Business del celular **y** en Orkestal al mismo tiempo. Se conecta escaneando un QR. → [WhatsApp](/docs/canales/whatsapp)

**Cuenta matriz / subcuenta** — Modelo para agencias: una cuenta matriz administra a varios clientes, cada uno en su subcuenta. → [Agencias](/docs/cuenta/agencias)

### E–L

**Escalamiento (regla de)** — Regla que detecta una situación y entrega la conversación a una persona, con o sin pausar la IA. → [Relevo humano](/docs/agente/relevo-humano)

**Etapa** — Punto del recorrido de venta en que está una conversación: nuevo lead, interesado, negociación, vendido, etc. → [Etiquetas y etapas](/docs/atencion/etiquetas-y-etapas)

**Etiqueta** — Marca que clasifica a un contacto («VIP», «cotizado»). Se administran en un catálogo; la IA solo usa las que tú le autorices. → [Etiquetas y etapas](/docs/atencion/etiquetas-y-etapas)

**Flujo** — Conjunto de reglas «Cuando → Hacer» que se ejecutan solas. → [Flujos](/docs/flujos/introduccion)

**IA Global** — Interruptor general del agente. Apagado, ningún cliente recibe respuesta automática. → [Relevo humano](/docs/agente/relevo-humano)

**Inventario** — Catálogo de productos y servicios, con precio, existencias, fotos y videos, que el agente consulta, recomienda y cotiza. → [Inventario](/docs/conocimiento/inventario)

### M–R

**Meta** — La empresa dueña de WhatsApp, Instagram y Messenger. Sus reglas (ventana de 24 horas, plantillas, calidad del número) rigen esos canales. → [Reglas de WhatsApp](/docs/canales/reglas-de-whatsapp)

**ORCA** — Calificación automática de la calidad de un lead, de 0 a 100, que aparece en el panel del cliente como Tier A, B, C o D. Combina cuatro dimensiones: Objetivo, Ritmo, Compatibilidad y Afinidad. Es una estimación, no un dato que captura el cliente. → [Etiquetas y etapas](/docs/atencion/etiquetas-y-etapas)

**Oportunidad (deal)** — Posible venta con valor, etapa y responsable, separada de la conversación. Un contacto puede tener varias. → [Oportunidades](/docs/atencion/oportunidades)

**Orki** — El asistente de Orkestal que te ayuda a instalar y operar tu cuenta. → [Orki](/docs/empezar/orki)

**Plantilla (de WhatsApp)** — Mensaje con formato fijo que Meta debe aprobar. Es la única forma de escribirle a un cliente fuera de la ventana de 24 horas. → [Plantillas](/docs/campanas/plantillas)

**Funnel de ventas (playbook)** — Guion de pasos que el agente sigue en una conversación comercial (qué preguntar primero, cómo cerrar). Es un complemento de pago. → [Funnel de ventas](/docs/agente/playbook-de-ventas)

**RAG** — Técnica con la que el agente busca fragmentos relevantes de tu base de conocimiento antes de contestar. Es lo que hace la Base de Conocimiento.

### S–Z

**Relevo humano** — El momento en que una persona toma una conversación. Pausa la IA en ese chat para que no escriba encima. → [Relevo humano](/docs/agente/relevo-humano)

**Simulador** — Canal de prueba dentro de Conversaciones para hablar con tu agente como si fueras un cliente. → [Simulador](/docs/agente/simulador)

**Ventana de 24 horas** — Regla de WhatsApp: solo puedes escribir libremente a un cliente durante las 24 horas posteriores a su último mensaje. Después, únicamente con una plantilla aprobada. Si el cliente llegó desde un anuncio de Click-to-WhatsApp, la ventana es de 72 horas. → [Reglas de WhatsApp](/docs/canales/reglas-de-whatsapp)

**WABA** — WhatsApp Business Account. La cuenta de WhatsApp Business en Meta a la que pertenece tu número.

**Webhook** — Aviso automático que un sistema manda a una dirección web cuando pasa algo. Orkestal puede mandarlos (desde un flujo) y recibirlos (la API pública). → [Webhooks](/docs/api/webhooks)


# Canales


## Canales, resumen

> Qué canales puedes conectar, cuántos incluye tu plan, qué cuesta un canal adicional y cómo se desconecta uno.
Fuente: https://orkestaliq.com/docs/canales/resumen

Un **canal** es cada servicio de mensajería por el que te escriben tus clientes. Todas las conversaciones, vengan del canal que vengan, llegan a la misma bandeja en **Conversaciones**. Los canales se administran en **Canales** (disponible para Manager y Admin).

### Canales disponibles

| Canal | Cómo se conecta | Guía |
| --- | --- | --- |
| WhatsApp Business | Escaneando un QR con la app de WhatsApp Business (Coexistencia), o con credenciales de Meta (modo avanzado) | [WhatsApp](/docs/canales/whatsapp) |
| Instagram Direct | Iniciando sesión con tu cuenta profesional de Instagram | [Instagram y Messenger](/docs/canales/instagram-y-messenger) |
| Facebook Messenger | Iniciando sesión con Facebook y eligiendo tu Página | [Instagram y Messenger](/docs/canales/instagram-y-messenger) |
| Telegram | Con el token de tu bot de Telegram | [Telegram](/docs/canales/telegram) |

En la pantalla de Canales verás además otros servicios marcados como **Próximamente** (por ejemplo TikTok, correo o LinkedIn). Todavía no se pueden usar.

> [!NOTA]
> El **Simulador** de Conversaciones es un canal interno de prueba, no cuenta como canal conectado ni consume mensajes de WhatsApp. Mira [Simulador](/docs/agente/simulador).

### Una cuenta por canal

Solo puedes tener **una cuenta conectada por canal**: un WhatsApp, un Instagram, una Página de Messenger y un bot de Telegram. Para usar otra cuenta del mismo canal, desconecta primero la actual con el botón **Desconectar**. Orkestal te lo explica con este aviso: *«Solo puedes tener una cuenta conectada por canal. Para usar otra, desconecta esta primero.»*

Al desconectar:

- Orkestal **deja de recibir y enviar** mensajes por esa cuenta.
- **Tus conversaciones anteriores se conservan.**
- Se elimina el token de acceso guardado.

Si el canal es WhatsApp conectado por QR, además conviene desvincularlo desde la propia app. Mira [WhatsApp: desconectar](/docs/canales/whatsapp#desconectar-un-numero).

### Cuántos canales incluye tu plan

Cada plan incluye un número de canales. El plan **Starter** incluye **1**. Cuando ya usaste todos los incluidos y conectas otro, Orkestal te muestra el **cargo por canal adicional** antes de continuar y te pide que lo aceptes:

- **$15 USD (o $299 MXN) al mes** por cada canal adicional.
- Se **prorratea** en tu siguiente factura.
- Si lo desconectas, **se te acredita** la parte no usada.

El monto exacto que se cobra sale de Stripe en tu moneda. Más sobre planes en [Planes y facturación](/docs/cuenta/planes-y-facturacion).

### El chat de tu sitio web

Orkestal cuenta con un chat web propio, pero **hoy no se activa desde el panel de Canales**. Si quieres uno en tu sitio, escríbenos a soporte@orkestaliq.com.

### Si un canal deja de funcionar

- **Un canal activo no recibe mensajes**: revisa que el canal esté activado en Canales y, en WhatsApp, atiende los avisos de recepción que aparecen en rojo arriba del panel. Mira [Solución de problemas](/docs/ayuda/solucion-de-problemas).
- **Meta retiró el acceso** (por ejemplo, lo quitaste desde la configuración de Instagram o Facebook): Orkestal lo detecta, elimina el token y desactiva el canal. Para volver, conéctalo otra vez.


## WhatsApp

> Cómo conectar tu número de WhatsApp Business escaneando un QR, qué cambia al hacerlo, y cómo desconectarlo o reactivar la recepción.
Fuente: https://orkestaliq.com/docs/canales/whatsapp

La forma recomendada de conectar WhatsApp es la **Coexistencia**: escaneas un código QR y tu número **sigue funcionando en la app de WhatsApp Business de tu celular y, al mismo tiempo, en Orkestal**. No tienes que soltar tu teléfono ni migrar tus chats.

Hay también una [conexión manual](#conexion-manual-avanzada) para quien administra su propia app de Meta.

### Antes de conectar

Meta revisa estos puntos mientras escaneas el QR. Si alguno falla, **la ventana se cierra sin explicar por qué** y hay que empezar de nuevo. Por eso Orkestal te pide confirmarlos antes de habilitar el botón.

1. **La app de WhatsApp Business en la versión 2.24.17 o más nueva.** Es el mínimo que exige Meta. Revísalo en el celular: WhatsApp Business → Configuración → Ayuda → Información de la aplicación. Si es más vieja, actualízala desde la tienda de aplicaciones.
2. **El número ya debe estar en uso en la app.** La Coexistencia conecta un número que ya usas en WhatsApp Business, con sus chats. Los números recién dados de alta, o con la app recién instalada, son el motivo más común de rechazo: déjalos trabajando algunos días antes de conectarlos.
3. **Pon tu foto de perfil y los datos del negocio antes de conectar.** Después de conectar solo se editan desde la app, no desde Orkestal.
4. **Identifica la cuenta de Meta correcta.** Inicia sesión con la persona que tiene **control total del Business Portfolio** (portafolio de negocio) que posee ese WhatsApp. Que esa persona administre varias empresas no es problema: eliges el portafolio correcto dentro del flujo. Cambiar de perfil o de Página de Facebook no concede acceso al WABA.

También ten en cuenta:

- **Un solo número por cuenta de Orkestal** en Coexistencia.
- **No desinstales ni reinstales WhatsApp Business.** Para Meta, reinstalar la app es motivo de desconexión y tendrías que repetir todo el proceso.
- **Deja la app abierta y el celular desbloqueado** mientras sincroniza. El código QR caduca en segundos.

### Conectar paso a paso

1. Ve a **Canales** y busca la tarjeta de **WhatsApp Business**.
2. En el bloque **Coexistencia**, marca las casillas de confirmación.
3. Si tu plan ya usó todos sus canales incluidos, acepta el cargo por [canal adicional](/docs/canales/resumen#cuantos-canales-incluye-tu-plan).
4. Pulsa **Conectar por QR**. Se abre el inicio de sesión de Meta. No se te pedirán WABA ID, Business ID ni tokens.
5. Inicia sesión, elige el portafolio de negocio y la cuenta de WhatsApp, y **escanea el QR** con tu app de WhatsApp Business.
6. Cuando termina, Orkestal te avisa que el número quedó conectado y empieza a **sincronizar tus contactos e historial**.

> [!NOTA]
> Si tienes un bloqueador de anuncios o una extensión de privacidad, puede impedir que cargue el inicio de sesión de Meta. Permite orkestaliq.com o abre una ventana privada y recarga.

### Después de conectar

#### Agrega un método de pago en WhatsApp Manager

Tu número queda conectado y **ya recibes mensajes**, pero para poder **enviarlos** Meta necesita un método de pago en tu cuenta de WhatsApp Business. Es tu propia cuenta y solo tú puedes agregarlo. El aviso de Orkestal incluye un botón directo a WhatsApp Manager y desaparece solo cuando lo agregas.

#### Historial y contactos

Orkestal sincroniza tus contactos y el historial de conversaciones individuales de la app (hasta 180 días, por fases y una sola vez). Los chats de grupo **no** se sincronizan.

#### Lo que escribes desde el celular también aparece

Los mensajes que envías desde la app de WhatsApp Business quedan registrados en la conversación de Orkestal. Si respondes a mano un chat, la IA se pausa en él: mira [Relevo humano](/docs/agente/relevo-humano).

### Qué cambia en tu WhatsApp al conectar

- El número queda con un límite fijo de **20 mensajes por segundo**.
- Las **listas de difusión** se desactivan; las que ya tenías quedan de solo lectura.
- En chats individuales se apagan los **mensajes temporales**, «ver una vez» y la **ubicación en tiempo real**.
- Los **chats de grupo** no se sincronizan: siguen viviendo solo en tu app.
- **WhatsApp para Windows y para WearOS** no funcionan con Coexistencia, y los dispositivos vinculados «companion» se desvinculan al conectar.
- Por la API tampoco hay llamadas, catálogo, estados ni canales.

### Mantén activa tu app

Meta puede **desconectar números de Coexistencia inactivos**. Abre la app de WhatsApp Business al menos cada 14 días. Orkestal te avisa en el panel cuando no ha visto actividad reciente de WhatsApp Business: abre la app y úsala ese día.

### Desconectar un número

Desconectar en Orkestal detiene el envío y la recepción, pero para **quitar el vínculo por completo** hazlo también desde el celular:

1. En **Canales**, pulsa **Desconectar** en la tarjeta de WhatsApp y confirma. Tus conversaciones se conservan.
2. En WhatsApp Business, abre **Configuración**.
3. Ve a **Cuenta → Business Platform**.
4. Elige **Desconectar** y confirma. Meta avisa a Orkestal, que apaga el canal automáticamente.

> [!CUIDADO]
> **No borres el número desde WhatsApp Manager ni uses «deregister».** Es una baja distinta que puede afectar los datos y el uso futuro del número.

### Si dejas de recibir mensajes

Orkestal vigila la recepción de tu número y muestra un aviso arriba del panel cuando detecta un problema:

| Aviso | Qué significa | Qué hacer |
| --- | --- | --- |
| WhatsApp no está recibiendo mensajes | Meta dejó de entregarle a Orkestal los mensajes de tu número | Pulsa **Reactivar recepción**; suele resolverse en segundos |
| Los mensajes se están enviando a otro sistema | Meta manda tus mensajes a otra dirección | Reactiva la recepción; si el aviso vuelve, revisa el diagnóstico en Configuración → WhatsApp |
| WhatsApp perdió su autorización | Meta ya no acepta la autorización guardada: no entran ni salen mensajes | **Reconectar WhatsApp** |
| Lleva demasiado tiempo sin recibir mensajes | Tu número recibe mensajes a diario y lleva mucho más de lo normal sin ninguno | Si tus clientes sí te escriben, reactiva la recepción |

Después de reactivar, manda un mensaje de prueba a tu número para confirmar.

### Quién responde en WhatsApp

En **Configuración → WhatsApp → Quién responde en WhatsApp** eliges el modo del canal:

- **Agente Orkestal**: la IA de Orkestal contesta (lo normal).
- **Agente externo (n8n o webhook)**: tu propio sistema genera las respuestas. Mira [Agente externo](/docs/integraciones/agente-externo).
- **Solo atención humana**: nadie contesta automáticamente; tu equipo atiende desde la bandeja.

### Conexión manual (avanzada)

Si administras tu propia app de Meta, puedes conectar con credenciales en lugar del QR. En **Canales → WhatsApp Business → Conexión manual (avanzado)** necesitas:

| Campo | De dónde sale |
| --- | --- |
| Phone Number ID | WhatsApp Manager, configuración de la API |
| WhatsApp Business Account ID (WABA ID) | **WhatsApp Manager → Configuración de la API.** No es el ID del portafolio de negocio de Business Manager: con ese, los mensajes funcionan pero las plantillas no se sincronizan |
| Permanent Access Token | Un token permanente de un usuario de sistema (System User) en Business Settings, con los permisos de WhatsApp |
| Webhook Verify Token | Un valor que tú eliges |

Después pega la **Callback URL** y el **Verify Token** que muestra Orkestal en la configuración de Webhooks de tu app de Meta (producto WhatsApp).

> [!IMPORTANTE]
> Este modo es para quien ya conoce Meta for Developers. Si tu número ya vive en la app de WhatsApp Business, usa la Coexistencia por QR.

### Dudas frecuentes

**¿Puedo seguir contestando desde mi celular?** Sí, ese es el objetivo de la Coexistencia.

**¿Pierdo mis chats?** No. Tus chats individuales siguen en la app y se sincronizan a Orkestal.

**¿Puedo conectar dos números?** No en la misma cuenta: Orkestal admite **una cuenta por canal**, o sea un número de WhatsApp. Para cambiar de número, desconecta el actual y conecta el otro. Mira [Canales, resumen](/docs/canales/resumen#una-cuenta-por-canal).

**¿Por qué no puedo escribirle a un cliente?** Seguramente pasaron más de 24 horas desde su último mensaje. Mira [Reglas de WhatsApp](/docs/canales/reglas-de-whatsapp).


## Reglas de WhatsApp que conviene conocer

> La ventana de 24 horas, los mensajes gratis, la calidad de tu número y qué significa cada error de entrega.
Fuente: https://orkestaliq.com/docs/canales/reglas-de-whatsapp

Estas reglas las pone **Meta**, no Orkestal. Conocerlas evita la mayoría de los «mi mensaje no salió».

### La ventana de 24 horas

Solo puedes escribirle a un cliente con **texto libre** durante las **24 horas siguientes a su último mensaje**. Pasado ese tiempo, WhatsApp únicamente entrega **plantillas aprobadas** por Meta.

| Situación | Ventana |
| --- | --- |
| El cliente te escribió por su cuenta | 24 horas desde su último mensaje |
| El cliente llegó desde un anuncio de Click-to-WhatsApp o desde el botón de tu Página de Facebook | 72 horas desde ese momento |

La ventana de 72 horas **no sustituye** a la de 24: la extiende. Rige la que termine más tarde.

Dentro de Orkestal:

- Cuando la ventana está por cerrar, el chat te avisa cuánto falta («La ventana cierra en X h Y min. Después solo podrás escribirle con una plantilla.»).
- Cuando ya cerró, el campo de mensaje te indica que solo puedes retomar la conversación con una plantilla aprobada. Usa el botón **Enviar plantilla aprobada** del chat. Mira [Plantillas](/docs/campanas/plantillas).
- El agente de IA contesta a los mensajes que el cliente acaba de mandar, así que sus respuestas caen dentro de la ventana. Lo que queda fuera de ella son los mensajes que **inicia** tu negocio: seguimientos, recordatorios y campañas.

> [!IMPORTANTE]
> Los recordatorios que se mandan horas antes de una cita casi siempre caen **fuera** de la ventana. Por eso un flujo «Antes de una cita» debe usar una **plantilla aprobada**, no un mensaje libre. Mira [Flujos: recetas](/docs/flujos/recetas).

### Mensajes gratis cada mes

Desde el 1 de octubre de 2026, Meta incluye una bolsa mensual de mensajes de servicio gratuitos por cuenta de WhatsApp Business: **los primeros 1,000 del mes**. A partir del 1,001, Meta cobra cada mensaje que escribas dentro de la ventana de 24 horas.

- Los chats que **entran por un anuncio** abren una ventana de 72 horas y **no consumen** esa bolsa.
- Las **plantillas** y las **campañas** no consumen la bolsa: se cobran por mensaje, según su categoría y el país, directamente por Meta.
- El contador se **reinicia el día 1** de cada mes.
- En el panel verás avisos cuando llevas **80 %, 95 % y 100 %** de la bolsa.

> [!NOTA]
> El conteo de Orkestal es una **estimación de lo que Orkestal envió**. La cifra que factura Meta es la de WhatsApp Manager. Consulta las tarifas vigentes en la documentación de Meta.

### Calidad de tu número

Meta califica la salud de tu número según los bloqueos, reportes de spam y quejas de tus contactos en los últimos 7 días. Orkestal lo muestra como un semáforo en **Campañas**:

| Semáforo | Qué significa | Efecto en campañas |
| --- | --- | --- |
| Verde, calidad alta | Todo funciona normal | Puedes enviar |
| Amarillo, calidad media | Meta detectó riesgo de calidad | **Envíos bloqueados**, incluidas las campañas ya programadas |
| Rojo, calidad baja | El número no puede usar campañas hasta recuperar calidad | **Envíos bloqueados** |
| Sin dato reciente | Orkestal no ha sincronizado la calidad | Sincroniza antes de un envío importante |

El bloqueo se levanta solo cuando Meta vuelve a marcar el número en verde. Los administradores reciben un aviso.

La etiqueta junto al semáforo (por ejemplo «hasta 1,000/24h») es el **límite de conversaciones que tu negocio puede iniciar cada 24 horas**. Los niveles son 50, 250, 1,000, 10,000, 100,000 o sin límite. Los números nuevos, o con el portafolio de negocio sin verificar, arrancan en los niveles más bajos; verificar tu negocio y mantener buena calidad hace que Meta los suba.

### Estado de entrega de cada mensaje

Junto a cada mensaje que sale verás su estado:

| Estado | Significado |
| --- | --- |
| Enviando | Orkestal lo está mandando |
| Enviado | Meta lo aceptó |
| Entregado | Llegó al teléfono del cliente |
| Leído | El cliente lo abrió |
| No se pudo entregar | WhatsApp lo rechazó; el chat muestra el motivo |
| No se pudo confirmar | Orkestal no recibió confirmación de que saliera; si no lo ves en el teléfono del cliente, vuelve a enviarlo |

### Errores de entrega más comunes

| Código | Qué pasó | Qué hacer |
| --- | --- | --- |
| 131047 | Pasaron más de 24 horas desde el último mensaje del cliente | Envía una plantilla aprobada |
| 131026 | El número no tiene WhatsApp, o el cliente no puede recibir mensajes de empresas (versión desactualizada, no aceptó los términos o te bloqueó) | Confirma el número; si es correcto, no hay nada que hacer desde tu lado |
| 133010 | El número de WhatsApp de tu negocio no está registrado | Reconéctalo en Canales |
| 131049 | Meta limitó este mensaje de marketing para proteger la experiencia del cliente | Intenta más tarde o espera a que responda |
| 131048 | Meta frenó el envío por una tasa alta de reportes de spam en tu número | Revisa la calidad de tu número y el contenido de tus mensajes |
| 131056 | Mandaste demasiados mensajes seguidos a este contacto | Espera un momento y reintenta |
| 130429 | Tu cuenta alcanzó el límite de velocidad de envío | Reintenta en unos minutos |
| 131051 | WhatsApp no admite este tipo de mensaje o archivo | Cambia el formato |
| 131053 | WhatsApp no pudo procesar el archivo adjunto | Revisa formato y tamaño |
| 131031 | La cuenta de WhatsApp Business está bloqueada o restringida por Meta | Revisa tu cuenta en WhatsApp Manager |
| 131009 | WhatsApp rechazó el mensaje por un dato inválido | Revisa el contenido |
| 190 | La conexión con WhatsApp venció | Reconecta el canal |
| 132000 | Hay un problema con la plantilla (variables o estado) | Revisa la plantilla en Campañas → Plantillas |

### Bajas voluntarias

Los contactos que responden **STOP**, **BAJA** o **CANCELAR** a un mensaje masivo se **excluyen automáticamente** de la audiencia de tus campañas. Mira [Campañas](/docs/campanas/campanas).

### Tipos de archivo

WhatsApp no acepta cualquier archivo. Para enviar a un cliente desde Orkestal, el límite en el chat es de **15 MB por archivo**. En los [flujos](/docs/flujos/hacer), «Enviar archivo» admite imágenes JPG o PNG de hasta 5 MB, y videos MP4 o 3GP y documentos de hasta 14 MB.


## Instagram y Messenger

> Conecta los mensajes directos de Instagram y los de tu Página de Facebook iniciando sesión con Meta, sin copiar tokens.
Fuente: https://orkestaliq.com/docs/canales/instagram-y-messenger

Instagram Direct y Facebook Messenger se conectan iniciando sesión con Meta. **No tienes que copiar tokens** ni crear una app. Una vez conectados, los mensajes llegan a la misma bandeja que WhatsApp y el agente de IA puede contestarlos igual.

Ambos están en **Canales** (disponible para Manager y Admin).

### Instagram Direct

#### Requisitos

- Una cuenta **profesional** de Instagram (de tipo **Empresa** o **Creador**). Las cuentas personales no pueden conectarse.
- No necesitas una Página de Facebook.
- Acceso a esa cuenta para iniciar sesión y aceptar los permisos.

#### Conectar

1. En **Canales**, en la tarjeta de **Instagram Direct**, pulsa **Conectar con Instagram**.
2. Se abre Instagram. Inicia sesión con tu cuenta profesional.
3. **Acepta todos los permisos** que pide. Si rechazas alguno, la conexión falla.
4. Vuelves a Orkestal con el aviso «¡Instagram conectado!». Los mensajes directos de tu cuenta ya llegan a tu bandeja.

Si aparece «No se pudo conectar Instagram», inténtalo de nuevo y asegúrate de aceptar todos los permisos.

### Facebook Messenger

#### Requisitos

- Una **Página de Facebook** de la que seas administrador.
- Acceso a la cuenta de Facebook que administra esa Página.

#### Conectar

1. En la tarjeta de **Facebook Messenger**, pulsa **Conectar con Facebook**.
2. Inicia sesión con Facebook y elige la **Página** cuyos mensajes quieres atender desde Orkestal.
3. Orkestal confirma con «¡Messenger conectado con (nombre de tu Página)!».

Si autorizaste **varias Páginas**, Orkestal te pide elegir cuál conectar y Facebook se abre otra vez para confirmar. Recuerda que solo se conecta **una Página por cuenta de Orkestal**.

### Qué datos recibe Orkestal

Solo se accede a las cuentas y Páginas que **tú seleccionas** en el cuadro de autorización de Meta. De las personas que te escriben, Orkestal recibe sus mensajes y archivos, su identificador en la plataforma y su nombre o nombre de usuario público. Esos datos se usan únicamente para mostrar tus conversaciones, enviar las respuestas de tu equipo o de tu agente de IA, y mantener la conexión activa. El detalle completo está en el [aviso de privacidad](/privacy) y en [Seguridad y privacidad](/docs/cuenta/seguridad-y-privacidad).

### Desconectar o cambiar de cuenta

- **Desde Orkestal:** pulsa **Desconectar** en la tarjeta del canal. Se elimina de inmediato el token de acceso y se dejan de recibir y enviar mensajes. Tus conversaciones anteriores se conservan.
- **Desde Meta:** si quitas el acceso de Orkestal en la configuración de Instagram o de Facebook, Meta nos avisa y Orkestal elimina el token y desactiva el canal automáticamente.

Para usar otra cuenta del mismo canal, desconecta primero la actual: solo hay [una cuenta por canal](/docs/canales/resumen#una-cuenta-por-canal).

### Conexión manual

Para quien administra su propia app de Meta, cada tarjeta ofrece una opción de conexión manual con tokens. Para Instagram necesitas el **Access Token**; el ID de tu cuenta de Instagram se detecta solo a partir del ID de tu Página. Para Messenger necesitas el **Page Access Token** y un **Verify Token** que tú eliges. Si no administras tu propia app de Meta, usa el inicio de sesión.

### Si algo falla

| Síntoma | Qué revisar |
| --- | --- |
| «No se pudo conectar Instagram» | Que la cuenta sea Empresa o Creador y que aceptaste todos los permisos |
| «Messenger todavía no está configurado en el servidor» | Escribe a soporte@orkestaliq.com |
| Dejaron de llegar mensajes | Que el canal siga activo en Canales y que no hayas quitado el acceso de Orkestal desde Meta; si lo quitaste, vuelve a conectar |
| El agente no contesta en el canal | Mira [Solución de problemas](/docs/ayuda/solucion-de-problemas) |


## Telegram

> Conecta un bot de Telegram para atender clientes o para recibir avisos internos de tu equipo.
Fuente: https://orkestaliq.com/docs/canales/telegram

Telegram se conecta con un **bot** que tú creas. Orkestal puede usarlo de dos maneras, que se combinan:

- **Comunicación con clientes**: tus clientes escriben al bot y el agente de IA o tu equipo les contestan desde la bandeja.
- **Notificaciones internas**: el bot manda avisos a un grupo o a una persona de tu equipo, por ejemplo cuando un cliente pide hablar con una persona.

### Crear tu bot

1. En Telegram, abre una conversación con **@BotFather**.
2. Escribe `/newbot` y sigue las instrucciones para ponerle nombre y usuario.
3. @BotFather te entrega el **token** del bot, con un formato parecido a `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`. Cópialo.

> [!CUIDADO]
> El token da control total del bot. No lo compartas en chats ni en capturas de pantalla. Si se expone, genera uno nuevo con @BotFather y actualízalo en Orkestal.

### Conectar en Orkestal

1. Ve a **Canales** y abre la tarjeta de **Telegram**.
2. Completa los campos:

| Campo | Qué poner |
| --- | --- |
| Bot Token | El token que te dio @BotFather |
| Bot Name | El nombre de usuario del bot, por ejemplo `@mi_negocio_bot` |
| Modo de uso | **Comunicación con clientes**, **Solo notificaciones internas** o **Ambos** |
| Chat ID de Notificaciones | El ID del grupo o persona que recibirá los avisos. Es obligatorio si el modo incluye notificaciones |

3. Guarda. Orkestal registra el webhook de tu bot automáticamente y confirma con «Telegram credentials configured & webhook registered».

### Obtener el Chat ID de notificaciones

El Chat ID identifica **dónde** llegan los avisos. Para un grupo, agrega tu bot al grupo y obtén el ID con cualquier bot de utilidad de Telegram o con la API de Telegram (`getUpdates`). Para una persona, esa persona debe haber iniciado una conversación con el bot.

### Qué avisos llegan a Telegram

- Las alertas de **«Requiere humano»**: cuando una regla de escalamiento entrega una conversación a tu equipo.
- Los avisos de los flujos que usan la acción **Notificar por Telegram**. Si el aviso lo dispara «Se agendó una cita», incluye la fecha y hora de la cita. Mira [Flujos: acciones](/docs/flujos/hacer).

Ambos usan **el mismo chat** configurado aquí, salvo que un flujo indique otro. Un flujo con «Notificar por Telegram» no se puede guardar si Telegram no está en modo **Notificaciones** o **Ambos** con un Chat ID.

### Campañas por Telegram

Las campañas masivas también pueden salir por Telegram: el envío es inmediato y no tiene costo por mensaje. Mira [Campañas](/docs/campanas/campanas).

### Desconectar

Pulsa **Desconectar** en la tarjeta de Telegram. Orkestal deja de recibir y enviar por ese bot; tus conversaciones se conservan.


# Tu agente de IA


## Perfil y estilo del agente

> Cómo definir el nombre, el estilo de lenguaje, el objetivo, el horario de atención y los demás ajustes de la pantalla Agente IA.
Fuente: https://orkestaliq.com/docs/agente/perfil-y-estilo

La pantalla **Agente IA** (disponible para Manager y Admin) define **quién es** tu agente y **cómo habla**. Los cambios se aplican con el botón **Guardar cambios**. Arriba verás una barra de **Progreso de configuración** y a un lado una **vista previa** de cómo saludaría el agente con tu configuración.

> [!NOTA]
> Si el botón avisa «tu usuario no tiene permiso para editar el agente de este negocio», pide a un administrador de la cuenta que haga el cambio.

### Identidad y personalidad

| Ajuste | Qué hace |
| --- | --- |
| **Nombre del agente** | Cómo se presenta con tus clientes |
| **Nombre del negocio** | A qué negocio representa. Aparece en sus saludos |
| **Estilo de lenguaje** | El tono con el que escribe (ver abajo) |
| **Objetivo de conversión (CTA principal)** | La acción concreta a la que el agente lleva al cliente cuando la conversación es comercial: «Agendar una llamada», «Solicitar cotización», «Comprar el curso». No aplica en post-venta, quejas ni soporte |

> [!CONSEJO]
> Un objetivo específico mantiene la conversación enfocada y ayuda al agente a resolver mejor las dudas. «Agendar una visita» funciona mejor que «Vender más».

### Estilo de lenguaje

Cada estilo combina un tono de escritura con una técnica de cierre de ventas:

| Estilo | Cómo suena | Cierre asociado |
| --- | --- | --- |
| **Natural y conversacional** | Chat humano: emojis moderados, frases cortas y giros coloquiales | Cierre natural (amigo) |
| **Formal y profesional** | Corporativo: gramática impecable, trato de usted, sin emojis y vocabulario preciso | Cierre ejecutivo (asesor senior) |
| **Técnico y preciso** | Datos primero: términos exactos, listas y viñetas, sin relleno emocional | Cierre basado en datos |
| **Cálido y empático** | Consejero de confianza: emojis expresivos, reconoce emociones y apoyo genuino | Cierre empático |
| **Breve y directo** | Al grano: máximo 2 oraciones, cero relleno, sin emojis | Cierre telegráfico |
| **Casual y amigable** | Amiga que sabe del tema: humor seco, slang casual, anti-bot extremo, sin listas | Cierre directo |

#### «Escribe como tu equipo» (estilo aprendido)

Además de los estilos predefinidos, Orkestal puede medir **cómo escribe de verdad tu equipo** y pedirle al agente que lo imite: el largo de los mensajes, si abren las preguntas con «¿», cómo cierran, si tutean o hablan de usted, qué emojis usan y las frases que repiten.

- Se calcula con los mensajes que tu equipo ya mandó: desde la bandeja, desde el celular (Coexistencia) o del historial importado.
- Necesita una muestra mínima: **al menos 30 mensajes de tu equipo en 5 chats distintos**. Con menos, los porcentajes serían ruido. Mientras tanto el agente usa el estilo «Natural y conversacional».
- La tarjeta **Así escribes tú** muestra, número por número, qué midió.
- No se envían conversaciones de clientes a ningún proveedor para calcularlo, y **no se guardan mensajes completos**: solo estadísticas y frases que se repiten en varios chats (saludos, cierres, muletillas).
- Después de elegirlo, pulsa **Guardar** para que el agente empiece a usarlo.

### Comunicación

| Ajuste | Qué hace |
| --- | --- |
| **¿Mencionar que es un bot?** | Si está activo, el agente aclara que es una IA cuando se lo preguntan |
| **Longitud de los mensajes** | De «más cortos de lo normal» a «más largos de lo normal» |
| **Emojis permitidos** | Una lista de emojis que puede usar. Déjala vacía para elección libre |
| **Uso de jerga o slang** | Entre jerga local del país y cero jerga (formal) |
| **Tiempo de espera antes de contestar** | Cuánto espera el agente tras el último mensaje del cliente antes de empezar a redactar, hasta 120 segundos. **No es el tiempo total**: generar el mensaje puede sumar algunos segundos. Es útil si tus clientes suelen escribir en varios mensajes cortos |

### Horario de atención

Por defecto la IA contesta las **24 horas**. Si activas el **Horario de atención**:

1. Elige tu **zona horaria**.
2. Para cada día de la semana, activa o desactiva el día y define la hora de inicio y fin.
3. Opcionalmente escribe un **mensaje de fuera de horario**, por ejemplo: «¡Gracias por escribirnos! Nuestro horario es de 7:00 a 21:00. Te respondemos en cuanto abramos.»

Cómo funciona:

- **Fuera de horario la IA no contesta automáticamente.** Los mensajes siguen llegando a la bandeja y tu equipo puede responder a mano: lo único que se apaga es la respuesta automática.
- El mensaje de fuera de horario se envía **una sola vez por conversación**, no en cada mensaje del cliente.
- Si lo dejas vacío, la IA simplemente no responde nada fuera de horario.

> [!NOTA]
> Este horario controla cuándo contesta la IA. No es el horario que usa Google Calendar para ofrecer citas; ese se explica en [Google Calendar](/docs/integraciones/google-calendar).

### Reglas de escalamiento y reanudación

En la misma pantalla se definen las **reglas de escalamiento** y cuánto tiempo pasa antes de que la IA retome un chat que tu equipo atendió a mano. Eso tiene su propia guía: [Relevo humano](/docs/agente/relevo-humano).

### Links inteligentes

Al final de la pantalla está la sección **Avanzado · Links inteligentes**, para que el agente comparta enlaces (catálogo, portafolio, precios) cuando el cliente pregunta por ese tema. Mira [Links inteligentes](/docs/agente/links-inteligentes).

### Buenas prácticas

- **Objetivo claro y medible**: una sola acción principal.
- **Tono consistente**: elige el estilo que ya usa tu equipo, o déjalo aprender el tuyo.
- **Mensajes concisos y útiles**: sube la longitud solo si tu negocio vende algo que requiere explicación.
- **Escalamiento definido**: antes de encender la IA, decide en qué situaciones entra una persona.
- Después de cada cambio, **pruébalo en el [simulador](/docs/agente/simulador)**.


## Clave de IA (tu proveedor de inteligencia artificial)

> Cómo conectar tu cuenta de OpenAI o Google Gemini, cuánto cuesta y qué pasa si falta la clave.
Fuente: https://orkestaliq.com/docs/agente/clave-de-ia

Tu agente "piensa" con un modelo de lenguaje de un proveedor de IA. Orkestal **no incluye ese consumo**: usas **tu propia cuenta** con el proveedor, y él te cobra directamente según el uso. A esa credencial se le llama **clave de API** (API key).

### Proveedores disponibles

| Proveedor | Dónde obtener la clave | Cómo se ve |
| --- | --- | --- |
| **OpenAI** (recomendado) | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) | Empieza con `sk-proj-` |
| **Google Gemini** | [Google AI Studio](https://aistudio.google.com/apikey) | Empieza con `AIzaSy` |

### Conectar tu clave

1. Abre **Configuración** (solo administradores).
2. En **Proveedor de IA**, elige OpenAI o Google Gemini.
3. Pega tu clave.
4. Pulsa **Guardar Credenciales**. Orkestal confirma con «Proveedor de IA configurado con éxito».

También puedes pedirle a [Orki](/docs/empezar/orki) que la solicite: abre un campo seguro y enmascarado, y Orki nunca ve el valor.

> [!CUIDADO]
> Nunca pegues tu clave en una conversación con Orki, con un cliente ni en un correo. Lo que se escribe en un chat queda guardado en su historial.

### Cuánto cuesta

El costo depende de cuántas conversaciones atiendas y del modelo que uses. Orkestal no cobra ese consumo: lo cobra tu proveedor. Para controlar el gasto:

- **Pon un límite de gasto** en la cuenta de tu proveedor (OpenAI y Google lo permiten).
- Revisa el consumo en el panel de tu proveedor, no en Orkestal. Orkestal verifica que haya una clave configurada, **no su saldo**.

### Seguridad de tu clave

Las claves que configuras se almacenan **cifradas** y se usan únicamente para procesar los mensajes de **tu propia cuenta**. Mira [Seguridad y privacidad](/docs/cuenta/seguridad-y-privacidad).

### Qué pasa si falta la clave

- El panel muestra el aviso **«Tu agente de IA no está activo»** con un botón **Configurar API Key**.
- El agente **no contesta** a tus clientes; en el chat solo queda un aviso interno.
- Los documentos que subas a la [base de conocimiento](/docs/conocimiento/base-de-conocimiento) quedan en estado **«Falta clave de IA»** hasta que la configures; al guardar la clave, Orkestal reprocesa la base de conocimiento pendiente.

### Si cambias de clave o de proveedor

Basta con guardar la nueva en **Configuración**. Si rotaste o revocaste la clave anterior en tu proveedor, el agente deja de contestar hasta que guardes la nueva.

### Problemas comunes

| Síntoma | Causa probable |
| --- | --- |
| El agente no contesta y el aviso de clave no aparece | La clave existe pero tu proveedor la rechaza: saldo agotado, límite de gasto alcanzado, o clave revocada. Revísalo en el panel de tu proveedor |
| Los documentos nuevos se quedan en «Falta clave de IA» | No hay clave guardada. Guárdala en Configuración: Orkestal reprocesa la base de conocimiento pendiente |
| Guardé la clave y sigue sin contestar | Revisa las demás causas en [Solución de problemas](/docs/ayuda/solucion-de-problemas) |


## Relevo humano y reglas de escalamiento

> Cuándo contesta la IA y cuándo una persona, cómo pausar el agente, cómo crear reglas de escalamiento y cómo se reanuda.
Fuente: https://orkestaliq.com/docs/agente/relevo-humano

El principio de Orkestal es sencillo: **la IA nunca debe escribir encima de una persona**. Esta guía explica los cuatro mecanismos que lo logran y cómo se combinan.

### Los cuatro mecanismos

| Mecanismo | Alcance | Quién lo reactiva |
| --- | --- | --- |
| **IA Global** (interruptor) | Todos los chats | Una persona |
| **Pausa por conversación** (botón del chat) | Un chat | Una persona |
| **Pausa automática por respuesta del equipo** | Un chat | La IA retoma sola, o una persona |
| **Regla de escalamiento** | Un chat | Una persona (si la regla pausa la IA) |

#### 1. IA Global

El interruptor **IA Global** de **Conversaciones** enciende o apaga al agente en toda la cuenta. Apagado, **ningún cliente recibe respuesta automática**. Es la forma más rápida de detener todo si algo sale mal. Sirve también como paso final de la instalación: mira [Primeros pasos](/docs/empezar/primeros-pasos).

#### 2. Pausa por conversación

Dentro de un chat, el botón **Pausar IA para este chat** (o **Activar IA para este chat**) controla solo esa conversación. Úsalo cuando quieras atender un caso tú mismo sin apagar todo.

#### 3. Pausa automática cuando tu equipo responde

En cuanto alguien de tu equipo **escribe en un chat**, la IA se pausa en él. Esto incluye las respuestas que mandas **desde tu celular** cuando WhatsApp está conectado por Coexistencia. El chat muestra: *«La IA está en pausa aquí porque el equipo respondió a mano.»*

Para que atender un chat a mano una sola vez no lo deje sin agente para siempre, la IA **retoma sola** el chat cuando tu equipo lleva cierto tiempo sin escribir en él.

- Se configura en **Agente IA** con la frase **«La IA retoma el chat tras [N] horas sin que el equipo vuelva a escribir»**.
- Acepta de **0 a 720 horas**. Si no lo cambias, son **24 horas**.
- Con **0**, la IA **no se reactiva sola**: solo una persona la reactiva desde el chat.
- Siempre puedes reactivarla antes desde el botón de la conversación.

> [!IMPORTANTE]
> La reanudación automática solo levanta pausas que vinieron de **una respuesta manual**. Una pausa puesta con el botón o por una regla de escalamiento es una decisión explícita y solo la revierte una persona.

#### 4. Reglas de escalamiento

Una regla describe una **situación** en lenguaje natural. Cuando el agente detecta que la conversación coincide, ejecuta lo que configuraste en la regla. Se crean en **Agente IA → reglas de escalamiento → Nueva Regla**.

| Campo | Qué hace |
| --- | --- |
| **Nombre de la regla** | Para que la reconozcas. Ej.: «Boda o evento masivo» |
| **Etiqueta a aplicar** | Etiqueta que se le pone al contacto cuando la regla se dispara. Si tu cuenta usa el [modo estricto de etiquetas](/docs/atencion/etiquetas-y-etapas#modo-estricto), eliges de tu catálogo |
| **SI ocurre este escenario (Trigger)** | La situación, en tus palabras. Ej.: «El cliente pide informes para un banquete, boda o evento masivo» |
| **Pausar a la IA** | La IA deja de responder en este chat hasta que se reactive manualmente |
| **Asignar a humano** | Aplica la etiqueta **Requiere humano** al contacto y entrega la conversación a un asesor |
| **Entregar la conversación a** | Aparece con «Asignar a humano»: una persona concreta del equipo, o **cualquier asesor disponible (menor carga)** |
| **Mensaje automático (opcional)** | Un texto fijo que se envía al cliente cuando la regla se dispara |

Si dejas el mensaje automático **vacío**, el agente contesta según el contexto de la conversación (modo Co-Piloto).

**Escribe el trigger como lo diría un cliente.** Entre más concreto, menos falsos positivos: «El cliente pide cotizar más de 50 piezas» funciona mejor que «Pedido grande».

> [!CONSEJO]
> Después de crear o editar una regla, pruébala en el [simulador](/docs/agente/simulador) con frases reales de tus clientes. Una regla demasiado amplia escalará conversaciones que la IA podía resolver.

#### Qué pasa cuando una regla entrega la conversación

1. El contacto recibe la etiqueta (y **Requiere humano**, si activaste «Asignar a humano»).
2. La conversación se asigna a la persona elegida, o se reparte con la [asignación automática](/docs/atencion/equipo-y-roles#asignacion-automatica).
3. Tu equipo recibe una notificación (campana y notificación push) y, si configuraste Telegram, un aviso ahí. Mira [Notificaciones](/docs/atencion/notificaciones).
4. Si activaste «Pausar a la IA», la IA se calla en ese chat hasta que una persona la reactive.

### Otras formas de pasar a una persona

- **Un cliente pide hablar con alguien.** El disparador de flujo **«Solicita humano»** lo detecta. Mira [Flujos: cuándo](/docs/flujos/cuando).
- **Desde un flujo** con la acción **Escalar a humano** o **Transferir a agente**. Ojo: *Escalar a humano* en un flujo genera un resumen y evita una respuesta duplicada **en ese turno**, pero **no pausa la IA de forma persistente**. Para pausar hasta que una persona reactive, usa una regla de escalamiento con «Pausar a la IA».
- **Desde la API:** `POST /conversations/{id}/pause-agent` y `resume-agent`. Mira [Referencia](/docs/api/referencia).

### Qué ve el cliente

Nada especial: cuando una persona toma el chat, el cliente simplemente recibe respuestas de ella en lugar de las de la IA. Si quieres avisarle del cambio, usa el **mensaje automático** de la regla.

### Preguntas frecuentes

**¿Cómo sé si la IA está pausada en un chat?** Abre el chat: el botón dice **Activar IA para este chat** cuando está pausada, y el aviso indica el motivo si fue por una respuesta del equipo. Las tres causas de una pausa son una respuesta de tu equipo, el botón de pausa o una regla con «Pausar a la IA».

**¿Qué pasa si nadie atiende un chat escalado?** La conversación queda en **Sin asignar** o con la persona asignada, con la etiqueta **Requiere humano**. Si la IA está pausada, no contesta hasta que alguien actúe. Considera activar la [asignación automática](/docs/atencion/equipo-y-roles#asignacion-automatica) y el [horario de atención](/docs/agente/perfil-y-estilo#horario-de-atencion).

**La IA contestó cuando ya había respondido una persona.** Revisa en [Solución de problemas](/docs/ayuda/solucion-de-problemas) la sección «La IA contesta cuando no debería».


## Links inteligentes

> Haz que el agente comparta un enlace (catálogo, portafolio, precios) de forma natural cuando el cliente pregunta por ese tema.
Fuente: https://orkestaliq.com/docs/agente/links-inteligentes

Un **link inteligente** es un enlace que el agente incluye en su respuesta cuando el cliente pregunta por un tema que tú definiste. Evita que el agente describa tu catálogo en un mensaje larguísimo cuando basta con compartir la página.

Se configuran en **Agente IA → Avanzado · Links Inteligentes**.

### Cómo configurarlos

Para cada link completas tres campos:

| Campo | Ejemplo |
| --- | --- |
| **Cuándo compartirlo (tema o pregunta)** | «Cuando pregunten por el catálogo, por los precios o por el portafolio» |
| **URL del enlace** | `https://tutienda.com/catalogo` |
| **Etiqueta del link** | «Ver catálogo» |

Pulsa **Guardar** al terminar. El agente empieza a usarlos de inmediato en los siguientes mensajes.

### Cómo los usa el agente

Cuando alguien pregunta sobre el tema indicado, el agente incluye el enlace **en su respuesta, de manera natural**: lo menciona dentro de la conversación en lugar de pegarlo suelto.

### Cuándo conviene un link inteligente y cuándo otra cosa

| Quieres… | Usa… |
| --- | --- |
| Que el agente mande **una página web** (catálogo, formulario de reserva, portafolio) | **Link inteligente** |
| Que el agente mande **un archivo** (PDF, imagen, video) | [Archivos de contexto](/docs/conocimiento/archivos-de-contexto) |
| Que el agente **sepa y explique** una política o un precio | [Base de conocimiento](/docs/conocimiento/base-de-conocimiento) |
| Que el agente **cobre** | [Stripe](/docs/integraciones/stripe) |
| Que el agente **agende** | [Google Calendar](/docs/integraciones/google-calendar) |

### Buenas prácticas

- **Una situación por link.** «Catálogo de bodas» y «Catálogo de XV años» funcionan mejor separados que juntos.
- **Describe la pregunta del cliente**, no tu nombre interno del enlace.
- **Verifica que el enlace abra** en un celular. Muchos clientes lo verán desde WhatsApp.
- **Revisa que no sea de uso interno.** El agente compartirá el enlace con cualquier cliente que pregunte por el tema.


## Funnel de ventas (playbook)

> Define paso a paso qué debe preguntar tu agente primero y cómo cerrar, con una cita agendada o un link de pago.
Fuente: https://orkestaliq.com/docs/agente/playbook-de-ventas

El **Funnel de ventas**, también llamado **playbook de ventas**, es el guion con el que tu agente conduce una conversación comercial: **qué conocer primero y cuándo ofrecer**. Sin él, el agente decide solo el orden; con él, sigue tu proceso de venta en cada conversación sin sonar a formulario.

Se configura en **Integraciones → Funnel de ventas** y también se edita desde la pantalla del agente.

> [!IMPORTANTE]
> El Funnel de ventas es un **complemento (add-on)** que se suma a tu plan. Si tu cuenta no lo tiene, la pantalla te ofrece **Activar add-on**: se prorratea sobre tu plan y puedes cancelarlo cuando quieras (tu funnel queda guardado por si lo reactivas). Si tu cuenta la administra un proveedor o agencia, pídele que lo active. Para guardar el funnel como activo se requiere el add-on, y solo un administrador puede editarlo.

### Para qué sirve

- **Tu proceso de venta, paso a paso.** Defines qué conocer primero (servicio, fecha, zona, presupuesto…) y cuándo ofrecer.
- **Datos directo a tu CRM.** Lo que el cliente responde queda en su ficha, y cada paso puede mover el lead de etapa, ponerle etiquetas o avisar a tu equipo.
- **Ofertas que sí encajan.** Cuando llega el momento de ofrecer, el agente ya sabe lo que el cliente necesita y propone la opción correcta de tu catálogo.

### Cómo avanza la conversación

Estas reglas van incluidas siempre:

- **Siempre responde primero lo que el cliente pregunta**, antes de pedir un dato.
- **Pide un dato por mensaje** y se salta lo que el cliente ya dijo.
- **Precios y paquetes salen de tu base de conocimiento**, no del funnel.

Un paso es un **objetivo**, no un mensaje fijo: el agente lo dice con sus propias palabras. El funnel responde «¿hacia dónde voy y qué me falta?»; la base de conocimiento responde «¿qué es verdad?». Si parecen contradecirse en un dato, **manda el documento**.

### Crear tu funnel

1. Entra a **Integraciones → Funnel de ventas**.
2. Elige un **punto de partida** y ajústalo. Hay plantillas por tipo de negocio (por ejemplo eventos, inmobiliaria, tienda en línea, servicios con cita). Puedes cambiar todo después.
3. Para cada paso defines:

| Campo | Qué es |
| --- | --- |
| **¿Qué quieres saber del cliente?** | El dato que ese paso busca (servicio, fecha, lugar, presupuesto o un dato propio) |
| **¿Para qué es este paso?** | El objetivo, en una frase |
| **Frase de ejemplo** | Para marcar el tono; el agente **no la copia literal** |
| **Necesario antes de dar precios** | Obliga a completar el paso antes de hablar de precios |
| **Cuando se complete este paso** | Acciones internas que ocurren **una sola vez por conversación**: mover el lead a una etapa, avisar al equipo, poner etiquetas |

4. Elige **cómo termina el recorrido**:

| Cierre | Qué hace el agente | Se cumple cuando… |
| --- | --- | --- |
| **Solo la propuesta** | Hace la oferta con la opción adecuada de tu catálogo | El paso de oferta se completa |
| **Agendar una cita** (requiere [Google Calendar](/docs/integraciones/google-calendar)) | Propone horarios reales de tu calendario y agenda cuando el cliente elige uno | La cita existe de verdad |
| **Enviar link de pago** (requiere [Stripe](/docs/integraciones/stripe)) | Cuando el cliente decide pagar, genera un link real de Stripe con el monto de tus documentos | El link existe de verdad |

5. Guarda. Verás «Funnel guardado y activo» o «Funnel guardado (inactivo)». Necesitas **al menos un paso** para activarlo.

> [!NOTA]
> Los pasos de cierre se cumplen por **el efecto real** (la cita existe, el link existe), no por lo que el agente diga haber hecho.

### Qué pasa si el cliente no coopera

Las acciones de «Cuando se complete este paso» corren hasta que el paso se completa. Si el cliente no da el dato tras varios mensajes, el agente **deja de insistir** y esas acciones **no se ejecutan**.

### Cómo se lleva con los flujos y otras reglas

- **Con un flujo de «Recolectar datos»:** si un flujo pide el mismo dato que el funnel, mientras el funnel esté activo **es el funnel quien lo pregunta** y el flujo solo lo guarda. El editor te avisa cuando detecta esa coincidencia.
- **Con un flujo de «Cambiar estado del lead»:** si un flujo y el funnel mueven al lead a etapas distintas, el editor te pide revisar que no se contradigan.
- **Con las reglas de escalamiento y la pausa por respuesta del equipo:** tienen prioridad. Si la conversación se escala o una persona la atiende, el funnel no corre. Mira [Relevo humano](/docs/agente/relevo-humano).
- **Con el objetivo de conversión del agente:** mientras el funnel no haya terminado, el funnel define el siguiente objetivo y reemplaza al objetivo genérico. Cuando termina, o si no hay funnel, vuelve el objetivo de la pantalla de Agente IA.
- **En post-venta, quejas y soporte** el funnel no aplica.

### Cancelar

Puedes cancelar el add-on desde la misma pantalla de **Funnel de ventas**. Orkestal te pide confirmar. El agente deja de seguir el funnel, pero tu funnel queda guardado por si lo reactivas.


## Simulador

> Habla con tu agente como si fueras un cliente, sin gastar mensajes de WhatsApp, para probar antes de encender la IA.
Fuente: https://orkestaliq.com/docs/agente/simulador

El **Simulador** es un canal de prueba dentro de **Conversaciones**. Te deja escribirle a tu agente **como si fueras un cliente** y ver cómo contesta con tu configuración real: su estilo, tu base de conocimiento, tu inventario, tus reglas de escalamiento y las integraciones conectadas.

### Para qué usarlo

- **Antes de encender la IA** por primera vez.
- **Después de cada cambio importante**: un documento nuevo, una regla de escalamiento, un estilo distinto.
- **Para reproducir un problema** que viste en un chat real, sin molestar al cliente.

### Cómo usarlo

1. En **Conversaciones**, pulsa **Iniciar Simulador**. Aparece una conversación nueva en la lista, bajo el canal **Simulador**.
2. Abre la conversación y escribe en el campo «Escribe un mensaje como cliente…». También puedes mandar un archivo.
3. Lee la respuesta del agente. Si probaste una regla de escalamiento o un flujo, verifica también la etiqueta, la asignación y las notificaciones.
4. Para empezar de cero, pulsa **Reiniciar Simulador**: borra la memoria del simulador.

### Qué conviene probar

| Prueba | Qué deberías ver |
| --- | --- |
| Las 5 preguntas que más te hacen tus clientes | Respuestas correctas y con el tono que elegiste |
| Una pregunta cuya respuesta **no** está en tu información | El agente no inventa; la pregunta aparece en **Brechas de Conocimiento** |
| Una queja o un cliente enojado | Se dispara tu regla de escalamiento |
| «Quiero hablar con una persona» | El agente pasa la conversación según tus reglas |
| Pedir un producto, precio o existencia | Datos exactos de tu inventario |
| Pedir una cita (si conectaste calendario) | Propone horarios libres y agenda |
| Pagar (si conectaste Stripe) | Genera el enlace de pago |
| Escribir fuera de tu horario de atención | Respeta el horario y el mensaje de fuera de horario |

### Qué no hace el simulador

- **No consume mensajes de WhatsApp ni de ningún canal**, pero **sí usa tu clave de IA**: cada respuesta del agente consume el crédito de tu proveedor, igual que en una conversación real.
- Las **respuestas rápidas** no están disponibles en el simulador.
- No prueba el **envío a WhatsApp** (ventana de 24 horas, plantillas, calidad del número). Esas reglas solo se ven en chats reales. Mira [Reglas de WhatsApp](/docs/canales/reglas-de-whatsapp).

> [!CONSEJO]
> Haz las pruebas con **frases reales** que te hayan escrito tus clientes, con sus faltas de ortografía incluidas. Es la mejor forma de saber si una regla de escalamiento es demasiado amplia o demasiado estricta.


# Conocimiento


## Qué fuente usar para cada cosa

> Base de conocimiento, inventario, archivos de contexto, links, funnel y flujos responden preguntas distintas. Aquí está cuál usar según lo que quieras lograr.
Fuente: https://orkestaliq.com/docs/conocimiento/que-fuente-usar

Orkestal tiene varios lugares donde puedes poner información. La confusión más común es **meter todo en la base de conocimiento**. Funciona a medias porque cada fuente está pensada para responder una pregunta distinta.

### La regla corta

| Si quieres que el agente… | Ponlo en… |
| --- | --- |
| **Sepa algo**: una política, un horario, una explicación, precios de un servicio | [Base de conocimiento](/docs/conocimiento/base-de-conocimiento) |
| **Venda productos o servicios concretos**, con precio y existencias | [Inventario](/docs/conocimiento/inventario) |
| **Envíe un archivo** (catálogo en PDF, menú, mapa, foto) cuando el cliente lo pida | [Archivos de contexto](/docs/conocimiento/archivos-de-contexto) |
| **Comparta un enlace** (catálogo web, reservas, portafolio) | [Links inteligentes](/docs/agente/links-inteligentes) |
| **Siga un orden** en la conversación (preguntar servicio, luego fecha, luego presupuesto) | [Funnel de ventas](/docs/agente/playbook-de-ventas) |
| **Hable** de cierta manera (tono, longitud, emojis) | [Perfil y estilo](/docs/agente/perfil-y-estilo) |
| **Pase la conversación a una persona** en ciertos casos | [Reglas de escalamiento](/docs/agente/relevo-humano) |
| **Haga algo solo** cuando ocurre un evento (etiquetar, avisar, mandar una plantilla) | [Flujos](/docs/flujos/introduccion) |
| **Consulte datos vivos** de una hoja, tienda o página | [Google Sheets](/docs/integraciones/google-sheets), [WooCommerce](/docs/integraciones/woocommerce), [Notion](/docs/integraciones/notion) |

### Por qué importa separar

Cada fuente responde una pregunta distinta:

| Fuente | Responde | Nunca debería contener |
| --- | --- | --- |
| Base de conocimiento | ¿Qué es verdad? | El orden de la conversación |
| Funnel de ventas | ¿Hacia dónde voy y qué me falta? | Precios, políticas o datos |
| Reglas de escalamiento | ¿Cuándo me salgo? | Respuestas para el cliente |
| Flujos | ¿Qué hace el sistema solo? | Instrucciones de conversación |

Un ejemplo de lo que sale mal: si escribes en un documento «Paso 1: pregunta el servicio. Paso 2: pregunta la fecha…», el agente solo recupera **fragmentos por similitud**, no por orden. Si el cliente dice «vivo en Monterrey», el fragmento del «Paso 3» puede no entrar y el agente pierde el hilo. El orden va en el funnel; los datos, en la base de conocimiento.

### Cómo decide el agente qué consultar

- Cada turno, el agente recupera de la base de conocimiento los fragmentos más parecidos a la pregunta del cliente, y consulta también el inventario cuando el cliente habla de productos.
- Cada documento puede tener una **regla de enrutamiento** que dice cuándo debe consultarse. Sin regla, el agente puede omitirlo aunque contenga la respuesta. Un documento marcado como **base principal** se entrega siempre.
- Las integraciones tienen sus propias **reglas de uso** que definen cuándo se consultan. Mira [Integraciones: resumen](/docs/integraciones/resumen#reglas-de-uso-para-el-agente).
- Si el agente no encuentra la respuesta en la base de conocimiento, el inventario ni los archivos de contexto, la pregunta queda registrada en **Brechas de Conocimiento**.

### Cuando dos fuentes se contradicen

Es la causa número uno de respuestas raras. Ejemplos: el PDF viejo dice un precio y el inventario otro; una política cambió pero el documento anterior sigue activo. Reglas para evitarlo:

1. **Un dato, un lugar.** Los precios de productos viven en el inventario; no los repitas en un PDF.
2. **Reemplaza, no acumules.** Cuando una política cambie, edita o borra el documento anterior.
3. **Revisa los documentos viejos** de negocios o servicios que ya no ofreces: el agente los seguirá usando mientras existan.
4. Si el funnel y un documento parecen contradecirse en un dato, **manda el documento**.

### Un camino razonable para empezar

1. Sube a la **base de conocimiento** un documento de preguntas frecuentes y otro de políticas (envíos, devoluciones, pagos, horarios).
2. Carga tus productos o servicios al **inventario**.
3. Configura 1 o 2 **archivos de contexto** (el catálogo en PDF).
4. Prueba con el [simulador](/docs/agente/simulador) y revisa las **brechas**.
5. Agrega un **funnel** solo cuando el orden de la conversación importe.


## Base de conocimiento

> Sube documentos para que el agente conteste con tus precios, políticas y preguntas frecuentes, y aprende a mantenerlos al día.
Fuente: https://orkestaliq.com/docs/conocimiento/base-de-conocimiento

La **Base de Conocimiento** son los documentos que el agente consulta para responder con hechos: precios, políticas, horarios, preguntas frecuentes, descripciones de servicios. Es la **fuente de verdad** del agente sobre tu negocio. Se encuentra en **Base de Conocimiento** (Manager y Admin).

Si no sabes si algo va aquí o en otro lado, lee [Qué fuente usar para cada cosa](/docs/conocimiento/que-fuente-usar).

### Subir un documento

1. En **Base de Conocimiento**, pulsa **Subir documentos** (o **Agregar documento**).
2. Elige tu archivo. Formatos con lectura de texto: **PDF, TXT, Markdown (MD), CSV y Excel (XLSX/XLS)**. Si tu documento está en Word (DOCX), guárdalo como PDF antes de subirlo.
3. Orkestal lo guarda y lo procesa en segundo plano: lee el texto, lo divide en fragmentos, los convierte en vectores (*embeddings*) y los indexa para poder buscarlos por significado.
4. Cuando el estado sea **Activo**, el agente ya puede usarlo.

#### Estados de un documento

| Estado | Qué significa |
| --- | --- |
| **Procesando** / **Indexando** | Orkestal lo está leyendo e indexando |
| **Activo** | Listo: el agente puede consultarlo |
| **Falta clave de IA** | Aún no hay clave de IA configurada. Al guardarla en Configuración, el documento se reprocesa. Mira [Clave de IA](/docs/agente/clave-de-ia) |
| **Error** | No se pudo procesar. Revisa que el archivo no esté dañado ni protegido con contraseña y que tenga texto (un PDF escaneado como imagen no tiene texto que leer) |

> [!NOTA]
> Los PDF con tablas se leen conservando la estructura de las tablas. Un PDF que es solo una imagen escaneada no se puede leer: conviértelo antes a texto.

#### Límites

- Tu plan limita cuántos documentos puedes tener. El límite de **archivos de contexto** del plan se cuenta con los documentos de tu base de conocimiento (el plan Starter incluye **2**). Mira [Planes y facturación](/docs/cuenta/planes-y-facturacion).
- Un documento se divide en fragmentos de unos 1,200 caracteres y se indexan **hasta 500 fragmentos por documento**. Si tu archivo es muy grande, divídelo en varios por tema.

### Cómo decide el agente cuándo consultar un documento

Esta es la parte que más se pasa por alto. Cada documento tiene un **enrutador inteligente**:

- **Regla de enrutamiento**: una descripción, en tus palabras, de cuándo debe consultarse ese documento. Ejemplo: «Usar para preguntas sobre precios, planes, renovaciones y políticas de cancelación».
- **Base principal**: un documento marcado como **«Incluir siempre como base principal»** se entrega al agente en **todas** las consultas, y entonces la regla ya no hace falta.

Sin regla ni marca de base principal, **el agente puede omitir ese documento aunque contenga la respuesta**. Para configurarlo, abre el documento y pulsa **Configurar router ahora** (o **Editar regla del router**).

> [!CONSEJO]
> Una regla precisa reduce respuestas fuera de contexto y evita consultar archivos innecesarios. Marca como base principal solo un documento corto con lo esencial (quién eres, qué vendes, horarios); los demás, con su regla.

### Ver y editar un documento

Al abrir un documento verás tres pestañas:

- **Resumen**: su descripción para el router, cuántos fragmentos tiene, su tamaño, su tipo y el estado.
- **Contenido**: el texto (si el formato lo permite) y el botón **Editar contenido**. Al guardar, Orkestal muestra «Documento actualizado. Reindexando en segundo plano.»
- **Actividad**: cuándo se agregó, cuándo se actualizó y su estado de indexación.

También puedes **Ver archivo original**, y **eliminar** el documento: se borra de la base de datos y del almacenamiento, y no se puede deshacer.

### Las otras pestañas

| Pestaña | Para qué sirve |
| --- | --- |
| **Fuentes** | Una vista gráfica de tus documentos |
| **Brechas de Conocimiento** | Las preguntas que el agente **no pudo contestar** porque no encontró nada en la base de conocimiento, el inventario ni los archivos de contexto. Cubre cada una y márcala como **resuelta** |
| **Embeddings Preview** | El **simulador de búsqueda semántica**: escribe una pregunta y ve qué fragmentos recuperaría el agente. Útil para saber por qué contestó algo |

El encabezado de la pantalla muestra además cuántas fuentes están indexadas y la **última sincronización**; **Ver historial** lista los documentos agregados y actualizados.

### Cómo escribir buenos documentos

1. **Un tema por documento.** «Envíos y devoluciones» es mejor que «Todo sobre el negocio».
2. **Escribe como contestarías.** Frases completas con el dato incluido. En lugar de «Envío: 99», escribe «El envío estándar cuesta $99 MXN y tarda de 2 a 4 días hábiles».
3. **Incluye variantes de la pregunta.** Si la gente dice «factura» y «CFDI», usa ambas palabras.
4. **Pon fechas de vigencia** en promociones y precios que cambian.
5. **Estructura con títulos** y listas cortas; evita tablas gigantes.
6. **Un dato, un lugar.** No repitas precios de productos que ya viven en el [inventario](/docs/conocimiento/inventario).
7. **No metas el guion de la conversación** («primero pregunta X, luego Y»): eso va en el [funnel](/docs/agente/playbook-de-ventas).
8. **No incluyas datos que no deba repetir el agente**: contraseñas, datos de clientes o información interna. El agente puede citar cualquier cosa que esté en un documento.

### Mantenerlo al día

- Revisa **Brechas de Conocimiento** a diario las primeras semanas y después cada semana.
- Cuando cambien precios o políticas, **edita el documento**; no subas uno nuevo sin quitar el viejo.
- Elimina los documentos de servicios que ya no ofreces.
- Después de cambios grandes, prueba en el [simulador](/docs/agente/simulador).

### Problemas comunes

| Síntoma | Qué revisar |
| --- | --- |
| El agente no usa un documento | Que el estado sea **Activo** y que tenga regla de enrutamiento o esté marcado como base principal. Prueba la pregunta en **Embeddings Preview** |
| Contesta con un dato viejo | Hay otro documento (o el inventario) con el dato anterior. Busca el duplicado |
| El documento se queda en Procesando | Espera unos minutos; si sigue igual, elimínalo y vuelve a subirlo, o escribe a soporte@orkestaliq.com |
| «Falta clave de IA» | Configura tu clave en Configuración |


## Inventario

> Carga tus productos y servicios con precio, existencias, fotos y atributos para que el agente los recomiende, cotice y deje de ofrecer lo agotado.
Fuente: https://orkestaliq.com/docs/conocimiento/inventario

El **Inventario** es el catálogo de productos y servicios que el agente puede **consultar, recomendar y cotizar**. A diferencia de la [base de conocimiento](/docs/conocimiento/base-de-conocimiento) (que explica), el inventario **vende**: tiene precios, existencias y fotos concretos. Se encuentra en **Inventario** (Manager y Admin).

### Qué se carga por cada elemento

| Campo | Para qué sirve |
| --- | --- |
| **Nombre del elemento** (obligatorio) | Un nombre descriptivo, el que usaría un cliente. Ej.: «Collar artesanal de piel» |
| **Precio mínimo y máximo** | Un precio único, o un rango si varía. Deja el máximo vacío si es fijo |
| **Nota de precio** | La unidad o condición: «por sesión», «por m²», «por evento» |
| **Existencias (stock)** | Cuántas unidades hay. **Vacío significa ilimitado** (útil para servicios) |
| **SKU / identificador único** | Opcional, pero **imprescindible** si sincronizas con [Mercado Libre](/docs/integraciones/mercado-libre) o [WooCommerce](/docs/integraciones/woocommerce): es lo que enlaza cada producto |
| **Disponible para el agente** | Si el agente puede ofrecerlo (ver abajo) |
| **Nota de disponibilidad** | Ej.: «Lista de espera de 2 semanas», «entrega inmediata» |
| **Descripción** | Especificaciones, alcances, materiales, descripciones detalladas |
| **Etiquetas de asociación para la IA** | Frases que describen cómo lo buscaría un cliente, para que el agente lo encuentre |
| **Atributos** | La ficha técnica (ver abajo) |
| **Fotos, videos y documentos** | Material que el agente puede mostrar |

#### Disponibilidad automática

La disponibilidad **se calcula sola según el stock**: cuando las existencias llegan a **0**, el elemento se marca **Agotado** y el agente **lo omite**. Cuando vuelve a haber stock, se reactiva solo. No tienes que activarlo a mano. En la lista puedes filtrar por disponibles y agotados.

La pantalla resume tu catálogo con tres contadores: **Total del catálogo**, **Activos en IA** y **Críticos o sin stock**.

### Fichas por tipo de negocio

Para que la información sea útil, cada elemento tiene una **ficha de atributos** adaptada a tu sector. Elige la estructura en **Estructura activa**:

| Estructura | Campos de la ficha |
| --- | --- |
| Mascotas | Talla, color, material, raza objetivo, rango de peso |
| Eventos | Capacidad de personas, horas incluidas, ¿incluye catering?, ¿incluye estacionamiento?, días disponibles |
| Clínica estética | Duración, áreas de tratamiento, sesiones recomendadas, tiempo de recuperación, contraindicaciones |
| Restaurante | Ingredientes clave, alérgenos, tipo de cocina, tiempo de preparación, ¿es vegetariano? |
| Inmobiliaria | Metros cuadrados, recámaras, baños completos, zona, tipo de propiedad (casa, departamento, terreno, oficina, bodega), ¿está amueblado? |
| Ropa y moda | Talla, color, material o tela, género sugerido, temporada |
| Servicios generales | Duración, modalidad (presencial, a domicilio, online, híbrido), qué incluye, requisitos previos |
| General | Sin campos extra: solo los datos básicos del elemento |

Si ninguna encaja, usa **Crear estructura para otro sector** y define tus propios campos: nombre visible, tipo (**texto libre**, **lista de selección** con opciones separadas por coma, o **área de texto**). También puedes agregar **atributos libres** a un elemento puntual.

### Fotos, videos y documentos

Cada elemento admite material adjunto con estos límites por archivo:

| Tipo | Tamaño máximo |
| --- | --- |
| Imágenes | 1 MB |
| Documentos (PDF, Word, Excel, PowerPoint, CSV, texto, ZIP) | 5 MB |
| Videos | 10 MB |

Tu plan limita cuántos productos puedes tener y cuántos pueden llevar video. El plan **Starter** incluye **50 productos, con hasta 2 videos**. Mira [Planes y facturación](/docs/cuenta/planes-y-facturacion).

### Buscar y simular

La búsqueda del inventario encuentra por nombre, etiquetas, SKU y atributos. El panel incluye un simulador de búsqueda que muestra qué elementos devolvería para una consulta (con su **similitud de coincidencia**) y el contexto que recibiría el agente. Úsalo para ver por qué el agente recomendó un producto y no otro.

### Cómo lo usa el agente

- Cuando el cliente habla de productos, precios, existencias o disponibilidad, el agente consulta el inventario y responde con **los datos exactos** del catálogo.
- No ofrece lo marcado como no disponible o agotado.
- Con [Cotización Inteligente](/docs/integraciones/cotizacion-inteligente), arma cotizaciones en PDF con tus precios. Si falta un precio, queda un borrador en lugar de inventar.
- Si no encuentra un producto, la pregunta queda en **Brechas de Conocimiento**.

> [!IMPORTANTE]
> **El agente no inventa precios.** Si un producto no tiene precio cargado, no podrá cotizarlo con certeza. Revisa que tus precios, impuestos y existencias estén correctos antes de activar la IA o la cotización automática.

### Sincronización con tiendas

- **Mercado Libre**: el stock se sincroniza en ambos sentidos, y los precios de Mercado Libre hacia Orkestal, enlazados por SKU. Mira [Mercado Libre](/docs/integraciones/mercado-libre).
- **WooCommerce**: puedes importar tu catálogo (productos y variaciones) y mantener las existencias enlazadas. Mira [WooCommerce](/docs/integraciones/woocommerce).

Hoy los productos se cargan **uno por uno** desde la pantalla, o se importan desde WooCommerce.

### Buenas prácticas

1. **Nombra como te preguntan.** Usa las palabras de tus clientes, no un código interno.
2. **Un SKU único y estable** por producto, sobre todo si sincronizas con una tienda.
3. **Mantén el stock al día.** Si usas Mercado Libre o WooCommerce, edita el stock desde Orkestal para evitar desajustes.
4. **Llena las etiquetas de asociación** con frases reales: «vestido rojo talla S de seda», «terraza para evento pequeño de 50 personas».
5. **Define la nota de precio** cuando el precio dependa de algo (por sesión, por persona, por m²).


## Archivos de contexto

> Configura qué archivos (catálogo, menú, mapa, fotos) envía el agente al cliente y en qué situación.
Fuente: https://orkestaliq.com/docs/conocimiento/archivos-de-contexto

Los **archivos de contexto** son archivos que el agente **envía al cliente** durante la conversación cuando se cumple una situación que tú describes: tu catálogo en PDF cuando piden precios, el menú cuando preguntan qué ofreces, el mapa cuando preguntan cómo llegar.

> [!IMPORTANTE]
> No los confundas con la [base de conocimiento](/docs/conocimiento/base-de-conocimiento). Los archivos de contexto **se mandan tal cual**; el agente no los lee para contestar. Para que el agente *sepa* algo, súbelo a la base de conocimiento.

Se administran en **Archivos Contexto** (Manager y Admin). Cada entrada es una **regla de contexto**: «cuando pase esto, manda estos archivos».

### Crear una regla

1. Pulsa **Nueva Regla**.
2. Completa la **información principal**:

| Campo | Qué poner |
| --- | --- |
| **Nombre de la regla** | Para que la reconozcas. Ej.: «Catálogo 2026», «Menú de postres», «Mapa de ubicación» |
| **Contexto de envío** | Instrucciones claras, para la IA, de **cuándo** enviar estos archivos. Ej.: «Cuando el usuario pregunte por el menú, los precios de comida o qué ofrecemos de comer» |
| **Archivos adjuntos** | Sube imágenes, PDFs, videos o documentos. **Mínimo 1** |
| **Etiquetas adicionales** | Para organizar y buscar tus reglas |
| **Estado de la regla** | Si está **inactiva**, la IA no enviará los archivos de esta regla |

3. Guarda. Verás «Regla de contexto registrada con éxito».

#### Límites de tamaño por archivo

| Tipo | Máximo |
| --- | --- |
| Imágenes | 5 MB |
| Documentos | 10 MB |
| Videos | 15 MB |

Si pasas el límite, la pantalla lo avisa y puedes comprimir el archivo y volver a intentarlo.

### Editar, pausar o eliminar

- **Editar**: abre la regla, cambia lo que necesites y guarda. «Regla actualizada correctamente.»
- **Pausar** sin borrar: cambia el estado a inactiva.
- **Eliminar**: «Eliminar Regla». Se confirma antes de borrar.
- **Buscar**: el buscador filtra por nombre, descripción o etiquetas.

### Cómo escribir un buen contexto de envío

El contexto de envío es lo que le dice a la IA **en qué momento** mandar el archivo. Es la parte que más influye.

- **Describe la intención del cliente**, no el nombre del archivo: «Cuando pregunten qué platillos hay o cuánto cuesta comer» funciona mejor que «Menú».
- **Un archivo por situación.** Si juntas catálogo, menú y mapa en una sola regla, el agente mandará los tres siempre.
- **Indica cuándo no enviarlo** si hace falta: «No enviar si el cliente ya recibió el catálogo en esta conversación».
- **Pon el archivo adecuado para un celular**: un PDF liviano y legible a pantalla pequeña.

### Qué ve el cliente

El agente manda el archivo dentro de la conversación, como cualquier otro mensaje con adjunto, junto con una frase. En WhatsApp se aplican las [reglas de tipos de archivo de WhatsApp](/docs/canales/reglas-de-whatsapp#tipos-de-archivo).

### Alternativas

| Si lo que quieres es… | Usa… |
| --- | --- |
| Mandar **siempre el mismo archivo** automáticamente al cumplirse un evento (por ejemplo, al llegar un lead nuevo) | La acción **Enviar archivo** de un [flujo](/docs/flujos/hacer) |
| Que un **miembro del equipo** mande un archivo a mano | El botón de adjuntar archivo del chat, o una [respuesta rápida](/docs/atencion/bandeja#respuestas-rapidas) con archivo |
| Mandar una **página web** | [Links inteligentes](/docs/agente/links-inteligentes) |


# Flujos de automatización


## Flujos de automatización

> Qué es un flujo, cómo se construye con reglas «Cuando → Hacer» y en qué se diferencia del agente y de las reglas de escalamiento.
Fuente: https://orkestaliq.com/docs/flujos/introduccion

Un **flujo** es un conjunto de reglas **«Cuando → Hacer»** que Orkestal ejecuta solo, sin que nadie las dispare. *Cuando* un cliente escribe cierta palabra, *cuando* se le asigna una etiqueta, *cuando* se agenda una cita o pasa mucho tiempo sin contestar, *hacer* algo: etiquetar, avisar al equipo, mandar una plantilla, guardar los datos en una hoja de cálculo.

Se construyen en **Flujos** (Manager y Admin).

### Flujos, agente y reglas de escalamiento

Son tres cosas distintas que trabajan juntas:

| | Qué decide | Ejemplo |
| --- | --- | --- |
| **Agente de IA** | Qué **responder** al cliente | Contestar un precio con los datos de tu inventario |
| **Reglas de escalamiento** | Cuándo **dejar de contestar y pasar a una persona** | Un cliente pide cotizar un evento grande |
| **Flujos** | Qué **hace el sistema** cuando ocurre algo | Etiquetar al cliente como «cotizado» y avisar a ventas |

Un flujo no cambia lo que dice el agente en la conversación; automatiza lo que pasa **alrededor**. Si lo que quieres es que una persona tome el chat y la IA se calle, usa una [regla de escalamiento](/docs/agente/relevo-humano).

### Cómo se construye un flujo

1. Entra a **Flujos** y pulsa para crear uno nuevo. Puedes partir de una **plantilla de flujo** (bienvenida a nuevo lead, seguimiento por inactividad, transferencia al equipo ante sentimiento negativo, etiquetado por contexto) o de cero.
2. Dale un nombre. Para renombrarlo después, haz doble clic.
3. En **Lógica de automatización**, agrega una o más **reglas**. Cada una tiene:
   - un **Cuando**: el disparador (con sus opciones),
   - un **Hacer**: la acción (con sus opciones).
4. Pulsa **Guardar Flujo**. Orkestal valida cada regla y no te deja guardar una que no pueda ejecutar.

El editor solo te muestra **capacidades activas y ejecutables**. Si una combinación no aparece, es que hoy no está disponible.

> [!NOTA]
> Los flujos son **ilimitados** en todos los planes.

### Activar y pausar

Cada flujo tiene un interruptor de activo. Un flujo pausado conserva su configuración pero no se ejecuta. Pausar un flujo es la forma segura de apagarlo si dudas de su efecto, sin perderlo.

### Reglas generales que conviene saber

- **Se ejecutan sin intervención.** Prueba cada flujo con un contacto de prueba o en el [simulador](/docs/agente/simulador) antes de dejarlo activo.
- **Pueden encadenarse.** Un flujo puede asignar una etiqueta, y otro puede dispararse con «Se asignó una etiqueta». Una etiqueta puesta desde fuera (por ejemplo desde [n8n](/docs/integraciones/n8n)) dispara tus flujos igual que si la hubiera puesto el agente.
- **Los tiempos de espera tienen tope.** Las esperas en minutos u horas admiten hasta 23 horas; para esperas mayores usa «Inactividad prolongada», que acepta días.
- **Los envíos obedecen a WhatsApp.** Los mensajes que inicia tu negocio, fuera de la ventana de 24 horas, solo salen como plantilla aprobada. Mira [Reglas de WhatsApp](/docs/canales/reglas-de-whatsapp).
- **Tu equipo puede ver el resultado.** Las etiquetas aparecen en el contacto, los mensajes en el chat y los avisos en las notificaciones.

### Siguientes pasos

- Qué dispara un flujo: [Cuando](/docs/flujos/cuando).
- Qué puede hacer: [Hacer](/docs/flujos/hacer).
- Ejemplos listos para copiar: [Recetas](/docs/flujos/recetas).


## Flujos, Cuando (disparadores)

> Todos los disparadores que funcionan hoy en los flujos, con sus opciones y las trampas más comunes.
Fuente: https://orkestaliq.com/docs/flujos/cuando

El **Cuando** de una regla es lo que la dispara. Esta es la lista completa de combinaciones que el motor ejecuta hoy. Si el editor muestra otras opciones, no se ejecutarán; usa las de esta página.

### Mensaje entrante

Se evalúan cuando el cliente escribe.

#### Según el contexto (IA)

La IA evalúa el mensaje del cliente contra una **descripción que tú escribes** en palabras normales. Es la opción recomendada para disparadores precisos.

- **Campo:** «¿Qué debe detectar la IA?». Ej.: «El cliente pregunta por precios de mayoreo» o «cliente molesto».
- Es la más flexible: no depende de palabras exactas.
- Para capturar datos de **cualquier** contacto (no solo leads nuevos), úsala como disparador de «Recolectar datos».

#### Contiene palabra clave

Se activa si el mensaje del cliente **contiene** la palabra o frase configurada, sin distinguir mayúsculas.

- **Campo:** «Palabra o frase (no distingue mayúsculas)».
- Útil para códigos de promoción y comandos como `CANCELAR` o `MENÚ`.

#### Sentimiento detectado

Filtra por el sentimiento del mensaje: **Positivo**, **Negativo** o **Neutral**.

### Estado del contacto

Se evalúan cuando algo cambia en el contacto.

#### Nuevo lead

Se dispara con los contactos nuevos. **Se activa mientras el contacto conserva la etiqueta `nuevo_lead`**: un contacto antiguo, o uno que ya la perdió, nunca entra por aquí.

#### Se asignó una etiqueta

Se dispara cuando se asigna una etiqueta, ya sea desde un flujo o desde la API.

- **Campo:** «Etiquetas que disparan el flujo». Si lo dejas vacío, **cualquier etiqueta** lo dispara.
- Permite **encadenar flujos**.

#### Cambió la etapa del lead

Se dispara cuando un flujo cambia la etapa y es **distinta de la anterior**.

- **Campo:** «Etapa». Si lo dejas vacío, cualquier cambio lo dispara.

### Citas

Requieren [Google Calendar](/docs/integraciones/google-calendar).

#### Se agendó una cita

Se dispara **en el momento** en que el agente agenda una cita desde el chat. Sirve para **confirmar**. Para recordar antes de que empiece, usa «Antes de una cita».

#### Antes de una cita

Se dispara **X horas antes** de que empiece una cita agendada.

- **Campo:** «Horas antes de la cita». Debe ser un número mayor que 0.
- Se **recalcula solo** si la cita se reagenda.

> [!IMPORTANTE]
> A esas horas, la ventana de 24 horas de WhatsApp casi siempre ya cerró. Un mensaje libre se pierde sin avisar. **Usa «Plantilla aprobada de Meta»** como acción. El editor te muestra una advertencia roja si combinas «Antes de una cita» con un mensaje automático libre.

### Acción del usuario

#### Solicita humano

Se dispara cuando el cliente pide hablar con una persona.

### Tiempo

Las esperas se programan por evento y **se cancelan solas si el cliente responde antes**.

| Opción | Qué hace | Campos |
| --- | --- | --- |
| **Después de X minutos** (Fecha o tiempo) | Se dispara pasado el tiempo configurado | Tiempo de espera y unidad (minutos u horas; **máximo 23 horas**) |
| **Tarda más de X minutos en responder** (Tiempo / demora del cliente) | Se dispara si el cliente no contesta a tu último mensaje en ese tiempo | Tiempo de espera y unidad (minutos u horas; máximo 23 horas) |
| **Inactividad prolongada** (Tiempo / demora del cliente) | Se dispara tras un periodo largo sin actividad | Duración y unidad (**horas o días**) |

> [!CUIDADO]
> Bajo «Fecha o tiempo» y «Tiempo / demora del cliente» el editor puede mostrar otras opciones (día específico, fuera de horario, expira plazo definido, ventana horaria, esperar hasta un evento). **No guardan una duración y nunca se disparan.** No las uses.

### Ajustes de los disparadores de tiempo

Los tres disparadores de tiempo comparten estos ajustes de **política de seguimiento**:

| Ajuste | Qué hace |
| --- | --- |
| **Máximo de seguimientos por conversación (1–3)** | Cuántas veces se puede disparar en una misma conversación |
| **Hora de inicio permitida** y **Hora de fin permitida** (HH:MM, opcionales) | Ventana del día en que sí se puede mandar, para no escribir de madrugada |
| **Zona horaria** | La zona en que se interpretan esas horas (UTC, Ciudad de México, Bogotá, Nueva York, entre otras) |

Además, **«Tarda más de X minutos en responder»** e **«Inactividad prolongada»** admiten el filtro opcional **«Solo si el contacto tiene alguna etiqueta»**: la acción solo corre si el contacto tiene al menos una de esas etiquetas. Útil para no mandar una promoción a quien ya compró.

### Tabla resumen

| Categoría | Opción | Cuándo se dispara |
| --- | --- | --- |
| Mensaje entrante | Según el contexto (IA) | El mensaje coincide con tu descripción |
| Mensaje entrante | Contiene palabra clave | El mensaje contiene la palabra o frase |
| Mensaje entrante | Sentimiento detectado | El mensaje es positivo, negativo o neutral |
| Estado del contacto | Nuevo lead | Contacto con la etiqueta `nuevo_lead` |
| Estado del contacto | Se asignó una etiqueta | Se asigna una etiqueta (la tuya o cualquiera) |
| Estado del contacto | Cambió la etapa del lead | Un flujo cambia la etapa (a la tuya o a cualquiera) |
| Citas | Se agendó una cita | Se crea una cita desde el chat |
| Citas | Antes de una cita | X horas antes de la cita |
| Acción del usuario | Solicita humano | El cliente pide a una persona |
| Fecha o tiempo | Después de X minutos | Pasa el tiempo (máx. 23 h) |
| Tiempo / demora del cliente | Tarda más de X minutos en responder | El cliente no contesta (máx. 23 h) |
| Tiempo / demora del cliente | Inactividad prolongada | Pasan horas o días sin actividad |


## Flujos, Hacer (acciones)

> Todas las acciones que un flujo puede ejecutar hoy, con los campos de cada una y lo que conviene saber antes de usarlas.
Fuente: https://orkestaliq.com/docs/flujos/hacer

El **Hacer** de una regla es lo que Orkestal ejecuta cuando se cumple el [Cuando](/docs/flujos/cuando). Estas son todas las acciones que funcionan hoy.

### Mensajes automáticos

#### Bienvenida, Seguimiento, Promoción y Recordatorio

Cuatro acciones que envían un mensaje al cliente. Las cuatro funcionan igual; cambia solo la intención.

- **Campo:** «Instrucciones para la IA (Contexto)». No escribes el mensaje final: escribes **qué debe comunicar**, y el agente de IA lo redacta con tono natural, integrándolo a la conversación.
- Cuando el mensaje es **proactivo** (el cliente no acaba de escribir), la IA lo trata como seguimiento, recordatorio o promoción.
- Puedes meter una **condición dentro de la instrucción**: «No mandar a quien ya reservó» o «solo si sigue sin confirmar». La IA la compara contra el historial real de la conversación y, **si la condición no se cumple, no envía nada**.
- Disparado por un mensaje del cliente (palabra clave, contexto de IA, sentimiento o «solicita humano»), el mensaje se manda **una sola vez por conversación**, para no repetir el mismo texto en cada turno.
- Si el disparador es de tiempo (por ejemplo «Inactividad prolongada»), puedes limitar cuántos seguimientos se mandan y en qué horas. Mira [Cuando: ajustes de los disparadores de tiempo](/docs/flujos/cuando#ajustes-de-los-disparadores-de-tiempo).

> [!IMPORTANTE]
> Un mensaje libre solo se entrega si la **ventana de 24 horas** de WhatsApp está abierta. Con el disparador «Antes de una cita» casi nunca lo está: usa **Plantilla aprobada de Meta**.

#### Enviar archivo

Envía **el archivo exacto**, sin pasar por la IA.

- **Campos:** el archivo, un nombre y un texto opcional (*caption*).
- **Tipos y tamaños:** imágenes JPG o PNG de hasta **5 MB**; videos MP4 o 3GP y documentos de hasta **14 MB**.
- Fuera de la ventana de 24 horas en WhatsApp, un archivo libre no se entrega: usa una plantilla aprobada con encabezado multimedia y el mismo archivo.
- Espera a que termine de subir el archivo antes de guardar el flujo.

#### Plantilla aprobada de Meta

Envía una [plantilla de WhatsApp](/docs/campanas/plantillas) aprobada por Meta.

- **Campos:** eliges la plantilla de la lista de tus plantillas aprobadas, y rellenas los **valores de sus variables**.
- Solo se ejecuta en conversaciones de **WhatsApp** y queda registrada en la bandeja.
- Es la forma correcta de escribir fuera de la ventana de 24 horas.
- Debes elegir una plantilla antes de poder guardar.

### Etiquetado y clasificación

#### Asignar etiqueta

Pone una o varias etiquetas al contacto.

- **Campo:** «Etiquetas». Puedes elegir varias en la misma regla.
- Con el [modo estricto de etiquetas](/docs/atencion/etiquetas-y-etapas#modo-estricto), solo puedes usar etiquetas de tu catálogo.
- Asignar una etiqueta puede disparar otros flujos con «Se asignó una etiqueta».

#### Cambiar estado del lead

Mueve la conversación a otra etapa.

- **Campo:** «Nueva etapa»: Nuevo lead, En proceso, Interesado, Calificado, En seguimiento, Negociación, Vendido o Declinado.

### Recolección de datos

#### Recolectar datos

Hace que el agente obtenga datos del cliente durante la conversación y los guarde en su ficha.

- **Datos estándar:** Nombre, Correo, Teléfono, Producto de interés y Preferencia.
- **Campos personalizados:** hasta **5**, cada uno con un nombre (ej. «Presupuesto») y una pista para la IA sobre qué buscar (ej. «el presupuesto aproximado que menciona el cliente»).
- **Pedir los datos que falten** (activo por defecto): el agente pide un dato faltante por mensaje, **después** de contestar la consulta del cliente, y deja de insistir tras dos intentos.
- Solo guarda datos que el cliente **expresa explícitamente**.
- **No reemplaza un nombre ni un correo ya confirmados.**
- El **teléfono** se guarda como dato de la ficha: **no cambia el número del contacto**, que es lo que identifica a esa persona en WhatsApp.

> [!CUIDADO]
> Con el disparador «Nuevo lead», esto **solo recolecta de leads nuevos**: se activa mientras el contacto conserva la etiqueta `nuevo_lead`, y un contacto antiguo nunca entra por ahí. Para recolectar de **cualquier** contacto, usa el disparador «Mensaje entrante → Según el contexto (IA)».

### Notificaciones

#### Avisar al equipo

Manda una notificación a tu equipo (campana y push) **sin transferir la conversación ni pausar la IA**.

- **Campo:** «Texto del aviso».

#### Notificar por Telegram

Manda un aviso al chat de Telegram de tu negocio, sin tocar la conversación del cliente.

- **Campos:** «Texto del aviso» (opcional) y «Chat o grupo de Telegram» (opcional; vacío usa el configurado en Canales).
- Si el disparador es «Se agendó una cita», el aviso incluye la **fecha, hora y duración** de la cita.
- Requiere Telegram activo en [Canales](/docs/canales/telegram), en modo **Notificaciones** o **Ambos**, con un Chat ID guardado. Si falta, el editor no te deja guardar.

### Transferencia y escalamiento

#### Escalar a humano y Transferir a agente

- **Campos:** «Agente / Equipo a delegar» y «Nota interna».
- Generan un resumen y evitan una respuesta duplicada **en ese turno**.
- **No pausan la IA de forma persistente.** Para pausar la IA hasta que una persona la reactive, usa una [regla de escalamiento](/docs/agente/relevo-humano) con «Pausar a la IA».

### Google Sheets

Requiere [Google Sheets](/docs/integraciones/google-sheets) conectado.

#### Exportar a Google Sheets

Inserta una **fila** con los datos del contacto, lo recolectado y el estado en tu hoja.

- **Campos:** «ID de la hoja de cálculo» (opcional si hay una predeterminada), «Pestaña y rango inicial» y «Formato de la fila»: **Lead estándar** o **Reservación** (fecha, hora, personas y motivo).

#### Consultar Google Sheets

Lee valores de una hoja como fuente de información para el agente.

- **Campos:** «ID de la hoja de cálculo» y «Pestaña y rango inicial».

### Integraciones externas

#### Enviar a webhook (n8n)

Envía el lead completo, en JSON, a una URL de webhook: contacto, datos recolectados, etapa y último mensaje.

- **Campos:** «URL del webhook» (obligatoria), «Nombre del evento» (opcional) y «Secreto para firmar el envío» (opcional).
- La URL debe ser **pública**: se rechazan direcciones de red interna.
- Con secreto, el envío va **firmado con HMAC** en las cabeceras. Detalle y ejemplo de verificación en [Webhooks](/docs/api/webhooks) y [n8n](/docs/integraciones/n8n).

### Tabla resumen

| Categoría | Acción | Campos principales |
| --- | --- | --- |
| Mensajes automáticos | Bienvenida, Seguimiento, Promoción, Recordatorio | Instrucciones para la IA |
| Mensajes automáticos | Enviar archivo | Archivo, nombre, texto opcional |
| Mensajes automáticos | Plantilla aprobada de Meta | Plantilla y valores de variables |
| Etiquetado | Asignar etiqueta | Etiquetas |
| Etiquetado | Cambiar estado del lead | Nueva etapa |
| Recolección de datos | Recolectar datos | Datos estándar y hasta 5 personalizados |
| Notificaciones | Avisar al equipo | Texto del aviso |
| Notificaciones | Notificar por Telegram | Texto y chat opcionales |
| Transferencia | Escalar a humano / Transferir a agente | Agente y nota interna |
| Google Sheets | Exportar a Google Sheets | Hoja, pestaña, formato de fila |
| Google Sheets | Consultar Google Sheets | Hoja y pestaña |
| Integraciones externas | Enviar a webhook (n8n) | URL, evento, secreto |


## Flujos, recetas listas para usar

> Ocho flujos completos con su disparador, su acción y los detalles que evitan sorpresas. Todos usan solo lo que el motor ejecuta hoy.
Fuente: https://orkestaliq.com/docs/flujos/recetas

Cada receta indica el **Cuando**, el **Hacer** y la configuración. Adáptala a tu negocio. Antes de dejar cualquiera activa, pruébala con un contacto de prueba.

### 1. Bienvenida a cada lead nuevo

**Para qué:** saludar y presentar lo esencial en cuanto alguien escribe por primera vez.

| | |
| --- | --- |
| **Cuando** | Estado del contacto → Nuevo lead |
| **Hacer** | Mensajes automáticos → Bienvenida |
| **Instrucciones para la IA** | «Da la bienvenida a (tu negocio), menciona que atendemos de lunes a sábado de 9:00 a 19:00 y pregunta en qué podemos ayudar.» |

**Detalles:** «Nuevo lead» corre **una sola vez por conversación**. La instrucción es lo que la IA debe comunicar; ella lo redacta con tu tono.

### 2. Seguimiento si el cliente deja de contestar

**Para qué:** recuperar conversaciones que se enfriaron, sin insistir de más.

| | |
| --- | --- |
| **Cuando** | Tiempo / demora del cliente → Inactividad prolongada: 2 días |
| **Filtro** | Solo si el contacto tiene la etiqueta `interesado` |
| **Política** | Máximo de seguimientos: 1 · Hora de inicio 10:00 · Hora de fin 19:00 · Zona horaria: Ciudad de México |
| **Hacer** | Mensajes automáticos → Seguimiento |
| **Instrucciones para la IA** | «Pregunta amablemente si sigue interesado en lo que cotizó. No mandar a quien ya pagó o ya compró.» |

**Detalles:** si la condición escrita en la instrucción no se cumple, la IA **no envía nada**. Es un mensaje que inicia tu negocio: pasadas 24 horas del último mensaje del cliente, WhatsApp solo lo entrega como [plantilla aprobada](/docs/canales/reglas-de-whatsapp). Si tu seguimiento cae fuera de la ventana, usa **Plantilla aprobada de Meta** en lugar de la IA.

### 3. Recordatorio de cita con plantilla

**Para qué:** reducir inasistencias.

| | |
| --- | --- |
| **Cuando** | Citas → Antes de una cita: 24 horas |
| **Hacer** | Mensajes automáticos → Plantilla aprobada de Meta |
| **Plantilla** | Una plantilla de categoría *utilidad* con variables para el nombre y la hora, aprobada por Meta |

**Detalles:** requiere [Google Calendar](/docs/integraciones/google-calendar) conectado. Si la cita se reagenda, el aviso se recalcula solo. **No uses un mensaje libre**: a esa hora la ventana de 24 horas casi siempre está cerrada.

### 4. Avisar al equipo cuando se agenda una cita

**Para qué:** que ventas sepa en el momento.

| | |
| --- | --- |
| **Cuando** | Citas → Se agendó una cita |
| **Hacer** | Notificaciones → Notificar por Telegram |
| **Texto del aviso** | «Nueva cita agendada.» |

**Detalles:** el aviso incluye la fecha, hora y duración de la cita. Requiere Telegram en modo **Notificaciones** o **Ambos** con un Chat ID. Si prefieres que llegue a la campana y como notificación push, usa **Avisar al equipo**.

### 5. Atención prioritaria cuando el cliente está molesto

**Para qué:** que alguien vea de inmediato los casos críticos.

Dos reglas en el mismo flujo:

| Regla | Cuando | Hacer |
| --- | --- | --- |
| A | Mensaje entrante → Sentimiento detectado: Negativo | Etiquetado → Asignar etiqueta: `atención prioritaria` |
| B | Mensaje entrante → Sentimiento detectado: Negativo | Notificaciones → Avisar al equipo: «Cliente molesto, revisar ya» |

**Detalles:** este flujo **no pausa la IA ni pasa el chat a una persona**. Si además quieres eso, crea una [regla de escalamiento](/docs/agente/relevo-humano) con «Pausar a la IA» y «Asignar a humano».

### 6. Código de promoción

**Para qué:** responder a quien escribe un código de una campaña.

| | |
| --- | --- |
| **Cuando** | Mensaje entrante → Contiene palabra clave: `PROMO20` |
| **Hacer** | Mensajes automáticos → Enviar archivo |
| **Archivo** | La imagen o PDF de la promoción (JPG/PNG hasta 5 MB, o documento hasta 14 MB) |

**Detalles:** al ser un envío por mensaje del cliente, se manda **una sola vez por conversación**. Puedes añadir una segunda regla con el mismo disparador y la acción **Asignar etiqueta** `promo20` para medir quién la usó.

### 7. Recolectar el presupuesto de cualquier contacto

**Para qué:** completar la ficha sin formularios.

| | |
| --- | --- |
| **Cuando** | Mensaje entrante → Según el contexto (IA): «El cliente menciona cuánto quiere gastar o su presupuesto» |
| **Hacer** | Recolección de datos → Recolectar datos |
| **Campo personalizado** | «Presupuesto», pista: «el presupuesto aproximado que menciona el cliente» |

**Detalles:** usa «Según el contexto (IA)» y no «Nuevo lead» para que funcione con **cualquier** contacto, no solo con los nuevos. Solo se guarda lo que el cliente dice de forma explícita.

### 8. Mandar cada lead calificado a tu hoja de cálculo y a tu CRM

**Para qué:** que los leads buenos lleguen solos a donde trabaja tu equipo.

| Regla | Cuando | Hacer |
| --- | --- | --- |
| A | Estado del contacto → Se asignó una etiqueta: `calificado` | Google Sheets → Exportar a Google Sheets (formato: Lead estándar) |
| B | Estado del contacto → Se asignó una etiqueta: `calificado` | Integraciones externas → Enviar a webhook (n8n) |

**Detalles:** requiere [Google Sheets](/docs/integraciones/google-sheets) conectado. El webhook envía el contacto, los datos recolectados, la etapa y el último mensaje; con secreto, va firmado. Mira [n8n](/docs/integraciones/n8n).

### Patrón: encadenar flujos con etiquetas

Una etiqueta puede ser el "interruptor" que une dos flujos:

1. **Flujo 1:** palabra clave `cotizar` → Asignar etiqueta `cotizar`.
2. **Flujo 2:** Se asignó una etiqueta `cotizar` → Avisar al equipo + Exportar a Google Sheets.

Así separas **detectar** de **actuar**, y puedes cambiar la acción sin tocar el detector. Una etiqueta puesta desde la API dispara el flujo 2 igual.

### Antes de activar un flujo

- [ ] ¿La acción necesita una integración? Conéctala primero.
- [ ] ¿El mensaje lo inicia tu negocio? Revisa la ventana de 24 horas y considera una plantilla.
- [ ] ¿Cuántas veces puede dispararse? Los mensajes por palabra clave o contexto salen una vez por conversación; los de tiempo, hasta el máximo que configuraste.
- [ ] Pruébalo con un contacto de prueba y revisa etiquetas, mensajes y avisos.


# Atención y equipo


## La bandeja de conversaciones

> Cómo leer, filtrar, responder, asignar y organizar las conversaciones de todos tus canales desde un solo lugar.
Fuente: https://orkestaliq.com/docs/atencion/bandeja

**Conversaciones** es la bandeja donde tu equipo atiende. Reúne los mensajes de WhatsApp, Instagram, Messenger, Telegram y el simulador en una sola lista, ordenada por actividad reciente. Está disponible para todos los roles, pero un **Agente** solo ve las conversaciones que le asignaron: mira [Equipo y roles](/docs/atencion/equipo-y-roles).

### Cómo se organiza la pantalla

- **Lista de conversaciones** (izquierda): cada chat con su contacto, canal y último mensaje. Un indicador marca los que están **sin responder** (el último mensaje es del cliente).
- **Chat** (centro): el historial y el campo para escribir. Cada mensaje muestra quién lo mandó: **el agente de IA**, **tu equipo**, una **campaña** o el **sistema** (notas y avisos internos).
- **Detalles del cliente** (derecha): sus etiquetas, su etapa, la calidad del lead, los datos que la IA detectó, tus notas y, si conectaste WooCommerce, sus pedidos.

Un indicador arriba muestra si la conexión en tiempo real está **en vivo** o **reconectando**.

### Encontrar conversaciones

| Filtro | Qué hace |
| --- | --- |
| **Buscar** | Por nombre o teléfono |
| **Canales** | Todas, un canal concreto o el Simulador |
| **Bandejas** | Favoritas, Delegadas, Sin asignar, Resueltos, Archivados y Bloqueados |
| **Etiqueta** | Solo las conversaciones con esa etiqueta |
| **Fecha** | Cualquier fecha, solo hoy o una fecha específica |
| **Asignación** | Cualquiera, sin asignar o asignadas a mí |
| **Pendientes** | Solo donde el último mensaje es del cliente |

Cuando hay muchas, la lista carga por tramos: pulsa **Ver N conversaciones más**.

### Responder

Escribe en el campo inferior y envía. Junto al campo tienes:

| Botón | Para qué |
| --- | --- |
| **Respuestas rápidas** | Insertar un atajo guardado (ver abajo) |
| **Enviar imagen** y **Adjuntar archivo** | Mandar fotos o documentos (hasta **15 MB** por archivo) |
| **Enviar plantilla aprobada** | Escribir fuera de la ventana de 24 horas. Mira [Plantillas](/docs/campanas/plantillas) |
| **Grabar nota de voz** | Mandar un audio |
| **Insertar emoji** | Abrir el selector de emojis |
| **Responder a este mensaje** | Citar un mensaje anterior en tu respuesta |

Cada mensaje que sale muestra su estado: **Enviando**, **Enviado**, **Entregado**, **Leído** o **No se pudo entregar** (con el motivo). Los significados y los errores más comunes están en [Reglas de WhatsApp](/docs/canales/reglas-de-whatsapp#estado-de-entrega-de-cada-mensaje).

> [!IMPORTANTE]
> En WhatsApp, pasadas 24 horas desde el último mensaje del cliente, el chat solo permite plantillas. El campo te avisa cuánto falta antes de que cierre la ventana.

> [!CUIDADO]
> Si recibes el aviso «Se publicó una versión nueva de Orkestal y este mensaje NO se envió», **recarga la página** y vuelve a enviar: Orkestal te deja el texto en el campo. Pasa si tenías la pestaña abierta durante una actualización.

#### Respuestas rápidas

Los **atajos** son mensajes guardados (con texto y, si quieres, un archivo) para no escribir lo mismo cada vez. Hay dos listas:

| Lista | Quién la ve | Quién la edita |
| --- | --- | --- |
| **Del equipo** | Todos | Solo un administrador |
| **Mis atajos** | Solo tú | Solo tú |

Cada lista admite hasta **50** atajos. Para crear uno, abre **Respuestas rápidas** y elige **Nuevo atajo mío** o **Nuevo del equipo**; ponle nombre, escribe el mensaje (opcional si agregas un archivo) y guarda. Los atajos no están disponibles en el simulador.

### Atender, asignar y organizar

Estas acciones están en los botones del chat y en su menú:

| Acción | Qué hace |
| --- | --- |
| **Asignarme** | Tomas la conversación |
| **Delegar** | Se la entregas a otra persona del equipo (solo Admin y Manager) |
| **Delegación masiva** | Asignas varias conversaciones filtradas a una misma persona |
| **Desasignar** | La devuelves a «Sin asignar» |
| **Marcar como resuelto / Reabrir** | La mueve a la bandeja Resueltos, o la regresa |
| **Marcar como favorito** | La agrega a la bandeja Favoritas |
| **Archivar / Desarchivar** | La saca de la bandeja principal sin borrarla |
| **Bloquear / Desbloquear contacto** | Marca al contacto como bloqueado y lo manda a la bandeja Bloqueados |
| **Marcar como no leído / leído** | Para recordar volver a ella |
| **Eliminar conversación** | **Borra todos sus mensajes y no se puede deshacer** |

Al delegar, la persona ve la conversación en su bandeja y recibe una notificación. En el selector de delegación, quien no ha marcado que está disponible aparece como **desconectado**: mira [Equipo y roles](/docs/atencion/equipo-y-roles#disponibilidad-y-conexion).

### La IA en cada chat

- **IA Global**: el interruptor general del agente.
- **Pausar IA para este chat / Activar IA para este chat**: controla solo esa conversación.

Cuando alguien de tu equipo responde, la IA se pausa sola en ese chat. Todo el detalle está en [Relevo humano](/docs/agente/relevo-humano).

### Panel de detalles del cliente

- **Etiquetas**: agrega o quita etiquetas. El selector separa las del **catálogo oficial**, las que vienen de **IA y flujos** y las **comunes**. Con el [modo estricto](/docs/atencion/etiquetas-y-etapas#modo-estricto) solo se permiten las del catálogo. Las etiquetas con rayo las pusieron los flujos.
- **Estado (etapa)**: en qué punto del recorrido de venta está. Mira [Etiquetas y etapas](/docs/atencion/etiquetas-y-etapas).
- **Lead Score (ORCA)**: la calidad estimada del lead, de Tier A a D.
- **Datos del contacto**: nombre, correo, producto de interés y otros que la IA detecta se muestran con la indicación «Dato detectado por la IA. Puedes corregirlo.» Haz clic en un dato para editarlo.
- **Notas**: un espacio libre por conversación que se guarda solo a medida que escribes.
- **Pedidos de WooCommerce**: si conectaste tu tienda, los pedidos del cliente aparecen aquí.

### Notificaciones

Cuando una conversación se te asigna o un cliente necesita atención humana, recibes una notificación. Mira [Notificaciones](/docs/atencion/notificaciones).


## Contactos (CRM)

> Tu base de clientes y prospectos: buscar, filtrar, agregar, importar desde Excel o CSV, exportar y repartir entre tu equipo.
Fuente: https://orkestaliq.com/docs/atencion/contactos-y-crm

**Contactos (CRM)** es la lista de todas las personas que han hablado con tu negocio o que tú cargaste. Cada contacto tiene su ficha, sus etiquetas, su etapa y su conversación. Un contacto se crea solo cuando alguien te escribe por primera vez; también puedes agregarlos o importarlos tú.

Dentro de la sección hay dos vistas, que cambias con el selector **Vista de CRM**: **Contactos** (la lista) y **Oportunidades** (el tablero comercial; mira [Oportunidades](/docs/atencion/oportunidades)).

### Resumen y filtros

Arriba verás cuatro contadores: **Total de contactos**, **Contactos abiertos**, **Requieren humano** y **Actividad hoy**.

Puedes buscar por **nombre o teléfono** y filtrar por **canal**, **estatus**, **fecha** y **etiqueta**. Los filtros activos se muestran como chips que puedes quitar de uno en uno. Con **Seleccionar todos los filtrados** actúas sobre todo el resultado a la vez.

### La ficha de un contacto

- **Nombre, teléfono y correo.**
- **Canal** de origen.
- **Etiquetas.** Las que puso un flujo se distinguen con un rayo: «Etiqueta generada por flujo de automatización». Con **Gestionar etiquetas** abres el catálogo.
- **Producto de interés** y otros datos que la IA detecta de la conversación. Aparecen con la marca «Dato detectado por la IA. Puedes corregirlo.» y se editan con un clic.
- **Agente asignado.**
- **Ver conversación** abre su chat (o su chat de Telegram).

### Agregar un contacto

1. Pulsa para agregar uno nuevo.
2. Escribe el nombre y el teléfono. Para WhatsApp escribe el número **con lada de país**, por ejemplo `+52 55 1234 5678`.
3. Elige el canal. **Otro / solo CRM** guarda a la persona sin un canal por el que Orkestal pueda escribirle (por ejemplo, un contacto sin teléfono).
4. Guarda. Si el teléfono ya existía, Orkestal **actualiza la ficha existente** en lugar de duplicarla: «Ese teléfono ya estaba registrado, se actualizó su ficha.»

> [!IMPORTANTE]
> Crear un contacto con el teléfono mal escrito (sin lada, con un dígito de menos) puede abrir **un segundo chat** cuando el cliente responda desde su número real. Revisa siempre el formato internacional.

### Importar desde Excel o CSV

1. Pulsa para importar y arrastra tu archivo, o elígelo. Acepta **CSV y Excel**, de hasta **10 MB**.
2. Orkestal reconoce las columnas por su encabezado, en español o inglés:

| Dato | Encabezados reconocidos (ejemplos) |
| --- | --- |
| Nombre | nombre, nombre completo, name |
| Teléfono | teléfono, tel, celular, móvil, whatsapp, phone |
| Correo | correo, email |
| Etiquetas | etiquetas, tags |
| Agente asignado | agente asignado, responsable, propietario, assigned to (nombre o correo) |

3. Al terminar, Orkestal resume qué pasó: cuántos contactos eran nuevos, cuántos **ya existían** (se omiten), cuántos quedaron **solo en el CRM** por no tener teléfono, y cuántos se descartaron por no traer nombre, correo ni teléfono o por estar repetidos en el archivo.

Si el archivo trae una columna de **agente asignado**, cada contacto queda asignado a esa persona del equipo.

> [!CONSEJO]
> Importa primero un archivo de 5 o 10 filas para confirmar que las columnas se leyeron bien, y después el archivo completo.

### Exportar

El botón de exportar descarga tus contactos en un archivo. Si no hay contactos que exportar, Orkestal te lo indica.

### Repartir contactos entre tu equipo

Con **Asignación masiva** seleccionas varios contactos y los delegas a una misma persona. La persona recibe una notificación («Te han asignado el contacto…»). Solo Admin y Manager pueden asignar. Para el reparto automático, mira [Equipo y roles](/docs/atencion/equipo-y-roles#asignacion-automatica).

### Estatus y etapas

El estatus de un contacto (**Nuevo lead**, **Venta en proceso**, **Cerrado ganado**, **Cerrado perdido**, entre otros) se puede cambiar desde la lista. Está ligado a la etapa de la conversación. Mira [Etiquetas y etapas](/docs/atencion/etiquetas-y-etapas).

### Qué pasa con un contacto que escribe de nuevo

Si una persona que ya existe vuelve a escribir, Orkestal la reconoce por su identificador del canal (en WhatsApp, su número) y continúa en **el mismo chat**: no se crea otro contacto. Las campañas excluyen automáticamente a quien pidió la baja. Mira [Campañas](/docs/campanas/campanas).


## Etiquetas, etapas y calidad del lead

> Cómo clasificar a tus contactos con etiquetas, seguir su avance con etapas, controlar qué etiquetas puede poner la IA y leer la calificación ORCA.
Fuente: https://orkestaliq.com/docs/atencion/etiquetas-y-etapas

Orkestal usa tres formas distintas de clasificar a un contacto. Sirven para cosas diferentes:

| | Qué es | Quién lo pone | Para qué sirve |
| --- | --- | --- | --- |
| **Etiqueta** | Una marca libre («VIP», «cotizado») | Tu equipo, los flujos, las reglas de escalamiento, la API o la IA | Segmentar, filtrar y disparar flujos |
| **Etapa** | El punto del recorrido de venta | La IA, los flujos o tu equipo | Saber en qué va cada conversación |
| **Calidad (ORCA)** | Una calificación automática, Tier A–D | Orkestal | Priorizar a quién atender primero |

### Etiquetas

#### El catálogo

Las etiquetas se administran en el **Catálogo de Etiquetas** (en **Configuración**). Para cada etiqueta defines:

| Campo | Qué hace |
| --- | --- |
| **Nombre** | Ej.: «Cotizado», «Cliente VIP», «Prospecto» |
| **Criterio de uso** | Cuándo debe aplicarse. Sirve de guía para tu equipo y para la IA |
| **La IA puede asignar esta etiqueta** | Si está activado, la IA la pondrá **solo cuando el análisis de la conversación la considere pertinente**. Si no, queda **solo para personas** |
| **Vista previa** | Cómo se verá en pantalla |

Desde el catálogo también puedes **editar**, **eliminar** y **fusionar etiquetas duplicadas**. Al eliminar una etiqueta se desasocia automáticamente de todos los contactos que la tenían; Orkestal te dice a cuántos. Al fusionar, eliges la etiqueta que se queda y los contactos de las demás pasan a ella.

#### Modo estricto

El interruptor **Modo estricto (solo admins)** decide quién puede crear etiquetas nuevas:

- **Estricto:** solo los administradores crean etiquetas. En cualquier otro lugar, solo se pueden elegir las del catálogo oficial.
- **Libre:** cualquier usuario puede crear etiquetas nuevas al etiquetar.

Si tu equipo es grande, el modo estricto evita que aparezcan «VIP», «vip» y «Cliente vip» como tres etiquetas distintas.

#### La IA nunca inventa etiquetas

Orkestal garantiza que la IA **solo usa etiquetas que ya existen en tu catálogo y que tú le autorizaste** con «La IA puede asignar esta etiqueta». Si el análisis sugiere otra, se descarta. Esto vale también para lo que Orki propone.

#### Quién más pone etiquetas

- **Flujos:** la acción [Asignar etiqueta](/docs/flujos/hacer#asignar-etiqueta). Asignar una etiqueta puede disparar otros flujos.
- **Reglas de escalamiento:** aplican la etiqueta de la regla, y **Requiere humano** si activaste «Asignar a humano».
- **La API:** `POST /contacts/{id}/tags`. Las etiquetas se **suman**, nunca reemplazan a las existentes.
- **Etiquetas del sistema:** por ejemplo `nuevo_lead`, que marca a los contactos recién llegados.

#### Para qué usarlas

- **Filtrar** conversaciones, contactos y audiencias de [campañas](/docs/campanas/campanas).
- **Disparar flujos** con «Se asignó una etiqueta».
- **Condicionar** disparadores de tiempo con «Solo si el contacto tiene alguna etiqueta».

### Etapas

La etapa dice en qué punto del recorrido de venta está una conversación. Hay doce:

| Etapa | Significa |
| --- | --- |
| Nuevo lead | Acaba de escribir |
| En proceso | La conversación está en curso |
| Interesado | Mostró interés |
| Calificado | Mostró interés concreto |
| En seguimiento | Se le da seguimiento |
| Negociación | Se están discutiendo condiciones |
| Oferta enviada | Ya recibió una propuesta |
| Vendido | La venta se cerró |
| Declinado | No compró |
| No responde | Dejó de contestar |
| Requiere atención humana | Una persona debe intervenir |
| Soporte | Necesita ayuda posterior a la compra |

La etapa cambia por tres vías: el **análisis de la IA** a medida que avanza la conversación, la acción **Cambiar estado del lead** de un [flujo](/docs/flujos/hacer) (que puede fijar Nuevo lead, En proceso, Interesado, Calificado, En seguimiento, Negociación, Vendido o Declinado), y **tú** desde la lista de contactos o el panel del chat. Un flujo con «Cambió la etapa del lead» reacciona cuando un flujo mueve la etapa.

> [!NOTA]
> La etapa de una **conversación** no es lo mismo que una **oportunidad** del CRM. La etapa describe el chat; la oportunidad describe una posible venta con valor y responsable. Mira [Oportunidades](/docs/atencion/oportunidades).

### Calidad del lead (ORCA)

En el panel del cliente verás **ORCA «número» · Tier «letra»**. Es una **estimación automática** de qué tan bueno es el lead, de 0 a 100, que combina cuatro dimensiones:

| Dimensión | Qué mide |
| --- | --- |
| **O**bjetivo | La necesidad o intención de compra detectada |
| **R**itmo | La urgencia y el avance de la conversación |
| **C**ompatibilidad | Qué tan identificado está el lead (datos de contacto) y qué tanto encaja |
| **A**finidad | La relación: sentimiento y profundidad de la conversación |

| Tier | Puntuación |
| --- | --- |
| A | 75 o más |
| B | 50 a 74 |
| C | 25 a 49 |
| D | Menos de 25 |

ORCA es una **guía de prioridad**, no un dato que capturó el cliente ni una promesa de venta. Úsala para decidir a quién escribirle primero.

### Que la IA llene la ficha del contacto

En el Catálogo de Etiquetas hay también un interruptor para que la IA **llene la ficha del contacto con lo que el cliente comparta** (nombre, correo, producto de interés). Apagado, la IA deja de llenar la ficha. Los datos detectados se marcan para que los corrijas.


## Oportunidades

> El tablero comercial del CRM: posibles ventas con valor, etapa y siguiente acción, separadas del estado de la conversación.
Fuente: https://orkestaliq.com/docs/atencion/oportunidades

Una **oportunidad** (*deal*) es una **posible venta**: tiene un título, un valor, una etapa comercial, un responsable y una siguiente acción. Vive **separada de la conversación**: un mismo contacto puede tener varias oportunidades a la vez (por ejemplo, un servicio hoy y otro el próximo mes), y una oportunidad puede apuntar al chat del que salió.

Se ven en **Contactos (CRM) → Oportunidades**, con el selector **Vista de CRM**.

> [!NOTA]
> No las confundas con la **etapa de la conversación** (Nuevo lead, Interesado, Vendido…), que describe el estado de un chat y la actualiza la IA. Las oportunidades se gestionan en este tablero. Mira [Etiquetas y etapas](/docs/atencion/etiquetas-y-etapas).

### El tablero

Muestra tus oportunidades en columnas por etapa. Arriba hay un **resumen comercial**: oportunidades abiertas, valor en curso y cuántas están **sin siguiente acción**.

| Etapa | Significa |
| --- | --- |
| **Nuevo** | Acaba de abrirse |
| **Calificado** | Confirmaste que hay interés y encaje |
| **Propuesta** | Ya enviaste una propuesta o cotización |
| **Negociación** | Están discutiendo condiciones |
| **Ganado** | Se cerró la venta |
| **Perdido** | No se concretó |

Una oportunidad abierta tiene estado **abierta**; al llegar a **Ganado** pasa a ganada, y al llegar a **Perdido**, a perdida. Cambiar de columna actualiza la etapa y Orkestal confirma con «Etapa actualizada».

### Crear una oportunidad

1. Pulsa **Nueva oportunidad**.
2. Elige el **contacto** y escribe un **nombre** para la oportunidad (obligatorios).
3. Elige la etapa inicial (Nuevo, Calificado, Propuesta o Negociación).
4. Opcionalmente indica el **valor** y la **siguiente acción**.

### El detalle de una oportunidad

Al abrir una oportunidad ves:

- Su **estado** y etapa.
- Su **valor** (en pesos mexicanos por defecto) y su **siguiente acción**, con fecha si la definiste. Una oportunidad sin siguiente acción aparece marcada: es la forma más rápida de detectar a quién se te está olvidando dar seguimiento.
- La **cotización vinculada**, si el agente armó una con [Cotización Inteligente](/docs/integraciones/cotizacion-inteligente), con su estado: **Por revisar**, **Aceptada**, **Rechazada** o **Cancelada**.
- Un enlace para **abrir la conversación vinculada**.

### Cómo se crean solas

Con [Cotización Inteligente](/docs/integraciones/cotizacion-inteligente) puedes activar la opción de **crear o actualizar la oportunidad** automáticamente cuando el agente prepara una cotización. Así tu tablero se llena con las ventas que realmente se están cotizando.

### Buenas prácticas

- **Una oportunidad por venta**, no por conversación.
- **Siempre una siguiente acción** con fecha: «Llamar el jueves», «Esperar anticipo».
- **Cierra las oportunidades** como Ganado o Perdido; el valor en curso solo es útil si el tablero está limpio.
- **El valor es una estimación** que tú capturas; no se calcula solo a partir de la conversación.


## Equipo y roles

> Cómo invitar personas, qué puede hacer cada rol, cómo funciona la disponibilidad y cómo repartir las conversaciones automáticamente.
Fuente: https://orkestaliq.com/docs/atencion/equipo-y-roles

En **Equipo** (Manager y Admin) administras a las personas que atienden contigo: quién tiene acceso, con qué rol, si están disponibles y cómo se reparten las conversaciones.

### Los tres roles

| Rol | Qué puede hacer |
| --- | --- |
| **Admin** | Acceso total, incluido **Facturación** y **Configuración** (clave de IA, etiquetas, WhatsApp). Es el único que puede dar el rol Admin |
| **Manager** | Todo lo del Agente, más **Equipo**, **Agente IA**, **Canales**, **Integraciones**, **Flujos**, **Campañas**, **Base de Conocimiento**, **Inventario**, **Archivos Contexto** y **Orki**. No ve Facturación ni Configuración |
| **Agente** | Atiende conversaciones. Ve el **Panel**, **Conversaciones** y **Contactos**, y **solo las conversaciones que le asignaron** |

Reglas importantes:

- Un **Agente solo ve sus conversaciones asignadas**. No ve las de sus compañeros ni las que están sin asignar.
- Un **Agente no puede delegar** conversaciones a otras personas; solo Admin y Manager.
- Un **Manager puede dar los roles Manager y Agente, pero nunca Admin**, y no puede modificar ni quitar a un Admin.
- Un Admin puede hacer cualquier cambio sobre cualquier miembro.

> [!CONSEJO]
> Da a cada persona el rol mínimo que necesita. Un vendedor que solo atiende chats debe ser **Agente**: así no ve conversaciones ajenas ni puede cambiar la configuración.

### Invitar a una persona

1. En **Equipo**, pulsa **Invitar miembro**.
2. Escribe el **nombre completo** y el **correo de trabajo**, y elige el **rol**.
3. Pulsa **Enviar invitación**. La persona recibe un correo para crear su cuenta con el rol asignado.

La persona aparece como **invitada** hasta que acepta. Desde el menú de acciones de un miembro puedes **Reenviar invitación** (si el enlace venció) o **Cancelar invitación**.

> [!NOTA]
> La persona invitada debe usar el **enlace de su correo de invitación** para establecer su contraseña. Si se registra por su cuenta desde la página principal, creará **una cuenta distinta** con su propio negocio, no entrará a tu equipo. Si Orkestal te muestra una **contraseña temporal** al crear la cuenta, entrégala por tu propio canal: **no se vuelve a mostrar**.

El número de miembros que puedes tener depende de tu plan. Mira [Planes y facturación](/docs/cuenta/planes-y-facturacion).

### Gestionar miembros

Desde la lista de miembros (búsqueda por nombre o correo, vista de tabla) y su menú de acciones:

| Acción | Qué hace |
| --- | --- |
| **Cambiar rol** | Cambia el rol tras pedirte confirmación |
| **Marcar como desconectado** | La persona deja de recibir conversaciones nuevas hasta que vuelva a conectarse |
| **Reenviar / Cancelar invitación** | Para invitaciones pendientes |
| **Quitar acceso a esta cuenta** | Le quita el acceso a esta cuenta pero conserva su propia cuenta y el resto de sus accesos (para personas que trabajan en varias cuentas) |
| **Eliminar miembro** | Lo quita del equipo y **pierde el acceso de inmediato** |
| **Exportar miembros** | Descarga la lista completa |

Arriba verás cuántos miembros tienes, cuántos están **disponibles ahora** y cómo se distribuyen los roles.

#### Personas con acceso a varias cuentas

Una persona puede trabajar en varias subcuentas de una misma matriz, con un rol distinto en cada una. En su fila verás **Cuentas con acceso** y su rol aplica **por cuenta**. Mira [Agencias](/docs/cuenta/agencias).

### Disponibilidad y conexión

Cada persona tiene un interruptor personal de **disponible / desconectado**. Es la señal que usa Orkestal para saber a quién puede repartirle conversaciones. «Conectado» significa solo eso: que la persona se marcó disponible, no que tenga la pestaña abierta en este momento.

- En los selectores de **Delegar**, quien no ha hecho check-in aparece como **«Desconectado, no ha hecho check-in»**.
- Un Admin o Manager puede **desconectar a un miembro** a mano, con las mismas reglas de arriba (un Manager no puede desconectar a un Admin). A la persona le llega una notificación.
- Desconectar **no mueve las conversaciones** que la persona ya tenía asignadas: solo deja de recibir nuevas.

#### Desconexión automática por inactividad

En **Equipo → Asignación automática → Desconectar por inactividad** eliges cuánto tiempo sin usar el panel desconecta a una persona: **apagado** (lo normal), **15 min, 30 min, 1, 2, 4 u 8 horas**.

- Cuenta como actividad una **interacción real** con el panel (clic, tecla, desplazamiento, toque), no tener la pestaña abierta.
- La desconexión puede tardar unos minutos más que el tiempo elegido.
- Quien trabaja en varias cuentas tiene una sola disponibilidad: aplica el umbral más corto de sus cuentas.
- Al conectarse con el botón, el reloj se reinicia.

### Asignación automática

En **Equipo → Asignación automática** decides cómo se reparten las conversaciones que necesitan a una persona. Cuando un cliente necesita atención humana, la conversación se asigna sola al asesor **disponible** con **menos conversaciones abiertas**. Los chats que la IA resuelve sola no se reparten a nadie.

| Ajuste | Qué hace |
| --- | --- |
| **Asignación automática** (interruptor principal) | Encendido, las conversaciones **escaladas** por una [regla](/docs/agente/relevo-humano) se reparten solas entre quienes están disponibles. Apagado, quedan en **Sin asignar** |
| **Asignar también cada conversación nueva** | Además, en cuanto un contacto escribe por primera vez, su conversación se asigna sola al asesor disponible con menos conversaciones, sin esperar a que la IA escale. Pensado para cuentas donde el equipo atiende directamente. **Necesita el interruptor principal encendido** y viene apagado por defecto |
| **Desconectar por inactividad** | Ver arriba |

Cosas que conviene saber:

- Solo entran al reparto los miembros marcados como **Disponible**.
- Si **no hay nadie disponible**, la conversación queda en **Sin asignar** para que la tome quien pueda: no se pierde ninguna.
- Si una **regla de escalamiento nombra a una persona concreta**, se respeta aunque el reparto automático esté apagado.
- Solo un Admin o Manager puede cambiar estos ajustes.

> [!IMPORTANTE]
> Si nadie está disponible, la conversación queda **sin asignar** y espera a que alguien la tome. Pide a tu equipo que marque que está disponible al empezar su turno, o usa la desconexión automática para que las personas inactivas no reciban chats.

### Roles y la API

Las claves de la [API pública](/docs/api/autenticacion) tienen sus propios permisos y las administra un Admin. No heredan el rol de quien las creó.


## Notificaciones y avisos

> Cómo te enteras de que un cliente necesita a una persona: campana, notificaciones push, Telegram y los avisos del panel.
Fuente: https://orkestaliq.com/docs/atencion/notificaciones

Orkestal te avisa por varios caminos cuando algo requiere tu atención. Conviene activar al menos uno, sobre todo si la IA escala conversaciones a tu equipo.

### La campana

El ícono de **Notificaciones** del panel reúne los avisos de la cuenta. Ahí llegan, entre otros:

- Conversaciones o contactos que te **asignaron**.
- Clientes que **necesitan atención humana**.
- Avisos de **facturación** (pago rechazado, fin de la prueba).
- Avisos de las integraciones, como el reporte semanal de sincronización de inventario con Mercado Libre.
- Los avisos que genera la acción **Avisar al equipo** de un [flujo](/docs/flujos/hacer#avisar-al-equipo).

Pulsa **Marcar leídas** para limpiar la lista.

### Notificaciones push

Las notificaciones push te llegan al celular o a la computadora aunque no tengas Orkestal abierto.

#### Activarlas

1. Ve a **Configuración**.
2. Busca **Avisos de atención humana** y activa el interruptor. Se envía una notificación cada vez que un cliente necesita un agente, y también en las alertas de facturación.
3. Acepta el permiso del navegador cuando lo pida.
4. Usa **Enviar notificación de prueba** para comprobar que llega. Si no tienes una suscripción activa en ese dispositivo, activa primero el interruptor.

En **Conversaciones** también puede aparecer una tarjeta **Activar avisos** que hace lo mismo.

#### En iPhone o iPad

Requieren **iOS 16.4 o posterior** y abrir Orkestal desde el ícono de la pantalla de inicio:

1. En Safari, toca **Compartir → Agregar a pantalla de inicio**. Si aparece «Abrir como app web», déjalo activado.
2. Abre Orkestal desde su ícono e inicia sesión.
3. En **Conversaciones**, toca la tarjeta **Activar avisos** y elige **Permitir**.

#### Si las notificaciones están bloqueadas

- **En el celular:** ve a Ajustes → Notificaciones → Orkestal y activa «Permitir notificaciones». Vuelve a la app y recarga la pantalla.
- **En el navegador:** permite las notificaciones desde la configuración del sitio y recarga la pantalla.
- Si el navegador no admite notificaciones push, prueba con uno actualizado.

Las notificaciones push se activan **por dispositivo**: si usas Orkestal en el celular y en la laptop, actívalas en ambos.

### Telegram para el equipo

Si conectas un bot de Telegram en modo **Notificaciones** o **Ambos**, los avisos de **«Requiere humano»** y los de los flujos con **Notificar por Telegram** llegan a un grupo o chat de tu equipo. Es útil para avisos que deben verse aunque nadie esté mirando el panel. Mira [Telegram](/docs/canales/telegram).

### Avisos dentro del panel

Algunos problemas aparecen como una franja destacada arriba del panel hasta que los resuelves:

| Aviso | Qué indica | Dónde se resuelve |
| --- | --- | --- |
| **Tu agente de IA no está activo** | Falta la clave de IA | [Clave de IA](/docs/agente/clave-de-ia) |
| **Tu último pago fue rechazado** | Falló el cobro; hay riesgo de restricción | [Planes y facturación](/docs/cuenta/planes-y-facturacion) |
| **Cuenta suspendida por falta de pago** | El agente dejó de responder a tus clientes | [Planes y facturación](/docs/cuenta/planes-y-facturacion#cuenta-suspendida-por-falta-de-pago) |
| **WhatsApp no está recibiendo mensajes** (y variantes) | Meta dejó de entregar, perdió la autorización o redirigió los mensajes | [WhatsApp](/docs/canales/whatsapp#si-dejas-de-recibir-mensajes) |
| **Se agotaron / te quedan pocos mensajes gratis de WhatsApp** | Consumo de la bolsa mensual de Meta | [Reglas de WhatsApp](/docs/canales/reglas-de-whatsapp#mensajes-gratis-cada-mes) |
| **Hay una versión nueva de Orkestal** | Se publicó una actualización | Pulsa **Recargar** |

> [!CONSEJO]
> Cuando aparece **«Hay una versión nueva de Orkestal»**, recarga cuanto antes. Si no lo haces, un mensaje que escribas desde la pestaña vieja puede no enviarse.

### Recomendación para equipos

1. Que **cada persona active las notificaciones push** en su celular.
2. Que el administrador conecte **Telegram** en modo Ambos para un grupo del equipo.
3. Que cada quien marque que está **disponible** al empezar su turno: sin eso, [la asignación automática](/docs/atencion/equipo-y-roles#asignacion-automatica) no le reparte conversaciones.


# Campañas y plantillas


## Plantillas de WhatsApp

> Qué es una plantilla, cómo crearla y mandarla a revisión de Meta, cómo sincronizarlas y cómo usarlas en el chat, en flujos y en campañas.
Fuente: https://orkestaliq.com/docs/campanas/plantillas

Una **plantilla** es un mensaje de WhatsApp con formato fijo que **Meta debe aprobar** antes de poder usarse. Es la **única forma de escribirle a un cliente fuera de la ventana de 24 horas** (o de 72 si llegó desde un anuncio): recordatorios, seguimientos, avisos y campañas masivas. Mira [Reglas de WhatsApp](/docs/canales/reglas-de-whatsapp).

Se administran en **Campañas → Plantillas**. Requieren tener WhatsApp conectado.

### La lista de plantillas

Muestra las plantillas de tu cuenta de WhatsApp Business, tal como están en Meta:

| Columna | Qué indica |
| --- | --- |
| **Nombre** | El nombre interno |
| **Categoría** | Utility (utilidad) o Marketing |
| **Idioma** | El idioma con que se aprobó |
| **Estado** | Aprobada, Pendiente, Rechazada, Pausada o Deshabilitada |

También verás el **quality score** de la plantilla que calcula Meta según cómo la reciben los clientes.

Solo las **Aprobadas** se pueden usar para enviar. Si acabas de crear o editar una en Meta y no aparece, pulsa **Sincronizar con Meta**: Orkestal te dice cuántas plantillas trajo.

### Crear una plantilla

1. En **Campañas → Plantillas**, pulsa **Nueva plantilla**.
2. Completa:

| Campo | Qué poner |
| --- | --- |
| **Nombre interno** | Solo minúsculas, números y guion bajo. Ej.: `recordatorio_cita` |
| **Categoría** | **Utility** (confirmaciones, recordatorios, avisos de un pedido o cita) o **Marketing** (promociones y ofertas) |
| **Idioma** | Español (MX), Español o English (US) |
| **Encabezado** (opcional) | Hasta 60 caracteres. En esta primera versión **no admite variables** |
| **Mensaje** | Hasta 1,024 caracteres. Puede llevar variables |
| **Pie** (opcional) | Hasta 60 caracteres |
| **Botones** (opcional) | Hasta tres: respuestas rápidas o enlaces. El texto de cada botón admite hasta 25 caracteres |

3. Si el mensaje tiene variables, Orkestal te pide un **ejemplo para cada una**. Meta los usa para revisar la plantilla; **no se envían a clientes**.
4. Pulsa **Enviar a revisión**. La plantilla queda **Pendiente** hasta que Meta responda.

#### Variables

Una variable es un hueco que se llena al enviar. Puedes usar dos estilos, pero **no mezclarlos** en la misma plantilla:

- **Con nombre:** `{{nombre}}`, `{{fecha}}`. Más fáciles de leer.
- **Numeradas:** `{{1}}`, `{{2}}`.

Ejemplo: «Hola {{nombre}}, te recordamos tu cita para {{fecha}}.»

> [!IMPORTANTE]
> Debes dar **un ejemplo por cada variable**. Si falta alguno, Orkestal no deja enviar la plantilla.

#### La categoría importa

Meta puede **recategorizar** una plantilla si su contenido parece de otra categoría (por ejemplo, una promoción enviada como Utility). La categoría determina el **costo por mensaje** que cobra Meta y qué tipo de contenido es aceptable.

| Si tu mensaje… | Elige… |
| --- | --- |
| Confirma, recuerda o informa algo que el cliente ya espera | **Utility** |
| Promociona, ofrece o invita a comprar | **Marketing** |

### Si Meta la rechaza

El estado cambia a **Rechazada**. Causas comunes: contenido que parece promocional en una Utility, variables sin contexto, enlaces acortados, errores de formato o promesas que Meta considera engañosas. Ajusta el texto y crea una nueva con otro nombre. Las plantillas aprobadas no se editan libremente: si necesitas cambiar una, crea una nueva versión.

Si Meta devuelve un error al crearla, Orkestal te muestra el motivo, con el código de error.

### Usar una plantilla

| Dónde | Cómo |
| --- | --- |
| **En el chat** | Botón **Enviar plantilla aprobada**: eliges la plantilla, completas las variables (puedes usar «Usar el nombre del contacto»), ves cómo la recibirá el cliente y pulsas **Enviar**. Queda registrada en la conversación |
| **En un flujo** | La acción **Plantilla aprobada de Meta**. Mira [Flujos: Hacer](/docs/flujos/hacer#plantilla-aprobada-de-meta) |
| **En una campaña** | Al armar la campaña eliges una plantilla aprobada. Mira [Campañas](/docs/campanas/campanas) |
| **Por la API** | `POST /messages` con `template`, y `GET /templates` para listarlas. Mira [Referencia](/docs/api/referencia) |

### Buenas prácticas

1. **Redacta como una persona.** Los mensajes impersonales o genéricos reciben más bloqueos y reportes.
2. **Una intención por plantilla.** Mezclar recordatorio y promoción invita a que Meta la recategorice.
3. **Pon variables solo donde hacen falta.** Mensajes casi todo variable suelen rechazarse.
4. **Incluye una forma de salir** en las de marketing («Responde BAJA para dejar de recibir mensajes»). Quienes responden STOP, BAJA o CANCELAR se excluyen automáticamente de tus campañas.
5. **Vigila la calidad.** Si los clientes reportan tus mensajes, la calidad de tu número baja y Orkestal bloquea tus campañas.


## Campañas masivas

> Cómo armar y programar un envío a muchos contactos por WhatsApp o Telegram, qué cuesta, qué lo bloquea y cómo medir el resultado.
Fuente: https://orkestaliq.com/docs/campanas/campanas

Una **campaña** es un mensaje que mandas a muchos contactos a la vez: una promoción, un aviso, el lanzamiento de algo nuevo. Se administran en **Campañas** (Manager y Admin).

Antes de empezar: en WhatsApp, un envío masivo **solo puede usar [plantillas aprobadas](/docs/campanas/plantillas)** por Meta. En Telegram escribes el mensaje libremente.

### El semáforo de calidad

Arriba de Campañas verás un indicador con la **calidad de tu número de WhatsApp**, que calcula Meta con base en los bloqueos, reportes de spam y quejas de los últimos 7 días:

| Color | Qué pasa |
| --- | --- |
| **Verde** | Todo funciona: puedes enviar |
| **Amarillo / Rojo** | Orkestal **bloquea el envío de campañas** (también las ya programadas) y avisa a los administradores. Se levanta solo cuando Meta vuelve a marcar el número en verde |
| **Sin dato reciente** | Sincroniza la calidad antes de un envío importante |

Junto al color se muestra tu límite de conversaciones nuevas por día (por ejemplo «hasta 1,000/24h»). Detalle en [Reglas de WhatsApp](/docs/canales/reglas-de-whatsapp#calidad-de-tu-numero).

### Crear una campaña

Pulsa **Nueva campaña**. El asistente tiene tres pasos.

#### 1. Audiencia

| Campo | Qué hace |
| --- | --- |
| **Nombre de la campaña** | Ej.: «Promoción Buen Fin 2026». Solo lo ves tú |
| **Canal de entrega** | **WhatsApp** (requiere plantilla aprobada; costo estimado, varía por categoría y país) o **Telegram** (inmediato, sin costo por mensaje) |
| **Filtrar por estatus** | Todos, o solo contactos activos, cerrados o archivados |
| **Filtrar por etiquetas** | Solo contactos con esas etiquetas. **Si no eliges ninguna, se envía a toda tu base de contactos del canal** |
| **País** | Filtra por país. Se determina por el prefijo internacional del teléfono |

Debajo verás la **audiencia total**: cuántos contactos coinciden con tus filtros.

> [!NOTA]
> Los contactos que respondieron **STOP**, **BAJA** o **CANCELAR** a un mensaje masivo se **excluyen automáticamente** de la audiencia, y ya no puedes incluirlos.

#### 2. Contenido

**En WhatsApp:**

1. Elige una **plantilla aprobada** de la lista. Si no tienes, ve a [Plantillas](/docs/campanas/plantillas) y sincroniza con Meta.
2. Si la plantilla tiene variables, haz el **mapeo de variables**: para cada una, elige un **campo del contacto** (Nombre, Teléfono o Correo) o un **texto fijo** igual para todos.
3. Opcionalmente, agrega hasta **3 etiquetas de auto-etiquetado**, que se aplican a los contactos que reciban el mensaje (por ejemplo `promo_mayo`, `interesado_oferta`).

**En Telegram:** escribes el mensaje directamente. Puedes usar variables nativas como `{{nombre}}` para personalizar cada envío.

#### 3. Programación

Elige el **día** y la **hora (local)** del envío. El **resumen final** muestra la campaña, la audiencia estimada, el canal y el **costo estimado**.

> [!NOTA]
> El costo es un **rango aproximado**: Meta cobra por conversación y varía por país y categoría. **No es una cifra de facturación**; la real es la de WhatsApp Manager. Orkestal incluye una referencia del tarifario de Meta por región (Norteamérica, Latinoamérica, Europa y global).

Pulsa **Programar envío**. Verás «Campaña programada exitosamente».

### Gestionar campañas

La lista muestra nombre, estatus, programación, costo estimado y canal. En cada una puedes:

- **Enviar ahora**: dispara el envío de inmediato, sin esperar la hora programada (te pide confirmar).
- **Editar campaña** y **Eliminar campaña** (te pide confirmar).

### Qué ve el cliente y tu equipo

Los mensajes de una campaña **se guardan en la conversación** de cada contacto y aparecen en el chat normal marcados como **Campaña**. Así, si el cliente responde, tu equipo ve el contexto.

### Resultados

Cada campaña reporta cuántos mensajes fueron **entregados**, **leídos** y **fallidos**. Los fallos traen el código de error de Meta; los más comunes están explicados en [Reglas de WhatsApp](/docs/canales/reglas-de-whatsapp#errores-de-entrega-mas-comunes).

### Reglas que protegen tu número

- **Solo contactos que esperan tu mensaje.** Una campaña a una lista fría genera reportes y baja la calidad.
- **Marketing con parsimonia.** Meta limita los mensajes de marketing a un mismo contacto en un periodo corto (error 131049).
- **Respeta las bajas.** Orkestal excluye a quien las pidió; no las reincorpores a mano.
- **Empieza con grupos pequeños** si tu número es nuevo o tiene un límite diario bajo.
- **Revisa la calidad antes y después** de cada envío grande.


# Integraciones


## Integraciones, resumen

> Qué integraciones existen, qué le permite hacer cada una a tu agente, quién puede conectarlas y cómo controlar cuándo las usa.
Fuente: https://orkestaliq.com/docs/integraciones/resumen

Una **integración** conecta Orkestal con otro servicio para que tu agente pueda **hacer** cosas en la conversación (agendar, cobrar, consultar una hoja, ver un pedido) o para que tus sistemas se enteren de lo que pasa. Se administran en **Integraciones** (Manager y Admin).

### Qué hay disponible

| Integración | Qué le permite al agente o a tu negocio | Guía |
| --- | --- | --- |
| **Google Calendar** | Proponer horarios libres, agendar, reagendar y cancelar citas, con invitación por correo | [Google Calendar](/docs/integraciones/google-calendar) |
| **Google Sheets** | Consultar tus hojas y guardar una fila por cada lead o reservación | [Google Sheets](/docs/integraciones/google-sheets) |
| **Stripe** | Crear enlaces de pago y revisar si ya se pagaron | [Stripe](/docs/integraciones/stripe) |
| **WooCommerce** | Consultar pedidos, importar tu catálogo y enlazar existencias | [WooCommerce](/docs/integraciones/woocommerce) |
| **Mercado Libre** | Mantener tu inventario sincronizado con tus publicaciones | [Mercado Libre](/docs/integraciones/mercado-libre) |
| **Notion** | Consultar páginas y bases de datos que elijas compartir (solo lectura) | [Notion](/docs/integraciones/notion) |
| **Cotización Inteligente** | Armar cotizaciones en PDF con los precios de tu inventario | [Cotización Inteligente](/docs/integraciones/cotizacion-inteligente) |
| **Envia.com** | Dar el rastreo de un envío | [Envia.com](/docs/integraciones/envia) |
| **n8n y API pública** | Conectar Orkestal con cientos de apps, mandar y recibir datos | [n8n](/docs/integraciones/n8n) |
| **WhatsApp API** | Usar tu número de WhatsApp Business desde tu propio sistema | [WhatsApp API](/docs/integraciones/whatsapp-api) |
| **Agente externo** | Que tu propio agente (n8n u otro) conteste en WhatsApp | [Agente externo](/docs/integraciones/agente-externo) |
| **Funnel de ventas** | Guion de conversación comercial (complemento de pago) | [Funnel de ventas](/docs/agente/playbook-de-ventas) |

La pantalla de Integraciones muestra además otras tarjetas marcadas como **Próximamente** o de servicios que aún no están disponibles, y un botón **Solicitar nueva integración** para pedirnos una.

> [!NOTA]
> Para qué integraciones incluye tu plan, mira **Facturación**: el plan Starter lista Google Calendar como su integración incluida. Si necesitas otra y no estás seguro de que tu plan la cubra, escribe a soporte@orkestaliq.com antes de configurarla.

### Cómo se conectan

La mayoría usa el mismo patrón:

1. En **Integraciones**, busca la tarjeta y pulsa **Conectar**.
2. Inicias sesión en el otro servicio y aceptas los permisos (Google, Mercado Libre, Notion), o pegas una credencial (Stripe, Envia.com, WooCommerce).
3. Vuelves a Orkestal con un mensaje de confirmación y la tarjeta en **Conectado**.
4. Para dejar de usarla, **Desconectar**. Lo ya creado en el otro servicio (citas, filas, pagos) **no se borra**.

Orkestal pide solo los permisos que necesita. Las credenciales que pegas se guardan **cifradas**.

### Reglas de uso para el agente

Cuando conectas Google Calendar, Google Sheets, Notion, Stripe o Cotización Inteligente, la tarjeta incluye el panel **Reglas de uso para el agente**. Sirve para decidir **cuándo** el agente puede usar esa integración. Antes de cada respuesta, un enrutador lee estas reglas y decide si la integración hace falta; las reglas no se agregan completas al mensaje de cada conversación.

| Campo | Qué hace |
| --- | --- |
| **Activar selección inteligente** | Enciende el enrutador para esa integración. Apagado, se conserva temporalmente el comportamiento anterior para tu cuenta |
| **Cuándo debe usarla** | Ej.: «cuando pregunten por stock o precios de mayoreo» |
| **Cuándo no debe usarla** | Ej.: «no usar para devoluciones ni información interna» |
| **Instrucciones especiales** | Ej.: «consultar solo para clientes con etiqueta mayorista» |
| **Papel frente a otras fuentes** | **Decidir según la consulta**, **Principal** (puede reemplazar otras fuentes en los temas indicados), **Complementaria** (agrega contexto pero no reemplaza a la principal) o **Respaldo** (solo si la principal no tiene respuesta) |

Pulsa **Guardar**: el enrutador las aplica desde el siguiente mensaje.

> [!CONSEJO]
> Escribe las reglas pensando en **la intención del cliente**. Para Stripe, por ejemplo: «Usar solo cuando el cliente confirma que quiere pagar un producto con precio definido». Sin reglas claras, el agente puede dudar o usar la integración en momentos poco útiles.

### Qué hacer si el agente "no usa" una integración

1. Comprueba que la tarjeta diga **Conectado**.
2. Revisa las **Reglas de uso**: una regla "cuándo no usarla" demasiado amplia la apaga.
3. Revisa que el cliente haya dado lo necesario (fecha y hora exactas para agendar; producto y monto claros para cobrar).
4. Prueba en el [simulador](/docs/agente/simulador) con la frase que usaría un cliente.

### Integraciones y privacidad

Cada integración recibe solo los datos necesarios para su función. Los permisos y el manejo de credenciales se explican en [Seguridad y privacidad](/docs/cuenta/seguridad-y-privacidad).


## Google Calendar

> Deja que tu agente proponga horarios libres, agende, reagende y cancele citas en tu calendario, con invitación por correo al cliente.
Fuente: https://orkestaliq.com/docs/integraciones/google-calendar

Al conectar **Google Calendar**, tu agente puede ver tu disponibilidad real y gestionar citas directamente en tu calendario, desde cualquier canal.

### Qué hace el agente

| Capacidad | Cómo funciona |
| --- | --- |
| **Proponer horarios** | Consulta tu calendario y ofrece opciones libres, sin crear nada todavía. Lo usa cuando el cliente pregunta qué hay disponible o aún no confirma una hora exacta |
| **Agendar** | Crea el evento **solo cuando el cliente confirma una fecha y hora exactas**. Revisa antes que el horario esté libre |
| **Reagendar** | Mueve la cita de esa conversación a otra hora, **sin crear un duplicado** |
| **Cancelar** | Cancela la cita de esa conversación solo cuando el cliente pide la cancelación definitiva. Si el cliente duda o dice que no puede asistir, primero ofrece otros horarios |

#### Cómo busca horarios

- Busca en los **próximos 7 días**.
- Considera un horario laboral de **9:00 a 18:00** en la zona horaria de tu cuenta.
- Revisa los eventos existentes para evitar empalmes.
- Propone el primer espacio libre que alcance para la duración.
- La duración predeterminada es de **30 minutos**; el agente la ajusta si el cliente indica otra («necesito una hora»).
- Si no hay espacio en esa ventana, lo dice y puede sugerir que el cliente contacte a tu equipo.

> [!NOTA]
> El horario de búsqueda (9:00 a 18:00 y 7 días) y la duración base **no se configuran desde el panel hoy**. Si necesitas otros valores, escríbenos a soporte@orkestaliq.com. Es independiente del [horario de atención](/docs/agente/perfil-y-estilo#horario-de-atencion) de la IA.

#### Qué lleva el evento

Título descriptivo (por ejemplo «Demo con Juan García»), fecha y hora en tu zona horaria, duración y notas con el contexto relevante de la conversación.

#### Invitación por correo al cliente

Si el agente tiene el **correo del cliente**, la cita se crea con una **invitación real de Google** que le llega por correo. Esa invitación es la confirmación.

- El correo sale de la ficha del contacto o de lo que el cliente escribió. Si no lo tiene, **se lo pide**.
- Nunca inventa ni adivina un correo: solo usa uno que el cliente haya escrito.

#### Reagendar y cancelar: sobre qué cita actúan

El agente solo puede **reagendar o cancelar la cita que él mismo agendó en esa conversación**. No ve ni toca otras citas de tu calendario: así un cliente nunca ve la cita de otro. Las citas agendadas antes de que existieran estas funciones no se pueden reagendar desde el agente.

Cuando una cita se cancela, el evento **se queda visible en tu calendario** pero marcado: su título pasa a «❌ CANCELADA — …», se pinta en gris y la descripción registra la cancelación. No desaparece.

### Requisitos

- Una **cuenta de Google** (Gmail o Google Workspace) con el calendario donde quieres las citas. En Workspace, confirma que tu administrador no restrinja el acceso a aplicaciones de terceros.
- Ser **Manager o Admin** de la cuenta de Orkestal.
- Una [clave de IA](/docs/agente/clave-de-ia) configurada.

### Conectar

1. Ve a **Integraciones** y busca la tarjeta de **Google Calendar** (estado «No conectado»).
2. Pulsa **Conectar**. Te lleva a Google.
3. Elige la cuenta de Google que contiene tu calendario.
4. Autoriza los permisos: **ver eventos** (para consultar disponibilidad) y **crear y modificar eventos** (para agendar).
5. Vuelves a Orkestal con «¡Google Calendar conectado!». La tarjeta pasa a **Conectado**.

Si Google muestra la pantalla **«Google no ha verificado esta app»**, es una advertencia de Google para aplicaciones en proceso de verificación. Para continuar, pulsa **Configuración avanzada** o **Avanzado** y luego **Ir a Orkestal**. Orkestal solo pide acceso al calendario, no a tu correo, contactos ni archivos de Drive.

### Configuración

Una vez conectado, la tarjeta ofrece:

#### Zona horaria

Elige la zona de tu negocio, por ejemplo `America/Mexico_City` (la predeterminada) o `America/Bogota`. Es importante: las citas se agendan y se comunican en esa zona. Puedes cambiarla cuando quieras; los eventos futuros usan la nueva zona y los existentes no se modifican.

#### Generar link de Meet

**Generar link de Meet para las reuniones**: si lo activas, **todas las citas incluyen una videollamada de Google Meet**. Actívalo si tus reuniones son en línea; si tus clientes te visitan en persona, déjalo apagado (viene apagado por defecto).

#### Reglas de uso para el agente

Para controlar cuándo agenda, mira [Reglas de uso](/docs/integraciones/resumen#reglas-de-uso-para-el-agente). Ejemplo: «Usar solo cuando el cliente pida una cita o una visita; no para consultas de precios».

### Con los flujos

- **Se agendó una cita**: dispara un [flujo](/docs/flujos/cuando) en el momento en que el agente agenda (confirmaciones, avisos al equipo).
- **Antes de una cita**: dispara un flujo X horas antes (recordatorios). Si la cita se reagenda, se recalcula. Usa **plantilla aprobada**: mira [Recetas](/docs/flujos/recetas).

### Preguntas frecuentes

**¿En qué calendario se crean los eventos?** En el calendario principal de la cuenta de Google que conectaste. Para usar otro, contáctanos.

**¿Qué pasa si desconecto la integración?** El agente deja de poder agendar. Los eventos ya creados permanecen en tu calendario. Puedes volver a conectar cuando quieras.

**¿Mis datos de Google están seguros?** Los tokens de acceso se almacenan cifrados y se renuevan solos. Orkestal nunca guarda tu contraseña de Google.

**El agente no agenda.** Revisa que la tarjeta esté **Conectada**, que el cliente haya confirmado una **fecha y hora exactas** y que tus reglas de uso no lo impidan. Mira [Solución de problemas](/docs/ayuda/solucion-de-problemas).


## Google Sheets

> Guarda cada lead o reservación como una fila en tu hoja de cálculo y deja que el agente consulte los datos de tus hojas.
Fuente: https://orkestaliq.com/docs/integraciones/google-sheets

Google Sheets sirve para dos cosas distintas:

- **Escribir:** guardar una fila por cada lead o reservación (acción de flujo **Exportar a Google Sheets**).
- **Leer:** que el agente consulte los valores de tus hojas para contestar (precios vigentes, disponibilidad, listas) (acción **Consultar Google Sheets** y herramienta del agente).

### Conectar

1. Ve a **Integraciones** y busca la tarjeta de **Google Sheets**.
2. Pulsa **Conectar** y autoriza el acceso a tus hojas de cálculo con tu cuenta de Google.
3. Vuelves a Orkestal con «¡Google Sheets conectado!».

Tu hoja **no necesita ser pública**: Orkestal accede con la cuenta de Google que vinculaste.

### Indicar tu hoja

Necesitas el **ID de la hoja**: la parte de la URL entre `/d/` y `/edit`.

Ejemplo: en `https://docs.google.com/spreadsheets/d/1BxiMVs0X_x5U.../edit` el ID es `1BxiMVs0X_x5U...`.

En la tarjeta guarda el ID como hoja predeterminada. Un flujo puede usar otra distinta escribiendo su propio ID.

### Leer: qué pestañas ve el agente

Para que el agente consulte tus datos:

1. En la tarjeta, pulsa **Ver pestañas de mi hoja**. Orkestal lee las pestañas con datos.
2. Elige hasta **3 pestañas** y, para cada una, escribe **qué contiene** («precios vigentes 2026»). Eso ayuda al agente a saber cuál consultar.
3. Pulsa **Guardar pestañas**. «Listo. El agente solo consultará esas pestañas.» Si no eliges ninguna, consulta todas.

> [!NOTA]
> Orkestal te avisa si la hoja no tiene pestañas con datos o si no pudo leerla.

Cuando el cliente pregunta algo que depende de esos datos, el agente **lee la hoja en ese momento**: ve siempre el valor actual. Puedes controlar cuándo lo hace con las [reglas de uso](/docs/integraciones/resumen#reglas-de-uso-para-el-agente).

### Escribir: exportar leads a una fila

En un [flujo](/docs/flujos/hacer#exportar-a-google-sheets), la acción **Exportar a Google Sheets** agrega una fila cada vez que se dispara. Tiene tres campos: la hoja (opcional si hay una predeterminada), la **pestaña y rango inicial** (por defecto `Leads!A1`) y el **formato de la fila**.

#### Formato «Lead estándar»

Las columnas se llenan **en este orden**:

| Columna | Dato |
| --- | --- |
| A | Fecha (UTC) |
| B | Nombre |
| C | Correo |
| D | Teléfono |
| E | Producto o servicio de interés |
| F | Preferencia |
| G | Etapa |
| H | Último mensaje |
| I | ID de conversación |

#### Formato «Reservación»

Pensado para restaurantes, bares y negocios que reciben reservas:

| Columna | Dato |
| --- | --- |
| A | Fecha de registro (UTC) |
| B | Nombre |
| C | Teléfono |
| D | Noche o ruta |
| E | Día de la reservación |
| F | Hora de llegada |
| G | Personas |
| H | Motivo de la visita |
| I | Confirmación del resumen |
| J | Etapa |
| K | ID de conversación |

#### Cómo trata tu hoja

- Si la **pestaña no existe**, Orkestal la crea.
- Si la pestaña está **vacía**, escribe una fila de encabezados con los nombres de arriba. **Nunca sobrescribe** una hoja que ya tiene datos.
- Las filas se agregan **al final**.

> [!CUIDADO]
> El orden de las columnas es **fijo**. Si reordenas, borras o insertas columnas en una hoja que ya recibe leads, los datos nuevos caerán en las columnas equivocadas. Si necesitas otro orden, agrega columnas a la derecha o usa otra hoja o pestaña.

#### Datos personalizados

Los campos que recolectas con **Recolectar datos** (por ejemplo «Presupuesto») no tienen columna propia en el formato estándar. Si los necesitas en la hoja, envíalos por [webhook a n8n](/docs/integraciones/n8n) y escribe tu propia fila desde ahí.

### Desconectar

**Desconectar** en la tarjeta deja de leer y escribir. Los datos que ya están en tu hoja no se borran.

### Problemas comunes

| Síntoma | Qué revisar |
| --- | --- |
| «No se pudieron leer las pestañas» | Que el ID sea el de la hoja correcta y que tu cuenta de Google tenga acceso a ella |
| El agente no usa los datos de la hoja | Que las pestañas guardadas contengan la información, que escribiste qué contiene cada una y que tus reglas de uso no lo impidan |
| Los datos caen en columnas equivocadas | Cambiaste el orden de columnas de una hoja existente. Restáuralo |
| No se agregan filas | Que el flujo esté activo y que la hoja siga compartida con la cuenta de Google conectada |


## Stripe

> Conecta tu cuenta de Stripe para que el agente cree enlaces de pago cuando el cliente decide comprar y confirme si ya pagó.
Fuente: https://orkestaliq.com/docs/integraciones/stripe

Con **Stripe** conectado, tu agente puede **generar un enlace de pago** cuando un cliente decide comprar algo, y **revisar si ya se pagó** antes de confirmarlo.

### Cómo funciona en una conversación

1. El cliente decide comprar un artículo concreto y el importe está claro. Si falta información (qué producto, cuánto), el agente la aclara antes.
2. El agente crea el **enlace de pago** y se lo manda por el chat.
3. El cliente completa el pago en la página de Stripe.
4. Si el cliente dice «ya pagué», el agente **consulta el estado real del enlace** antes de confirmar.

Orkestal revisa periódicamente el estado de los enlaces pendientes. No necesitas configurar webhooks de Stripe para este flujo.

El importe se expresa en **unidades normales de la moneda** (500 significa 500 pesos), nunca en centavos. Si el agente no indica moneda, usa la predeterminada de tu negocio.

> [!IMPORTANTE]
> El agente solo crea un enlace cuando el cliente **ya decidió comprar**. No cobra por su cuenta ni cobra automáticamente. Para controlar en qué situaciones puede hacerlo, usa las [reglas de uso](#reglas-de-uso).

### Preparar la clave en Stripe

Orkestal usa una **clave de API restringida**, para limitar lo que puede hacer.

1. En el Dashboard de Stripe, abre **Desarrolladores → Claves de API**.
2. Crea una **clave restringida**.
3. Dale permiso de **escritura** a **Payment Links** y deja **sin permisos** los demás recursos.
4. Copia la clave en un lugar seguro: Stripe puede mostrarte el secreto solo al crearla.

> [!CUIDADO]
> **No pegues tu clave secreta principal ni una clave publicable.** Orkestal acepta claves secretas o restringidas y rechaza las publicables, pero la restringida es la forma segura.

### Conectar con Orkestal

1. Ve a **Integraciones → Stripe**.
2. Pega la clave y confirma. Orkestal valida la conexión consultando tus enlaces de pago.
3. Verás «¡Stripe conectado! El agente ya puede generar links de pago.» La clave queda guardada **cifrada**.

#### Empieza en modo de prueba

Una clave que empieza con `sk_test_` crea operaciones de prueba, sin dinero real. Una clave de producción puede generar **pagos reales**. Prueba primero con claves y datos de prueba de Stripe, y confirma el modo antes de conectar.

### Reglas de uso

Con la cuenta conectada, abre **Reglas de uso para el agente**, activa la **selección inteligente** y define cuándo usar Stripe. Mira [el panel completo](/docs/integraciones/resumen#reglas-de-uso-para-el-agente). Ejemplos:

- **Cuándo usarla:** «Solo cuando el cliente confirme que quiere pagar un producto con precio definido».
- **Cuándo no usarla:** «No generar enlaces para cotizaciones de más de 10 piezas; pasar con un asesor».

Pulsa **Guardar**: el enrutador las aplica desde el siguiente mensaje.

### Qué ve tu equipo

El resumen de enlaces de pago (cuántos siguen pendientes y cuánto se cobró) puede consultarse con [Orki](/docs/empezar/orki). El cobro en sí lo ves en tu Dashboard de Stripe.

### Con el funnel de ventas

El [funnel de ventas](/docs/agente/playbook-de-ventas) puede terminar con **Enviar link de pago**: cuando el cliente decide pagar, el agente genera un enlace real de Stripe con el monto de tus documentos. El paso se cumple solo cuando el enlace existe.

### Desconectar o rotar la clave

- **Desconectar:** Orkestal pide confirmación. El agente deja de poder generar enlaces hasta que vuelvas a conectar.
- **Rotaste o revocaste la clave en Stripe:** desconecta y vuelve a conectar con la nueva.

### Problemas comunes

| Síntoma | Qué revisar |
| --- | --- |
| Stripe rechaza la clave | Que sea de la cuenta correcta y que **Payment Links** tenga permiso de escritura |
| El agente no crea enlaces | Que la conexión esté activa, que las reglas de uso permitan el cobro y que el precio y la moneda estén definidos |
| El cliente pagó, pero no aparece confirmado | Pídele al agente que vuelva a comprobar el estado del enlace; la confirmación depende de la respuesta de Stripe |


## WooCommerce

> Conecta tu tienda WooCommerce para que el agente consulte pedidos, importa tu catálogo y mantén las existencias enlazadas.
Fuente: https://orkestaliq.com/docs/integraciones/woocommerce

Con **WooCommerce** conectado, Orkestal puede:

- **Mostrar los pedidos** de un cliente junto a su conversación, y dejar que el agente consulte el estado de un pedido.
- **Importar tu catálogo** (productos y variaciones) a tu [inventario](/docs/conocimiento/inventario).
- **Enlazar las existencias** entre tu tienda y Orkestal.

Sobre los **pedidos** la integración es de **solo lectura**: Orkestal no cancela, reembolsa, cambia direcciones ni modifica pedidos en tu tienda. Lo único que Orkestal **escribe** en tu tienda son las **existencias** de un producto, y solo cuando tú las editas en tu inventario (mira [Existencias](#existencias-y-disponibilidad)).

### Qué necesitas

- Tu tienda con **HTTPS** y acceso de administrador a WordPress.
- Una **clave de REST API de WooCommerce** (Consumer Key `ck_…` y Consumer Secret `cs_…`). Con permiso de **solo lectura** funcionan los pedidos y la importación del catálogo; si quieres que las existencias que edites en Orkestal se reflejen en tu tienda, la clave necesita permiso de **lectura y escritura**.
- Un **secreto de webhook** que inventas tú: mínimo **16 caracteres**.

### Conectar paso a paso

#### 1. Crear la clave REST en WooCommerce

En WordPress: WooCommerce → Ajustes → Avanzado → API REST → Añadir clave. Elige el permiso (solo lectura, o lectura y escritura si quieres enviar existencias a tu tienda) y copia la Consumer Key y el Consumer Secret.

#### 2. Conectar en Orkestal

1. Ve a **Integraciones → WooCommerce**.
2. Completa **URL de la tienda**, **Consumer key**, **Consumer secret** y el **secreto de webhook**.
3. Elige la **estrategia del inventario inicial** (abajo).
4. Pulsa conectar. Orkestal valida las credenciales y las guarda **cifradas**. Verás «WooCommerce conectado».

#### 3. Crear los webhooks en WooCommerce

Tras conectar, la tarjeta muestra la **URL de entrega**. En WooCommerce: Ajustes → Avanzado → Webhooks, crea:

| Webhook | Obligatorio |
| --- | --- |
| **Order updated** | Sí |
| **Product updated** | Sí |
| Order created | Opcional |
| Product created | Opcional |

En cada uno, usa **esa URL de entrega** y **exactamente el mismo secreto** que escribiste en Orkestal. Los eventos de borrado no se usan.

#### 4. Verificar

Pulsa **Verificar** en la tarjeta y provoca una actualización de pedido de prueba. El indicador debe pasar de «Falta recibir el primer webhook firmado de la tienda» a **«Webhook verificado recientemente»**.

### Pedidos

- Al conectar, Orkestal importa los pedidos **modificados en los últimos 90 días** y después se mantiene al día con los webhooks.
- Un pedido se vincula a un contacto solo si su **correo o teléfono** lo identifica de forma clara. Si el correo y el teléfono apuntan a contactos distintos, no se adivina.
- En el chat del contacto aparece la tarjeta **Pedidos de WooCommerce** con número, estado, pago, artículos, método de envío y rastreo.

#### Lo que puede decir el agente

El agente consulta **los pedidos del contacto de esa conversación**, nunca los de otra persona, y no recibe la dirección de entrega. Si no encuentra una coincidencia segura, no afirma que el pedido no existe: pide el número de pedido y ofrece pasar la conversación a una persona.

### Importar tu catálogo

Para que el agente venda tus productos de WooCommerce, importa el catálogo:

- La importación corre **sola la primera vez** que se sincroniza la tienda, y la puedes repetir con **Importar catálogo** o **Re-sincronizar catálogo**.
- Trae **productos y variaciones** a tu inventario, con la moneda de tu tienda.
- Un producto **sin SKU** recibe uno sintético (`WOO-<id>`) para poder enlazarse.
- **No pisa lo que editaste a mano** en Orkestal. Esos productos se cuentan como «conservados». Si quieres reemplazarlos con los datos de WooCommerce, la opción **Reemplazar también los que edité a mano** lo hace, y te pide confirmar.
- **Respeta el límite de productos de tu plan**: lo que no cabe no se importa, y la pantalla te dice cuántos quedaron fuera.

#### Estrategia del inventario inicial

Al conectar eliges qué pasa con las existencias de los productos que ya tenías:

| Opción | Efecto |
| --- | --- |
| **Vincular sin cambiar existencias** | Enlaza productos por SKU sin tocar ninguna cantidad |
| **Conservar existencias de WooCommerce** | Orkestal toma como verdad las cantidades de tu tienda |
| **Conservar existencias de Orkestal** | Orkestal toma como verdad sus propias cantidades |

### Existencias y disponibilidad

Los productos enlazados por **SKU** mantienen sus existencias alineadas según la estrategia que elegiste:

- **De tu tienda a Orkestal:** si elegiste **conservar las existencias de WooCommerce**, los cambios de producto que llegan por el webhook actualizan tu inventario.
- **De Orkestal a tu tienda:** cuando editas las existencias de un producto en Orkestal, la misma cantidad se envía a tu tienda (necesita una clave con permiso de escritura).

Cuando el stock llega a 0, el producto pasa a **Agotado** y el agente deja de ofrecerlo.

### Con Envia.com

Los pedidos sincronizados de WooCommerce son la fuente de las guías de rastreo para [Envia.com](/docs/integraciones/envia).

### Desconectar

Desconectar elimina las credenciales y la bandeja de eventos de esa tienda en Orkestal. **No borra los webhooks de WooCommerce**: elimínalos desde tu tienda si ya no deben enviarse.

### Problemas comunes

| Síntoma | Qué revisar |
| --- | --- |
| «No se pudo conectar WooCommerce» | Que la URL sea HTTPS y pública, y que las claves tengan permiso de lectura |
| Se queda en «Falta recibir el primer webhook firmado» | Que los webhooks usen exactamente la URL de entrega y el mismo secreto, y que estén activos |
| Un cliente no ve sus pedidos | Que su correo o teléfono en Orkestal coincida con los del pedido |
| Faltan productos tras importar | Revisa el resumen de la importación: pueden ser conservados por edición manual o excedentes del límite de tu plan |
| El stock que edité en Orkestal no cambia en la tienda | Que la clave REST tenga permiso de **escritura** y que el producto tenga el mismo SKU en ambos lados |


## Mercado Libre

> Mantén tu inventario de Orkestal sincronizado con tus publicaciones de Mercado Libre, enlazadas por SKU.
Fuente: https://orkestaliq.com/docs/integraciones/mercado-libre

Conecta tu cuenta de vendedor de **Mercado Libre** y tu inventario se mantiene sincronizado solo, sin hojas de cálculo ni descuentos a mano.

### Qué se sincroniza

| Dato | Dirección |
| --- | --- |
| **Stock** | **En ambos sentidos.** Si baja en Mercado Libre (por una venta, una edición manual o una venta en tu página web enlazada), baja en Orkestal. Si lo editas en Orkestal, se actualiza en Mercado Libre |
| **Precio** | **De Mercado Libre a Orkestal.** Orkestal **nunca** cambia tus precios en Mercado Libre, así no toca tus promociones u ofertas |

Todo se enlaza por **SKU**, el código único de cada producto (por ejemplo `CAMISA-AZUL-M`).

### Antes de conectar

1. Tus productos deben estar en **Inventario**, cada uno con su **SKU**.
2. Tus publicaciones de Mercado Libre deben tener **el mismo SKU** que en Orkestal: idéntico, con las mismas mayúsculas y sin espacios de más. Para ponerlo, edita la publicación y busca el campo **SKU** (suele estar en *Información para tu gestión* o *Ficha técnica → Información adicional*).
3. Ten a la mano tu usuario y contraseña de Mercado Libre.

> [!IMPORTANTE]
> Si un producto de Mercado Libre **no tiene SKU** o **no coincide** con ninguno de Orkestal, esa venta **no descontará stock**, y recibirás un aviso en Orkestal con el SKU que debes revisar.

### Conectar

> [!CUIDADO]
> La cuenta que queda conectada es **la que tengas con sesión iniciada en mercadolibre.com en ese momento**. Antes de autorizar, asegúrate de estar en la cuenta de vendedor correcta; si tienes otra abierta, cierra sesión e inicia con la correcta.

1. En **Integraciones**, busca la tarjeta de **Mercado Libre**.
2. Elige tu **país** (México, Argentina, Colombia, etc.).
3. Pulsa **Conectar**. Te lleva a Mercado Libre.
4. Verifica la cuenta, inicia sesión si hace falta y pulsa **Autorizar**.
5. Regresas con «¡Mercado Libre conectado!». La tarjeta muestra el **nombre de la cuenta vinculada** y su ID de vendedor para que confirmes que es la correcta.

No necesitas crear apps ni claves en Mercado Libre.

### Cómo se comporta

- **Edición en Orkestal.** La cantidad que escribas (suba o baje) se copia a la publicación con el mismo SKU. Solo se actualizan publicaciones que **ya existen**; Orkestal **no crea** publicaciones nuevas.
- **Disponibilidad automática.** Con stock en 0, el producto se marca **Agotado** y el agente deja de ofrecerlo; al volver a haber stock, se reactiva solo.
- **Reporte semanal.** Cada semana Orkestal compara tu stock con el de Mercado Libre y te manda una notificación: si todo cuadra, un aviso de inventario sincronizado; si algo no cuadra, la lista de SKUs con ambas cantidades («CAMISA-AZUL: Orkestal 5 / ML 3»).

#### Publicaciones de catálogo y Mercado Envíos Full

Algunas publicaciones (de **catálogo** o con **Mercado Envíos Full**) las administra Mercado Libre y no permite que aplicaciones externas cambien su stock. Para esas, el stock se gestiona **en Mercado Libre** y Orkestal lo **refleja** automáticamente. Si intentas editarlo desde Orkestal, recibirás un aviso. No es un error: es una regla de Mercado Libre.

### Si el inventario aparece fuera de sincronía

Abre la notificación, revisa los SKUs y decide cuál cantidad es la correcta:

- **La correcta es la de Orkestal:** abre el producto en Inventario y guárdalo de nuevo, aunque no cambies nada. Se vuelve a enviar la cantidad a Mercado Libre.
- **La correcta es la de Mercado Libre:** escribe esa cantidad en el producto en Inventario y guarda.

En ambos casos el stock se corrige **en Orkestal**, que es la fuente de la verdad. Para evitar desajustes, **edita el stock siempre desde Orkestal**.

### Lo que Orkestal nunca hace

- No cambia tus **precios**, fotos ni descripciones.
- No **crea ni elimina** publicaciones.
- No accede a tus **pagos**.

### Cambiar o desconectar la cuenta

Pulsa **Desconectar** en la tarjeta (Orkestal pide confirmación). Se detiene la sincronización de stock y después puedes conectar otra cuenta: primero inicia sesión en mercadolibre.com con la cuenta correcta y vuelve a pulsar **Conectar**.

### Preguntas frecuentes

**Vendí algo y el stock no bajó.** Casi siempre es el SKU: confirma que es idéntico en ambos lados y revisa tus notificaciones, donde te decimos qué SKU llegó sin enlazar.

**Si cancelan o devuelven una venta, ¿se vuelve a sumar el stock?** Si Mercado Libre regresa el stock a la publicación, Orkestal lo detecta y se actualiza solo. Si no se reflejara, ajústalo a mano en Inventario.

**¿Funciona para varios países?** Sí. Eliges tu país al conectar.

**¿Puedo importar mis publicaciones a Orkestal?** Hoy no: los productos se cargan en Inventario y se enlazan por SKU.


## Notion

> Deja que tu agente consulte las páginas y bases de datos de Notion que elijas compartir, en modo de solo lectura.
Fuente: https://orkestaliq.com/docs/integraciones/notion

Con **Notion** conectado, tu agente puede **consultar páginas y bases de datos** que tú elijas compartir, para responder con información vigente (políticas, menús, listas de precios, procedimientos). Es de **solo lectura**: Orkestal no crea, edita ni elimina nada en tu Notion.

### Cómo funciona

1. Conectas tu cuenta de Notion y, en el selector de Notion, **compartes solo las páginas necesarias**. Compartir una página padre también permite descubrir sus páginas hijas accesibles.
2. En Orkestal eliges **hasta cinco** páginas o bases de datos como fuentes del agente.
3. Para cada fuente describes **qué contiene** y guardas las reglas de uso.
4. En cada mensaje, el agente decide qué fuente consultar según la pregunta, y usa **la mínima necesaria**. Una página que no seleccionaste **no se consulta**, aunque Notion pueda mostrarla.

### Conectar

1. Ve a **Integraciones → Notion** y pulsa **Conectar con Notion**.
2. En Notion, elige tu espacio de trabajo y **comparte solo las páginas necesarias**.
3. De vuelta en Orkestal, selecciona hasta cinco páginas o bases de datos.
4. Describe qué contiene cada una (por ejemplo «Política de cambios y devoluciones») y define las [reglas de uso](/docs/integraciones/resumen#reglas-de-uso-para-el-agente).

### Qué lee de cada fuente

| Tipo | Qué obtiene el agente |
| --- | --- |
| **Página** | Sus propiedades y su contenido, con profundidad y tamaño limitados para proteger el contexto del modelo |
| **Base de datos** | Hasta **50 filas por consulta**, con sus propiedades normalizadas |

### Qué no hace

- No escribe en Notion.
- No sincroniza ni indexa tu contenido de forma permanente: consulta en el momento.
- No permite filtros de base de datos definidos por ti.
- Si Notion falla al consultar, el agente **no afirma que la fuente esté vacía ni inventa datos**.

### Una limitación importante: vistas enlazadas

Una **vista enlazada** de una base de datos (una vista que muestra datos de otra base) **no se puede leer** a través de la integración: Notion la devuelve vacía. Si tu página usa vistas enlazadas, **comparte y selecciona la base de datos original**, no la vista.

### Notion o base de conocimiento

| Usa… | Cuando… |
| --- | --- |
| **Notion** | La información cambia seguido y la mantiene tu equipo en Notion; quieres una sola fuente vigente |
| [Base de conocimiento](/docs/conocimiento/base-de-conocimiento) | La información es estable y prefieres un documento fijo bajo tu control |

### Desconectar

Al desconectar, Orkestal revoca el acceso y deja de consultar tu Notion. Puedes revocar también el acceso desde la configuración de Notion.

### Problemas comunes

| Síntoma | Qué revisar |
| --- | --- |
| El agente no usa Notion | Que la fuente esté seleccionada, que describiste qué contiene y que las reglas de uso no lo impidan |
| Contesta que no hay datos | Que la página esté compartida con la integración y que no sea una vista enlazada |
| Falta una página | Compártela en el selector de Notion y vuelve a seleccionarla en Orkestal |


## Cotización Inteligente

> Deja que el agente arme y envíe por el chat una cotización en PDF con los precios de tu inventario, y revisa los borradores antes de mandarlos.
Fuente: https://orkestaliq.com/docs/integraciones/cotizacion-inteligente

**Cotización Inteligente** permite que tu agente arme y envíe por el chat una **cotización en PDF**, con los precios de tu [inventario](/docs/conocimiento/inventario). El agente no inventa precios: lo que no está claro queda como **borrador** para que tú lo revises.

Se configura en **Integraciones → Cotización Inteligente**.

> [!IMPORTANTE]
> Antes de activarla, revisa que tu inventario tenga **productos, precios y disponibilidad correctos**. El cotizador usa esos datos. Una cotización enviada presenta esos valores al cliente.

### Configuración inicial

#### 1. Abrir el cotizador

El interruptor superior activa o pausa la función. Puedes dejarla apagada mientras completas los ajustes.

#### 2. Personalizar el documento (pestaña Diseño)

Configura lo que aparece en el PDF:

- Título y **prefijo de folio**, y la **vigencia** de la cotización.
- **Marca**, datos fiscales y de contacto de tu negocio.
- **IVA** y las **columnas** que se muestran.
- Condiciones, métodos de pago y pie de página.

Guarda los cambios. Si el precio de tu catálogo **ya incluye impuestos**, selecciona esa opción para que no se sumen otra vez.

#### 3. Elegir cuándo cotizar (pestaña Automatización)

Selecciona el **modo**:

| Modo | Cuándo cotiza |
| --- | --- |
| **Solicitud explícita** | Solo ante pedidos directos de cotización, presupuesto o propuesta formal |
| **Asistido** | Además, cuando el cliente ya confirmó productos y cantidades y pide el total o continuar |

Puedes añadir **situaciones de uso** y **exclusiones** (las exclusiones tienen prioridad), e instrucciones especiales. También decides si crear o actualizar la [oportunidad](/docs/atencion/oportunidades) y si guardar el resumen en el contacto. Guarda las reglas.

#### 4. Activar y revisar

Cuando la configuración esté lista, activa el cotizador. En la pestaña **Cotizaciones** puedes filtrar y abrir borradores, corregir artículos, cantidades o notas, revisar el PDF, enviarlo y actualizar su estado.

### Envío automático y borradores

- Con el **envío automático** habilitado, si **todos los artículos tienen precio fijo y disponible** y la solicitud está completa, el PDF se envía en la misma conversación.
- Si lo desactivas, **todas las cotizaciones quedan como borradores** para tu revisión.
- Se crea un borrador siempre que **falta un precio, hay ambigüedad o un artículo no está disponible**.

El PDF se manda al cliente como un mensaje más del chat. Los estados de una cotización incluyen **Por revisar**, **Aceptada**, **Rechazada** y **Cancelada**, y se pueden ver también desde la [oportunidad](/docs/atencion/oportunidades) vinculada.

### Comprobación sugerida

1. Prueba una solicitud explícita con un producto con **precio fijo y disponible**.
2. Revisa el PDF: folio, impuesto, vigencia y datos del negocio.
3. Prueba otra solicitud con un producto **sin precio** y confirma que genere un borrador.
4. Verifica en **Cotizaciones** el estado y, si lo habilitaste, la oportunidad o los datos guardados en el contacto.

Hazlo en el [simulador](/docs/agente/simulador) antes de activarla con clientes reales.

### Problemas comunes

| Síntoma | Qué revisar |
| --- | --- |
| No se genera una cotización | Que la función esté activa y que la solicitud coincida con el modo y las reglas |
| Se crea un borrador en vez de enviarse | El envío automático, que los precios sean fijos, la disponibilidad, los productos y las cantidades |
| El IVA o el total no coincide | El porcentaje de IVA y si los precios del catálogo ya lo incluyen |
| El documento tiene datos incorrectos | Corrige **Diseño**, guarda y genera la siguiente cotización; revisa a mano los borradores pendientes |


## Envia.com

> Conecta Envia.com para que el agente responda consultas de rastreo con el estado actual de la guía del pedido.
Fuente: https://orkestaliq.com/docs/integraciones/envia

Con **Envia.com** conectado, cuando un cliente pregunta «¿dónde está mi pedido?», el agente consulta el **estado actual de la guía** de su envío y le responde.

> [!NOTA]
> **Alcance actual:** Orkestal solo **consulta** el estado de guías en Envia.com. Las guías disponibles proceden de **pedidos sincronizados desde [WooCommerce](/docs/integraciones/woocommerce)**. No crea envíos ni etiquetas.

### Crear el token de API

1. En tu cuenta de Envia.com, entra a **Desarrolladores → Acceso de API** y agrega un token.
2. Usa el entorno **Sandbox** para pruebas y **Producción** para rastreos reales.

> [!CUIDADO]
> Envia.com describe el token como un acceso de API de alcance amplio. Orkestal solo lo usa para consultar rastreos, pero **mantenlo privado** y limita quién puede verlo. Si se expone, revócalo en Envia.com.

### Conectar en Orkestal

1. Ve a **Integraciones → Envia.com** y abre la configuración.
2. Selecciona el **mismo entorno** que el del token: un token de producción no funciona en Sandbox, ni al revés.
3. Pega el token y pulsa **Conectar Envia.com**.
4. Orkestal hace una consulta de validación de solo lectura y guarda la credencial **cifrada**. Verás el entorno y la fecha de validación cuando la conexión esté activa.

### Cómo se usa el rastreo

1. Sincroniza en Orkestal los **pedidos de WooCommerce** que contienen la guía de envío.
2. Asegúrate de que el pedido y el contacto correspondan al mismo cliente, por **teléfono o correo**.
3. Cuando el cliente pregunte por su pedido, el agente consulta el rastreo en Envia.com y responde con el estado disponible.

Prueba primero con una guía del entorno **Sandbox**.

### Cambiar o desconectar

- **Rotar el token:** ingresa el nuevo en la misma pantalla y actualízalo.
- **Desconectar:** el agente deja de consultar rastreos.

### Problemas comunes

| Síntoma | Qué revisar |
| --- | --- |
| Token inválido | Que lo copiaste completo, que sigue activo y que el entorno seleccionado coincide |
| No aparece el rastreo | Que el pedido se haya sincronizado desde WooCommerce, tenga una guía y esté asociado al contacto correcto |
| Sandbox no encuentra la guía | Usa un envío de prueba existente en Sandbox; las guías reales viven en Producción |
| Revocaron el token | Crea uno nuevo en Envia.com y actualízalo en Orkestal |


## n8n

> Conecta Orkestal con n8n en los dos sentidos: manda tus leads a otras apps y deja que n8n envíe mensajes o actualice contactos en Orkestal.
Fuente: https://orkestaliq.com/docs/integraciones/n8n

**n8n** es una herramienta de automatización que conecta cientos de aplicaciones (CRM, correo, Slack, hojas de cálculo). Con Orkestal te permite, por ejemplo, mandar un lead nuevo a tu CRM, avisar a tu equipo por Slack, enviar recordatorios automáticos o pasar un chat a una persona cuando se cumple una condición.

**No necesitas instalar nada en n8n.** Todo funciona con dos nodos que ya trae: **Webhook** (para recibir de Orkestal) y **HTTP Request** (para pedirle cosas a Orkestal).

### Las dos direcciones

| Dirección | Qué hace | Qué usas |
| --- | --- | --- |
| **Orkestal → n8n** | «Cuando pase algo en mi chat, corre mi automatización» | La acción **Enviar a webhook (n8n)** en tus [flujos](/docs/flujos/hacer#enviar-a-webhook-n8n) |
| **n8n → Orkestal** | «Desde mi automatización, manda un WhatsApp o crea un contacto» | Una **API key** y el nodo HTTP Request |

### Parte 1: de Orkestal a n8n

#### 1. Crea un Webhook en n8n

Crea un workflow nuevo y agrega el nodo **Webhook** como disparador. Copia la **Test URL** mientras pruebas; cuando el workflow ya funcione, actívalo y usa la **Production URL**.

> [!CUIDADO]
> La URL de prueba de n8n solo escucha mientras tienes la ventana abierta esperando. Si tu flujo de Orkestal «no llega», casi siempre es porque el workflow no está activo o estás usando una Test URL vencida.

#### 2. Agrega la acción en tu flujo

En **Flujos**, en el **Hacer** elige la categoría **Integraciones externas** y la opción **Enviar a webhook (n8n)**. Pega la URL en **URL del webhook**. Los otros dos campos son opcionales:

- **Nombre del evento:** te sirve para distinguir en n8n de qué flujo vino el aviso (por ejemplo `lead.colegios`).
- **Secreto:** si lo llenas, Orkestal **firma cada envío** para que puedas comprobar que viene de Orkestal. Mira [Webhooks](/docs/api/webhooks).

Cada acción tiene su propia URL, así que puedes mandar cada tipo de lead a un workflow distinto. La URL debe ser **pública**: por seguridad se rechazan direcciones de red interna.

#### 3. Qué recibe n8n

Orkestal manda el lead completo en JSON:

```json
{
  "event": "lead.colegios",
  "sent_at": "2026-08-03T18:22:04Z",
  "business_id": "…",
  "conversation_id": "…",
  "contact_id": "…",
  "channel": "whatsapp",
  "contact": {
    "name": "María López",
    "email": "maria@ejemplo.com",
    "phone": "+5215550001111",
    "product_interest": "Primaria",
    "preference": "Turno matutino",
    "stage": "interesado",
    "tags": ["nuevo_lead", "colegios"]
  },
  "captured_data": {
    "grado_de_interes": "3ro"
  },
  "last_message": "Quiero informes de inscripciones para primaria"
}
```

En `captured_data` vienen también los campos propios que definiste en el bloque [Recolectar datos](/docs/flujos/hacer#recolectar-datos) de ese flujo.

### Parte 2: de n8n a Orkestal

#### 1. Crea tu API key

1. Entra a **Integraciones → n8n** y pulsa **Crear API key**.
2. Ponle un nombre que diga para qué es («n8n producción») y marca **solo los permisos** que ese workflow necesita.
3. **Cópiala en ese momento**: se muestra **una sola vez**. Si la pierdes, no hay forma de recuperarla; se revoca y se crea otra.

Detalle de permisos en [Autenticación y permisos](/docs/api/autenticacion).

#### 2. Configura la credencial en n8n

En tu nodo **HTTP Request** elige:

- **Authentication:** Generic Credential Type
- **Generic Auth Type:** Header Auth
- **Name:** `Authorization`
- **Value:** `Bearer ork_live_…` (tu clave completa, con la palabra `Bearer` y un espacio)

Para comprobar que quedó bien, haz una petición `GET /me`. Si te devuelve el nombre de tu negocio, ya está conectado.

#### 3. Rutas disponibles

La URL base se muestra en **Integraciones → n8n**. El detalle de cada ruta está en la [Referencia de la API](/docs/api/referencia).

| Método y ruta | Para qué sirve |
| --- | --- |
| `GET /me` | Probar que la credencial funciona |
| `POST /messages` | Enviar un WhatsApp (texto o plantilla) |
| `GET /templates` | Ver tus plantillas aprobadas y qué variables piden |
| `GET /contacts` | Listar o buscar contactos |
| `POST /contacts` | Crear un contacto (o actualizarlo si ya existe) |
| `PATCH /contacts/{id}` | Editar un contacto |
| `POST /contacts/{id}/tags` | Poner etiquetas |
| `DELETE /contacts/{id}/tags/{etiqueta}` | Quitar una etiqueta |
| `GET /conversations` | Listar conversaciones |
| `GET /conversations/{id}/messages` | Leer el historial de un chat |
| `PATCH /conversations/{id}` | Cambiar estado, etapa o asignación |
| `POST /conversations/{id}/pause-agent` | Silenciar la IA y pasar el chat a una persona |
| `POST /conversations/{id}/resume-agent` | Devolverle el chat a la IA |

### Parte 3: las dos reglas que evitan problemas

#### La ventana de 24 horas de WhatsApp

Es una regla de Meta y la causa número uno de «mi mensaje no llegó»: solo puedes mandar texto libre si el cliente te escribió en las últimas 24 horas. Pasado ese tiempo, solo se entregan **plantillas aprobadas**. Como los recordatorios de pago, los carritos abandonados y los seguimientos casi siempre caen fuera de la ventana, lo normal desde n8n es usar plantilla:

```json
POST /messages
{
  "to": "+5215550001111",
  "template": {
    "name": "recordatorio_pago",
    "variables": { "1": "María", "2": "$1,500" }
  }
}
```

Consulta `GET /templates` para ver qué plantillas tienes aprobadas y qué variables espera cada una. Si mandas texto libre fuera de la ventana, Orkestal responde con un **error 409** que lo explica, en lugar de dejar que el mensaje se pierda.

#### Idempotency-Key: evita envíos y cobros dobles

Cuando un nodo falla, n8n lo reintenta. Si era un envío de WhatsApp, tu cliente recibiría el mensaje dos veces y a ti te lo cobrarían dos veces. Agrega en el nodo HTTP Request la cabecera:

- **Name:** `Idempotency-Key`
- **Value:** un valor **único por envío** (por ejemplo `{{ $json.id }}` o `{{ $execution.id }}`)

Si la petición se repite con la misma clave, Orkestal devuelve el resultado de la primera **sin volver a enviar**.

### Recetas

**Lead nuevo → tu CRM y aviso al equipo.** Flujo con *Cuando = Nuevo lead* y *Hacer = Enviar a webhook (n8n)*. En n8n: Webhook → tu CRM (HubSpot, Pipedrive, Google Sheets) → mensaje a Slack o correo al vendedor de turno.

**Recordatorio de pago o de cita.** En n8n: Schedule Trigger → consulta tu sistema de cobranza → por cada pendiente, `POST /messages` con una plantilla aprobada y un `Idempotency-Key`.

**Carrito abandonado o cotización sin cerrar.** En n8n: tu tienda dispara el evento → nodo Wait → `POST /contacts` para registrar a la persona → `POST /messages` con plantilla de seguimiento.

**Etiquetar desde fuera y dejar que Orkestal reaccione.** En n8n: cuando tu sistema marca a alguien como «cliente VIP», llama `POST /contacts/{id}/tags`. En Orkestal, un flujo con *Cuando = Se asignó una etiqueta* reacciona solo, igual que si la hubiera puesto el agente.

**Pasar el chat a una persona bajo cierta condición.** En n8n: cuando detectas un cliente importante, una queja o un monto alto, llama `POST /conversations/{id}/pause-agent` y avisa a tu equipo. La IA se calla hasta que llames `resume-agent` o la reactives desde la bandeja.

### Si algo no funciona

| Error | Significa | Cómo se arregla |
| --- | --- | --- |
| **401** | La API key no es válida o fue revocada | Revisa que el valor sea `Bearer ork_live_…` con el espacio. Si la revocaste, crea una nueva |
| **403** | La key no tiene ese permiso | El mensaje dice cuál falta. Crea una key con ese permiso |
| **402** | La cuenta está suspendida por falta de pago | Regulariza el pago; el acceso por API se reactiva solo |
| **409** | La ventana de 24 horas está cerrada | Manda una plantilla aprobada en lugar de texto libre |
| **422** | Falta un dato, o reusaste una Idempotency-Key con otro contenido | El mensaje del error dice qué falta |
| El webhook no llega a n8n | El workflow no está activo, o la URL es interna | Activa el workflow y usa la Production URL. La URL debe ser pública |


## WhatsApp API

> Usa el número de WhatsApp Business de tu negocio desde tu propio sistema: recibe cada evento firmado en tu servidor y envía con el formato de la Cloud API.
Fuente: https://orkestaliq.com/docs/integraciones/whatsapp-api

La **WhatsApp API** de Orkestal es para quien quiere usar su número de WhatsApp Business desde **su propio sistema**. Recibes cada evento de Meta en tu servidor y envías mensajes con el mismo formato de la **Cloud API de Meta**, sin dejar de usar la app de WhatsApp Business en el teléfono (Coexistencia).

> [!NOTA]
> Es una función para **desarrolladores** y se activa desde **Integraciones → WhatsApp API** (solo Admin). Si quieres contratarla o tienes dudas de disponibilidad y precio, escribe a soporte@orkestaliq.com. Con este producto **no hay agente de IA ni bandeja**: Orkestal solo reenvía y envía.

### Inicio rápido

1. **Conecta tu número** en **Canales → WhatsApp**, escaneando el QR desde la app de WhatsApp Business (versión 2.24.17 o posterior). Mira [WhatsApp](/docs/canales/whatsapp). **Agrega un método de pago en WhatsApp Manager**: Meta cobra los mensajes directamente.
2. En **Integraciones → WhatsApp API → Agregar webhook**, pega la URL `https://` de tu servidor y **guarda el secreto de firma** (se muestra una sola vez).
3. En **Integraciones → n8n → API keys**, crea una key con los permisos `messages:write` y `messages:read` (más `templates:write` y `webhooks:write` si los necesitas).
4. Envía tu primer mensaje (mira abajo).

La URL base es `https://orkestal-backend-production.up.railway.app/api/public/v1` (también se muestra en el panel). La autenticación es `Authorization: Bearer ork_live_...`.

### Recibir: webhooks

Cada cambio que Meta notifica llega a tu URL como un `POST`: mensajes entrantes, estados de entrega, mensajes que el negocio envía desde la app, historial, contactos y cambios de cuenta. El campo `data` tiene **exactamente el formato de un webhook de Cloud API**, con un cambio por entrega.

| `field` | Qué es |
| --- | --- |
| `messages` | Mensajes entrantes (`value.messages`) y estados de lo que enviaste (`value.statuses`) |
| `smb_message_echoes` | Mensajes que el negocio escribió desde la app de WhatsApp Business |
| `history` | Historial de hasta 180 días que se sincroniza al conectar (en fases, una sola vez) |
| `smb_app_state_sync` | Altas, cambios y bajas de contactos en la app |
| `account_update` | Cambios de la cuenta, por ejemplo `PARTNER_REMOVED` si se desconecta |
| `message_template_status_update` | Una plantilla fue aprobada, rechazada o pausada |

Reglas de entrega, reintentos y verificación de firma: mira [Webhooks](/docs/api/webhooks).

**Solo reenviar:** en este producto está siempre activo. Orkestal **no guarda los mensajes en su bandeja ni responde con el agente de IA**; solo los reenvía a tu servidor.

### Enviar

`POST /whatsapp/messages`, con el cuerpo de la Cloud API (Orkestal añade `messaging_product`). **Manda siempre un `Idempotency-Key` único**: cada mensaje se cobra, y un reintento sin clave lo duplica.

```bash
curl -X POST $BASE/whatsapp/messages \
  -H "Authorization: Bearer ork_live_..." \
  -H "Idempotency-Key: 3b2c..." \
  -H "Content-Type: application/json" \
  -d '{"to":"5215598765432","type":"text","text":{"body":"Hola Ana"}}'
```

Fuera de la ventana de 24 horas, envía una plantilla:

```json
{
  "to": "5215598765432",
  "type": "template",
  "template": {
    "name": "confirmacion_pedido",
    "language": { "code": "es_MX" },
    "components": [
      { "type": "body", "parameters": [{ "type": "text", "text": "#1234" }] }
    ]
  }
}
```

Para marcar un mensaje como leído: `{"status":"read","message_id":"wamid.…"}`.

La respuesta es la de Meta (`{"messages":[{"id":"wamid…"}]}`). Los errores de Meta (por ejemplo **131047**, ventana cerrada) llegan tal cual con su código 4xx. Si Meta falla, Orkestal responde 502.

### Multimedia

- **Subir:** `POST /whatsapp/media` (multipart, campo `file`). Devuelve `{"id":"…"}`, que usas en `image.id`, `document.id`, etc.
- **Descargar lo recibido:** `GET /whatsapp/media/{media_id}` devuelve los bytes del archivo. El id llega en el webhook. Meta conserva la multimedia unos **30 días**.

### Plantillas

- `GET /whatsapp/templates`: la lista de Meta, con todos los estados.
- `POST /whatsapp/templates`: crea una plantilla y la manda a revisión (cuerpo de Meta: `name`, `language`, `category`, `components`).
- `DELETE /whatsapp/templates?name=…`: borra la plantilla.

### Estado del número

`GET /whatsapp/phone-number` devuelve la calidad, el límite y el estado de Coexistencia del número.

### Gestionar webhooks por API

Con el permiso `webhooks:write`: `GET|POST /webhook-subscriptions`, `PATCH|DELETE /webhook-subscriptions/{id}`, `POST /webhook-subscriptions/{id}/rotate-secret`, `POST /webhook-subscriptions/{id}/test`, `GET /webhook-subscriptions/deliveries` y `POST /webhook-subscriptions/deliveries/{id}/retry`. Hasta **3 suscripciones por negocio**, solo `https://`.

### Límites de la Coexistencia

- **20 mensajes por segundo** por número.
- Por la API **no hay** grupos, mensajes temporales, «ver una vez», ubicación en vivo, llamadas, catálogo, estados ni canales. Las listas de difusión quedan en solo lectura.
- Al conectar se desvinculan los dispositivos *companion*; WhatsApp para Windows y WearOS no se pueden volver a vincular.
- **Abre la app de WhatsApp Business al menos cada 14 días.** Meta desconecta los números inactivos. Orkestal te avisa los días 10 y 13.
- Para darte de baja: desconecta en Orkestal y también en la app (Herramientas para la empresa → Plataforma empresarial → Desconectar).

### Seguridad

El token de acceso de Meta **nunca sale de Orkestal**: tú usas tu API key y Orkestal añade el token en cada llamada. Mira [Autenticación y permisos](/docs/api/autenticacion).


## Agente externo de WhatsApp

> Usa tu propio agente (en n8n u otro servicio) para contestar en WhatsApp, mientras Orkestal conserva el historial y tu equipo atiende desde la bandeja.
Fuente: https://orkestaliq.com/docs/integraciones/agente-externo

Con el **agente externo**, Orkestal sigue recibiendo los mensajes de WhatsApp, guardando el historial y dejando que tu equipo atienda desde la bandeja, pero **las respuestas las genera tu propio agente** (por ejemplo, un workflow de n8n con tu modelo y tus reglas) en lugar del agente nativo de Orkestal.

Es una opción avanzada para equipos técnicos. Si no necesitas esto, deja el modo **Agente Orkestal**.

### Cómo funciona

1. Un cliente escribe por WhatsApp.
2. Orkestal guarda el mensaje y manda un **webhook firmado** a tu servicio.
3. Tu agente genera la respuesta y la manda a Orkestal por el **callback** del evento.
4. Orkestal la envía por WhatsApp y la registra en la conversación.

### Configurar

#### 1. Prepara el webhook

Publica un Webhook `POST` con una **URL HTTPS pública** (usa la URL de producción). Confirma la recepción con un `2xx` rápido y procesa al cliente después. **Verifica la firma** antes de ejecutar tu agente.

#### 2. Actívalo en Orkestal

1. Ve a **Configuración → WhatsApp → Quién responde en WhatsApp**.
2. Elige **Agente externo (n8n o webhook)**, pega la URL y **genera un secreto**. Cópialo a tu receptor **antes de guardar**.
3. Usa **Probar conexión**. El evento `orkestal.connection.test` debe confirmarse sin generar una respuesta al cliente.

#### 3. Crea una API key

En **Integraciones → n8n** crea una API key con `messages:write`. Para leer historial y estados añade `messages:read` y `conversations:read`. Guárdala como credencial de tipo Header Auth: `Authorization: Bearer TU_API_KEY_DE_ORKESTAL`.

### El evento que recibes

```json
{
  "event": "whatsapp.message.received",
  "version": 1,
  "event_id": "UUID_DEL_EVENTO",
  "business_id": "UUID_DEL_NEGOCIO",
  "conversation_id": "UUID_DE_LA_CONVERSACION",
  "channel": "whatsapp",
  "contact": { "id": "UUID", "name": "Ana", "phone": "5215550001111" },
  "message": { "id": "UUID", "content": "Hola", "message_type": "text", "file_url": null, "created_at": "FECHA_ISO" },
  "reply_path": "/api/public/v1/external-agent/events/UUID_DEL_EVENTO/reply",
  "expires_at": "FECHA_ISO"
}
```

**Deduplica por `event_id`**: el mismo evento puede volver a llegar tras un fallo de red. Para dar contexto a tu agente, consulta los últimos mensajes en orden cronológico:

```
GET /api/public/v1/conversations/UUID_DE_LA_CONVERSACION/messages?limit=50
```

### Devolver la respuesta

Después de tu nodo de agente, usa un HTTP Request con el `reply_path` del evento original:

```json
POST /api/public/v1/external-agent/events/UUID_DEL_EVENTO/reply
Authorization: Bearer TU_API_KEY_DE_ORKESTAL

{ "text": "¡Hola, Ana! ¿En qué te ayudamos?" }
```

- Un `202` confirma que quedó **en la cola**. Puedes consultar el envío con `GET /api/public/v1/external-agent/events/UUID_DEL_EVENTO`. El estado `sent` indica que Meta aceptó el mensaje.
- **Devolver texto en la respuesta HTTP del webhook no envía un WhatsApp.** Usa siempre el callback.
- Esta primera versión admite **una respuesta de texto por turno**, de hasta **4,096 caracteres**.

### Firma del webhook

Verifica la cabecera `X-Orkestal-Signature`: es `sha256=` seguido del HMAC-SHA256 hexadecimal de `X-Orkestal-Timestamp + "." + cuerpo original del POST`, con tu secreto. Usa los **bytes originales**, una comparación en tiempo constante y una tolerancia de reloj de **5 minutos**. En n8n habilita **Raw Body**. Ejemplo de código en [Webhooks](/docs/api/webhooks).

### Cuando atiende tu equipo

- **Pausar el agente** desde la conversación también detiene al agente externo.
- **Una respuesta humana invalida el turno pendiente.**
- Si llega otro mensaje del cliente, vence el turno anterior: usa el evento nuevo. Los turnos vencen también a los **10 minutos**.
- Un callback repetido con el **mismo texto** no envía otro mensaje. Un **texto distinto** para el mismo evento devuelve `409`.
- Si el estado es `send_unknown`, **revisa WhatsApp antes de responder de nuevo**: no se reenvía automáticamente un mensaje cuya entrega es incierta.

Puedes revisar los últimos turnos en **Configuración → WhatsApp**.

### Volver a la IA de Orkestal o a atención humana

En **Quién responde en WhatsApp** elige **Agente Orkestal** para volver a la IA nativa, o **Solo atención humana** para que tu equipo atienda desde la bandeja sin respuestas automáticas.


# Cuenta y facturación


## Planes y facturación

> Qué incluye el plan Starter, cómo funciona la prueba gratis, qué se cobra aparte, qué pasa si falla un pago y cómo regularizar una cuenta suspendida.
Fuente: https://orkestaliq.com/docs/cuenta/planes-y-facturacion

La suscripción de Orkestal se administra en **Facturación** (solo Admin). Si tu cuenta es una **subcuenta** de una agencia, tu facturación la administra tu cuenta matriz: verás el aviso «Tu facturación la administra tu cuenta matriz».

### Plan Starter

El plan de entrada cuesta **$499 MXN al mes**. En la pantalla de Facturación verás el precio vigente en tu moneda y cualquier impuesto aplicable antes de pagar.

| Incluye | Detalle |
| --- | --- |
| Canales | **1** canal conectado (WhatsApp, Instagram, Messenger o Telegram) |
| Inventario | **50 productos**, con hasta **2 videos** |
| Archivos de contexto | **2** (cuentan los documentos de tu [base de conocimiento](/docs/conocimiento/base-de-conocimiento)) |
| Flujos y reglas de escalamiento | **Ilimitados** |
| Integración | **Google Calendar** |
| Visión de imágenes | El agente entiende las imágenes que mandan tus clientes |
| Audio | El agente transcribe las notas de voz de tus clientes |
| Equipo | Sin miembros de equipo adicionales |

Para necesidades mayores (más canales, más productos, más integraciones o más personas en el equipo), escríbenos a contacto@orkestaliq.com y armamos un plan a tu medida.

### Lo que no incluye el plan

El plan **no cubre** costos que cobran terceros directamente:

- **El consumo de IA.** Lo cobra tu proveedor (OpenAI o Google) con tu propia clave. Mira [Clave de IA](/docs/agente/clave-de-ia).
- **Los mensajes de WhatsApp.** Meta cobra según su tarifa: mensajes de servicio después de la bolsa mensual gratuita, plantillas y campañas. Mira [Reglas de WhatsApp](/docs/canales/reglas-de-whatsapp#mensajes-gratis-cada-mes).

### Canal adicional

Si ya usaste todos los canales incluidos y conectas otro, Orkestal te muestra el cargo antes de continuar y te pide aceptarlo: **$15 USD (o $299 MXN) al mes** por canal, prorrateado en tu siguiente factura. Si lo desconectas, se te acredita. Mira [Canales, resumen](/docs/canales/resumen).

### Complementos

| Complemento | Qué es |
| --- | --- |
| [Funnel de ventas](/docs/agente/playbook-de-ventas) | El guion de conversación comercial. Se suma a tu plan prorrateado y se cancela cuando quieras |
| [WhatsApp API](/docs/integraciones/whatsapp-api) | Para desarrolladores que usan su número desde su propio sistema |

### Soluciones empresariales

Diseñamos agentes de IA, automatizaciones e integraciones a la medida de los procesos de tu empresa, **desde $500 USD al mes**. El alcance se define según tu operación. Escribe a contacto@orkestaliq.com.

### La prueba gratis

Al registrarte inicias una **prueba gratis**:

1. Registras tu **tarjeta** al empezar.
2. Tienes un periodo para instalar y probar tu agente con tus propios clientes. En **Facturación** ves cuántos días te quedan.
3. **El primer cobro del plan llega cuando termina la prueba.** Antes de eso no se cobra la suscripción.

#### Cargo de verificación de tarjeta

Al registrar tu tarjeta en el checkout, Orkestal hace **un cobro único y mínimo** (**alrededor de $10 MXN**, o su equivalente en tu moneda) para confirmar de inmediato que tu banco acepta cargos en esa tarjeta, en lugar de descubrirlo hasta el primer cobro real. **No forma parte del precio del plan y no se acredita de vuelta.** Si tu banco lo rechaza, verás el error ahí mismo y el registro no se completa. Aplica también cuando reactivas una cuenta o cambias de tarjeta en un nuevo checkout.

Si no quieres continuar, cancela antes de que termine la prueba desde el portal de facturación.

### Administrar tu suscripción

En **Facturación** puedes ver tu plan actual y abrir el **portal de facturación** de Stripe, donde cambias tu método de pago, descargas facturas y cancelas.

### Si un pago falla

1. Orkestal te muestra el aviso **«Tu último pago fue rechazado»** y te manda una notificación. Actualiza tu método de pago cuanto antes con el botón del aviso.
2. Mientras no se regularice, existe el riesgo de que se restrinja tu cuenta.

#### Cuenta suspendida por falta de pago

Si el pago sigue sin cubrirse, la cuenta se **suspende**:

- **El agente deja de responder** los mensajes de tus clientes.
- El panel muestra **«Cuenta suspendida por falta de pago»**, con el monto pendiente y un botón **Pagar ahora**.
- La **API pública** responde `402` hasta que regularices.
- Tus datos, conversaciones y configuración **se conservan**.

Para reactivar, cubre el pago pendiente con **Pagar ahora** o **Reactivar mi cuenta**. El servicio vuelve **de inmediato**.

Si tu cuenta la administra una agencia, el aviso dice que debes contactar a tu proveedor para reactivar el servicio.

### Cobros e impuestos

- Se cobra en **pesos mexicanos** u otras monedas habilitadas; la moneda y el monto exacto se muestran al pagar.
- Las facturas están disponibles en el portal de facturación.
- Si necesitas **factura fiscal (CFDI)** o un cambio de datos de facturación, escribe a soporte@orkestaliq.com.

### Preguntas frecuentes

**¿Puedo cambiar de plan?** Los planes superiores se asignan con nuestro equipo: escríbenos y lo hacemos.

**¿Qué pasa con mis datos si cancelo?** Mira [Seguridad y privacidad](/docs/cuenta/seguridad-y-privacidad#conservacion-y-eliminacion).

**¿Hay reembolsos?** Escríbenos a soporte@orkestaliq.com con el detalle de tu caso.


## Seguridad y privacidad

> Qué datos trata Orkestal, para qué los usa, qué no hace nunca con ellos, cómo se protegen tus credenciales y cómo pedir que se eliminen.
Fuente: https://orkestaliq.com/docs/cuenta/seguridad-y-privacidad

Esta página resume cómo Orkestal cuida tu información y la de tus clientes. El documento legal que manda es el [aviso de privacidad](/privacy) y los [términos de servicio](/terminos); si algo aquí parece distinto, prevalecen ellos.

### Quién es responsable de qué

- **Tu negocio** es el responsable de los datos personales de sus prospectos y clientes. Debes contar con la base legal y el consentimiento necesarios e informarles cómo se tratan sus datos.
- **Orkestal** actúa como **encargado**: trata esos datos por tu cuenta y bajo tus instrucciones.

### Qué datos recibimos

- **De tu negocio:** los datos de tu cuenta y las credenciales de los canales que conectas (por ejemplo, el ID de tu número de WhatsApp Business, tu cuenta de Instagram o tu Página de Facebook), solo de las cuentas que **tú seleccionas** en el cuadro de autorización de Meta.
- **De las personas que te escriben:** sus mensajes y archivos, su identificador en la plataforma, su nombre o nombre de usuario público y, en WhatsApp, su número de teléfono, además de eventos de la conversación como reacciones o confirmaciones de lectura.

### Para qué los usamos

Únicamente para prestarte el servicio:

- Mostrar las conversaciones en la bandeja de tu negocio.
- Enviar las respuestas que escribe tu equipo.
- Si tú lo activas, generar y enviar respuestas con un asistente de IA que **tú configuras y controlas**, siempre desde tu propia cuenta y solo en conversaciones iniciadas por la persona.
- Mantener la conexión activa y asociar cada mensaje a tu negocio.

### Lo que Orkestal no hace

- **No vende, alquila ni licencia** estos datos, ni los comparte con anunciantes o intermediarios.
- **No los usa para publicidad**, para crear perfiles de las personas ni para vigilancia.
- **No entrena modelos de IA con datos de Meta** (WhatsApp, Instagram, Messenger), ni siquiera anonimizados.
- **No usa tus datos personales identificables ni los de tus clientes** para entrenar sus modelos.
- **No combina tus datos con los de otras empresas** usuarias.
- **No contacta a tus clientes** por cuenta propia.

Orkestal puede usar datos **de-identificados y anonimizados, de forma agregada**, para operar y mejorar el servicio. Si no quieres que los datos de-identificados de tu cuenta se usen para entrenar, escribe a contacto@orkestaliq.com: puedes pedir la exclusión en cualquier momento y no afecta el funcionamiento del servicio.

### Con quién se comparten

Solo con los subprocesadores necesarios para prestarte el servicio:

- La infraestructura de alojamiento y base de datos.
- Las pasarelas de pago, para tu suscripción.
- Las plataformas de mensajería que conectas (como Meta), para recibir y enviar tus mensajes.
- **El proveedor de IA que tú elijas** (OpenAI o Google), si activas al agente: se le envía el contenido de la conversación únicamente para generar la respuesta, con **tu propia clave**. Su procesamiento está sujeto a las políticas de privacidad de ese proveedor.

También podemos divulgar datos si una ley o autoridad competente lo exige.

### Cómo protegemos tu información

| Medida | Qué significa |
| --- | --- |
| **Cifrado** | La información viaja y se guarda cifrada. Los tokens de acceso de tus canales, tus claves de IA y las credenciales de integraciones se almacenan **cifrados** |
| **Aislamiento por negocio** | Los datos de cada negocio están separados. Una cuenta no puede leer los datos de otra, ni por el panel ni por la API |
| **Roles y permisos** | Admin, Manager y Agente ven solo lo que su rol permite. Un Agente solo ve las conversaciones asignadas a él. Mira [Equipo y roles](/docs/atencion/equipo-y-roles) |
| **API keys con permisos mínimos** | Las keys se muestran una sola vez, solo guardamos su huella, y cada una tiene únicamente los permisos que le diste. Puedes revocarlas al instante |
| **Webhooks firmados** | Lo que Orkestal manda a tu servidor puede ir firmado (HMAC) para que compruebes su origen. Mira [Webhooks](/docs/api/webhooks) |
| **Direcciones internas bloqueadas** | Los webhooks de salida solo aceptan URLs públicas `https`, para que nadie pueda usarlos contra redes internas |
| **Aprobación humana** | Los cambios que propone Orki o un asistente de IA los apruebas tú antes de aplicarse. Mira [Orki](/docs/empezar/orki) |
| **Credenciales que no se pegan en chats** | Orki pide claves con un campo seguro; nunca ve su valor |

### Permisos que pide cada integración

Orkestal pide solo lo necesario para cada función. Por ejemplo, Google Calendar pide ver y crear eventos de calendario, y no accede a tu correo, contactos ni archivos de Drive. Notion es de solo lectura y solo sobre lo que compartas. Los detalles están en la guía de cada [integración](/docs/integraciones/resumen).

### Conservación y eliminación

- **Conservación:** guardamos tus conversaciones mientras tu cuenta esté activa, para que consultes tu historial. Puedes **eliminar contactos y conversaciones** en cualquier momento desde el panel.
- **Desconectar un canal:** eliminamos de inmediato el token de acceso y dejamos de recibir y enviar mensajes por esa cuenta. Tus conversaciones anteriores se conservan.
- **Revocar desde Meta:** si quitas el acceso de Orkestal desde la configuración de Instagram o Facebook, Meta nos avisa y Orkestal elimina el token y desactiva el canal automáticamente.
- **Eliminar tus datos:** puedes pedirlo desde la configuración de Facebook o Instagram, desde Orkestal, o escribiendo a contacto@orkestaliq.com. Las instrucciones están en la página de [Eliminación de datos](/eliminacion-datos). La eliminación se completa en un plazo **máximo de 30 días**.

### Tus derechos

Tienes derecho a **acceder, corregir, actualizar, exportar o solicitar la eliminación** de tu información personal y de los datos de tu CRM. Puedes ejercerlos desde el panel o con nuestro equipo. Si eres cliente final de un negocio que usa Orkestal y quieres ejercer tus derechos, contacta primero a ese negocio; también puedes escribirnos y te ayudaremos.

### Recomendaciones para tu equipo

1. **Un correo por persona.** No compartas una cuenta entre varios.
2. **El rol mínimo necesario** para cada quien.
3. **Revoca accesos** de quien deje el equipo, en **Equipo**.
4. **Rota las claves** (de IA, de API, de integraciones) si sospechas que se expusieron.
5. **No pongas datos sensibles** (contraseñas, tarjetas) en documentos de la base de conocimiento: el agente podría repetirlos.
6. **Revisa tus reglas de uso** de las integraciones para limitar cuándo actúa el agente.

### Reportar un problema de seguridad

Si encuentras una vulnerabilidad o crees que tu cuenta fue comprometida, escribe de inmediato a soporte@orkestaliq.com con el mayor detalle posible. Para asuntos legales o de privacidad: contacto@orkestaliq.com.


## Agencias, subcuentas y marca blanca

> Cómo una agencia administra a varios clientes desde una cuenta matriz, con cada cliente en su subcuenta, su marca y su propio dominio.
Fuente: https://orkestaliq.com/docs/cuenta/agencias

Si manejas varios negocios (una agencia, un consultor, un grupo de empresas), Orkestal te permite administrarlos desde una sola **cuenta matriz**, con **cada cliente en su propia subcuenta**, y presentarles la plataforma **con tu marca y tu propio dominio**.

### Cómo está organizado

| Pieza | Qué es |
| --- | --- |
| **Cuenta matriz (Partner)** | Tu cuenta de agencia. **No opera conversaciones ni flujos por sí misma**: administra subcuentas, marca, dominio y facturación |
| **Subcuenta** | La cuenta de cada cliente. Funciona como una cuenta normal de Orkestal: sus propios canales, agente, conocimiento, flujos y equipo |
| **Tu equipo** | Las personas de tu agencia pueden tener acceso a **varias subcuentas**, con un rol distinto en cada una |

Cada subcuenta está **aislada**: los datos de un cliente nunca se mezclan con los de otro.

### Crear tu cuenta de Partner

Solicita acceso desde la página de [Partners](/partners/signup): creas tu cuenta Partner y confirmas tu correo. Al entrar, tu panel es el de la cuenta matriz: **Subcuentas**, **Marca y dominio**, **Facturación dinámica** y **Equipo**.

### Subcuentas

En **Subcuentas** puedes:

- **Crear una subcuenta** con el nombre del negocio, las condiciones de cobro (el plan), el correo y la contraseña inicial de su administrador, y el proveedor de IA. Antes de crear la primera necesitas **agregar un método de pago** a la cuenta matriz.
- **Entrar como administrador** a cualquier subcuenta para configurarla. El banner de arriba te indica en qué cuenta estás trabajando.
- **Configurar el nombre y el proveedor de IA sin entrar** a la subcuenta.
- **Cambiar el plan**, **suspender** o **reactivar** una subcuenta.

> [!IMPORTANTE]
> Cuando estés dentro de una subcuenta, todo lo que hagas se aplica **a esa subcuenta**. Revisa el banner antes de guardar cambios.

### Facturación dinámica

La cuenta matriz paga una **tarifa base** más un cargo por cada subcuenta según su plan. El detalle se ve en **Facturación dinámica**: subcuentas facturables en el corte, desglose por periodo y por subcuenta, y total estimado.

Reglas que conviene conocer:

- **Cada subcuenta tiene 7 días de gracia desde su alta.** Pasado ese plazo, genera el **cargo completo** de su plan.
- **No hay cálculo proporcional.** Los cargos son siempre por el importe completo.
- **Suspender una subcuenta detiene su acceso, pero no elimina un cargo ya comprometido.** Tampoco reinicia ni extiende la gracia: al reactivarla se conserva la fecha original de alta.
- Antes de cambiar el plan, suspender o reactivar, el panel muestra una **revisión de facturación** con el efecto en el cobro.

Quienes usan una subcuenta ven en su Facturación el aviso «Tu facturación la administra tu cuenta matriz».

### Marca blanca

En **Marca y dominio** personalizas lo que ven tus clientes:

| Ajuste | Qué hace |
| --- | --- |
| **Logo de la empresa** | Se muestra en el panel y en el login. Es el logo de la empresa, no tu foto personal (esa se cambia en Ajustes) |
| **Nombre de marca** | Reemplaza «Orkestal IQ» en el menú lateral, el título de la pestaña y el login. Vacío usa el de Orkestal |
| **Paleta de colores** | Tiñe el panel, sus superficies y la tarjeta lateral del login |
| **Nombre del asistente de IA** | Cómo se llama el asistente dentro de tu instancia |
| **Texto del login** | El mensaje bajo «Bienvenido de vuelta». Solo se ve cuando entran por tu dominio |
| **Contenido de la tarjeta lateral** | El mensaje principal del login. Los campos vacíos usan el texto original de Orkestal |

Una **vista previa del login** cambia al instante mientras editas. **Guarda la identidad** para aplicarla.

#### Dominio propio

Tus clientes pueden entrar por un dominio tuyo, por ejemplo `app.tuempresa.com`, con un login **sin marketing de Orkestal** y con tu marca.

1. **Elige un subdominio** (por ejemplo `app.tuempresa.com`). Debe ser un subdominio: un dominio raíz no se puede apuntar con CNAME.
2. **Agrégalo** en Marca y dominio.
3. **Crea el registro CNAME** que te muestra Orkestal en el proveedor de tu dominio.
4. **Espera a que se active.** Se activa solo en cuanto detectamos el registro; mientras tanto verás «Esperando tu DNS». Si falla, revisa los registros y pulsa **Actualizar estado**.
5. **Enlaza el botón de tu sitio web** a ese dominio.

> [!NOTA]
> Si tu DNS está en **Cloudflare**, deja el registro en **«DNS only»** (nube gris), no en modo proxy.

Cuando alguien entra por un dominio de partner, la página principal lo lleva directo al **login con tu marca**; no ve la landing de Orkestal.

### Equipo de la agencia

En **Equipo** de la cuenta matriz das de alta a tu gente y le repartes acceso a una o varias subcuentas. Cada persona tiene un solo usuario con roles distintos por cuenta. Mira [Equipo y roles](/docs/atencion/equipo-y-roles#personas-con-acceso-a-varias-cuentas).

### Soluciones a la medida

¿Necesitas algo distinto (más control de marca, integraciones propias, un acuerdo de volumen)? Escribe a contacto@orkestaliq.com.


# Para desarrolladores


## Autenticación y permisos de la API

> Cómo crear una API key, qué permisos existen, cómo se envía en cada petición y qué significan los errores y las reglas de paginación e idempotencia.
Fuente: https://orkestaliq.com/docs/api/autenticacion

La API pública de Orkestal te deja leer y modificar tus contactos y conversaciones, enviar mensajes de WhatsApp y recibir eventos, desde tus propios sistemas o desde herramientas como [n8n](/docs/integraciones/n8n).

### Conceptos básicos

- **URL base:** `https://orkestal-backend-production.up.railway.app/api/public/v1`. También se muestra en **Integraciones → n8n**.
- **Formato:** JSON sobre HTTPS.
- **Aislamiento:** cada API key pertenece a **un solo negocio** y solo ve sus datos. No hay forma de leer datos de otro negocio.

### Autenticación

Todas las peticiones llevan tu API key en la cabecera `Authorization`:

```
Authorization: Bearer ork_live_...
```

Para comprobarla, llama a `GET /me`: devuelve el nombre de tu negocio, el nombre de la key y sus permisos.

```bash
curl https://orkestal-backend-production.up.railway.app/api/public/v1/me \
  -H "Authorization: Bearer ork_live_..."
```

### Crear y administrar API keys

Solo un **Admin** puede crear keys, en **Integraciones → n8n → Crear API key**.

1. Ponle un **nombre** que diga para qué es («n8n producción»).
2. Marca **solo los permisos** que necesita.
3. **Cópiala en ese momento.** Se muestra **una sola vez**: Orkestal solo guarda una huella (hash) de la key y no puede recuperarla. Si la pierdes, revócala y crea otra.

Puedes tener hasta **20 keys activas** por negocio. Para dejar de usar una, **revócala**: deja de funcionar de inmediato.

> [!CUIDADO]
> Una API key es como una contraseña. No la pongas en código que se publique, en un chat ni en una captura de pantalla. Si se expone, revócala y crea otra.

### Permisos

El acceso es **denegado por defecto**: una key solo puede hacer lo que tiene marcado.

| Permiso | Qué permite |
| --- | --- |
| `contacts:read` | Leer contactos |
| `contacts:write` | Crear y editar contactos |
| `conversations:read` | Leer conversaciones y su historial |
| `conversations:write` | Cambiar estado, asignar y pausar el agente |
| `messages:read` | Leer mensajes |
| `messages:write` | Enviar mensajes |
| `tags:read` | Leer etiquetas |
| `tags:write` | Asignar y quitar etiquetas |
| `templates:read` | Leer plantillas de WhatsApp |
| `templates:write` | Crear y borrar plantillas de WhatsApp |
| `broadcasts:write` | Disparar campañas de difusión |
| `webhooks:write` | Crear y borrar suscripciones a webhooks |

Una key **no hereda el rol** de quien la creó: tiene solo los permisos que marcaste.

### Errores

Los errores devuelven un código HTTP y un JSON con un campo `detail` que explica el motivo, en español.

| Código | Significa | Qué hacer |
| --- | --- | --- |
| `401` | La key no es válida, está mal escrita o fue revocada | Revisa que el valor sea `Bearer ork_live_…`, con el espacio |
| `402` | La cuenta está **suspendida por falta de pago** | Regulariza el pago; el acceso por API se reactiva solo |
| `403` | La key no tiene el permiso necesario | El mensaje dice cuál falta; crea una key con ese permiso |
| `404` | El recurso no existe (o no pertenece a tu negocio) | Revisa el identificador |
| `409` | Conflicto. Por ejemplo, mensaje libre fuera de la ventana de 24 horas | Usa una plantilla aprobada |
| `422` | Falta un dato, un dato es inválido, o reusaste una `Idempotency-Key` con otro contenido | El mensaje dice qué corregir |
| `502` | Meta falló al procesar el envío | Reintenta más tarde |

### Paginación

Los listados (`/contacts`, `/conversations`) usan **cursor**:

- `limit`: cuántos resultados (por defecto **25**, máximo **100**).
- `cursor`: el valor de la página anterior.

Cuando hay más resultados, la respuesta incluye la cabecera `Link` con `rel="next"` y la cabecera `X-Next-Cursor`. Herramientas como n8n siguen el `Link` solas.

### Idempotencia

Los envíos de mensajes **se cobran** y una repetición crearía otro mensaje. Para que un reintento no duplique nada, manda la cabecera:

```
Idempotency-Key: un-valor-unico-por-envio
```

- Si repites la petición con la **misma clave y el mismo contenido**, Orkestal devuelve el resultado de la primera **sin volver a enviar**.
- Si reutilizas la clave con **otro contenido**, responde `422`.

Úsala siempre en `POST /messages` y `POST /whatsapp/messages`.

### Límites de uso

Orkestal no publica un límite de peticiones por minuto, pero **evita ráfagas**: Meta sí limita la velocidad de envío de WhatsApp (error `130429`), y una cuenta con calidad baja puede quedar bloqueada para campañas. Mira [Reglas de WhatsApp](/docs/canales/reglas-de-whatsapp).

### Siguiente paso

El detalle de cada ruta está en la [Referencia](/docs/api/referencia). Para recibir eventos en tu servidor, mira [Webhooks](/docs/api/webhooks).


## Referencia de la API

> Todas las rutas de la API pública de Orkestal con el permiso que exigen, sus parámetros y ejemplos de uso.
Fuente: https://orkestaliq.com/docs/api/referencia

Todas las rutas cuelgan de la URL base `https://orkestal-backend-production.up.railway.app/api/public/v1` y requieren `Authorization: Bearer ork_live_…`. Antes de empezar, lee [Autenticación y permisos](/docs/api/autenticacion).

### Identidad

#### `GET /me`

Comprueba que la key funciona. No requiere permisos especiales.

```json
{
  "business_id": "…",
  "business_name": "Mi Negocio",
  "api_key_name": "n8n producción",
  "scopes": ["contacts:read", "messages:write"]
}
```

### Contactos

| Método y ruta | Permiso | Qué hace |
| --- | --- | --- |
| `GET /contacts` | `contacts:read` | Lista contactos |
| `POST /contacts` | `contacts:write` | Crea un contacto, o lo actualiza si el teléfono ya existe |
| `GET /contacts/{id}` | `contacts:read` | Un contacto |
| `PATCH /contacts/{id}` | `contacts:write` | Edita nombre, correo, etiquetas o metadata |
| `POST /contacts/{id}/tags` | `tags:write` | Suma etiquetas |
| `DELETE /contacts/{id}/tags/{etiqueta}` | `tags:write` | Quita una etiqueta |

**Filtros de `GET /contacts`:** `search` (busca en nombre, teléfono o correo), `tag` (una etiqueta), `limit` (1 a 100, por defecto 25) y `cursor`.

**Objeto contacto:**

```json
{
  "id": "…",
  "phone": "+5215550001111",
  "name": "María López",
  "email": "maria@ejemplo.com",
  "tags": ["nuevo_lead"],
  "metadata": {},
  "created_at": "2026-11-04T18:22:04Z"
}
```

**`POST /contacts`:** el único campo obligatorio es `phone`. Es un **upsert**: si ya existe un contacto con ese teléfono, se actualiza. Las **etiquetas se suman, nunca reemplazan** las existentes, para que dos automatizaciones distintas no se pisen.

```json
POST /contacts
{ "phone": "+5215550001111", "name": "María López", "tags": ["colegios"] }
```

> [!NOTA]
> Una etiqueta puesta por la API dispara los flujos con «Se asignó una etiqueta» igual que si la hubiera puesto el agente. Mira [Flujos: Cuando](/docs/flujos/cuando).

### Conversaciones

| Método y ruta | Permiso | Qué hace |
| --- | --- | --- |
| `GET /conversations` | `conversations:read` | Lista conversaciones |
| `GET /conversations/{id}/messages` | `messages:read` | Historial de una conversación |
| `PATCH /conversations/{id}` | `conversations:write` | Cambia estado, etapa o asignación |
| `POST /conversations/{id}/pause-agent` | `conversations:write` | Pausa la IA en ese chat |
| `POST /conversations/{id}/resume-agent` | `conversations:write` | Reactiva la IA en ese chat |

**Filtros de `GET /conversations`:** `status`, `contact_id`, `limit` y `cursor`.

**Objeto conversación:**

```json
{
  "id": "…",
  "contact_id": "…",
  "channel": "whatsapp",
  "status": "active",
  "sale_stage": "interesado",
  "assigned_to": "…",
  "created_at": "…"
}
```

**`GET /conversations/{id}/messages`:** hasta 100 mensajes (`limit`, por defecto 50), en **orden cronológico** (del más viejo al más nuevo), cada uno con `id`, `sender_type`, `content`, `message_type` y `created_at`.

**`PATCH /conversations/{id}`:** campos opcionales `status`, `sale_stage` (una etapa como `interesado`, `negociacion` o `vendido`) y `assigned_to` (el id de una persona de tu equipo).

`pause-agent` y `resume-agent` son el equivalente a los botones **Pausar IA / Activar IA** del chat. Mira [Relevo humano](/docs/agente/relevo-humano).

### Mensajes

#### `POST /messages`

**Permiso:** `messages:write`. Envía un mensaje de WhatsApp, de **texto** o de **plantilla**.

| Campo | Qué es |
| --- | --- |
| `to` | Teléfono del destinatario con código de país (si no das `conversation_id`) |
| `conversation_id` | La conversación a la que se envía (alternativa a `to`) |
| `text` | El texto libre |
| `template` | La plantilla: `{ "name": "…", "variables": { "1": "…" } }` (o `id` en lugar de `name`) |
| `channel` | `whatsapp` (por defecto) |

Envía **`text` o `template`**, no ambos. Manda siempre `Idempotency-Key`.

```json
POST /messages
Idempotency-Key: pedido-1234-recordatorio
{
  "to": "+5215550001111",
  "template": { "name": "recordatorio_pago", "variables": { "1": "María", "2": "$1,500" } }
}
```

**Respuesta:**

```json
{
  "sent": true,
  "conversation_id": "…",
  "contact_id": "…",
  "message_id": "…",
  "mode": "template",
  "content": "…"
}
```

**Reglas:**

- Antes de enviar texto libre, Orkestal valida la **ventana de 24 horas**. Si está cerrada responde `409` con instrucciones, en vez de dejar que Meta lo rechace con el error 131047.
- La cuenta debe estar al corriente: con una suspensión por pago, responde `402`.
- El mensaje queda registrado en la conversación del contacto.

#### `GET /templates`

**Permiso:** `templates:read`. Lista tus plantillas con `id`, `name`, `language`, `status`, `category`, las `variables` que espera y el `body`. Úsala para saber qué plantillas puedes enviar con `POST /messages`.

### WhatsApp Cloud API (producto WhatsApp API)

Estas rutas están disponibles para quien usa el producto [WhatsApp API](/docs/integraciones/whatsapp-api). Reciben y devuelven el formato de la Cloud API de Meta.

| Método y ruta | Permiso | Qué hace |
| --- | --- | --- |
| `POST /whatsapp/messages` | `messages:write` | Envía un mensaje (texto, plantilla, multimedia) o marca como leído |
| `POST /whatsapp/media` | `messages:write` | Sube un archivo (multipart, campo `file`) |
| `GET /whatsapp/media/{id}` | `messages:read` | Descarga un archivo recibido |
| `GET /whatsapp/phone-number` | | Calidad, límite y estado de Coexistencia del número |
| `GET /whatsapp/templates` | `templates:read` | Lista las plantillas de Meta con todos sus estados |
| `POST /whatsapp/templates` | `templates:write` | Crea una plantilla y la manda a revisión |
| `DELETE /whatsapp/templates?name=…` | `templates:write` | Borra una plantilla |

### Suscripciones a webhooks

Todas requieren `webhooks:write`.

| Método y ruta | Qué hace |
| --- | --- |
| `GET /webhook-subscriptions` | Lista tus suscripciones |
| `POST /webhook-subscriptions` | Crea una (solo URL `https://`) |
| `PATCH /webhook-subscriptions/{id}` | Edita |
| `DELETE /webhook-subscriptions/{id}` | Elimina |
| `POST /webhook-subscriptions/{id}/rotate-secret` | Genera un secreto nuevo |
| `POST /webhook-subscriptions/{id}/test` | Manda un evento `test.ping` firmado |
| `GET /webhook-subscriptions/deliveries` | Bitácora de entregas |
| `POST /webhook-subscriptions/deliveries/{id}/retry` | Reintenta una entrega |

Límites y verificación de firma en [Webhooks](/docs/api/webhooks).

### Agente externo

| Método y ruta | Permiso | Qué hace |
| --- | --- | --- |
| `POST /external-agent/events/{event_id}/reply` | `messages:write` | Devuelve la respuesta de tu agente para un evento |
| `GET /external-agent/events/{event_id}` | | Consulta el estado del envío |

Mira [Agente externo](/docs/integraciones/agente-externo).

### Lo que la API no hace

- **No expone credenciales ni tokens** de tus canales o integraciones.
- **Con estas rutas no se crean ni editan** flujos, reglas de escalamiento, la base de conocimiento ni el perfil del agente. Eso se hace desde el panel.
- **No lee datos de otros negocios.**


## Webhooks firmados

> Cómo recibir eventos de Orkestal en tu servidor, cómo verificar su firma y cómo funcionan las entregas, los reintentos y la desactivación.
Fuente: https://orkestaliq.com/docs/api/webhooks

Un **webhook** es un aviso que Orkestal manda a una dirección web tuya cuando pasa algo. Hay tres fuentes, que comparten la misma forma de firmar:

| Fuente | Cuándo se manda | Dónde se configura |
| --- | --- | --- |
| **Acción «Enviar a webhook (n8n)»** de un flujo | Cuando se cumple el «Cuando» del flujo; manda el lead completo | [Flujos: Hacer](/docs/flujos/hacer#enviar-a-webhook-n8n) |
| **Suscripciones de WhatsApp API** | Por cada cambio que Meta notifica de tu número | [WhatsApp API](/docs/integraciones/whatsapp-api) |
| **Agente externo** | Por cada mensaje de un cliente, para que tu agente conteste | [Agente externo](/docs/integraciones/agente-externo) |

### Requisitos de tu URL

- Debe ser **pública** y usar **`https://`**. Orkestal rechaza direcciones de red interna (por seguridad) y no sigue redirecciones.
- Responde con un **`2xx` en menos de 10 segundos**. Si tu proceso tarda más, responde primero y procesa después.

### Cabeceras

Si configuraste un **secreto**, cada envío lleva:

| Cabecera | Contenido |
| --- | --- |
| `X-Orkestal-Signature` | La firma, con el formato `sha256=…` |
| `X-Orkestal-Timestamp` | Cuándo se envió (segundos Unix) |
| `X-Orkestal-Event` | El nombre del evento (en los envíos de flujos) |
| `X-Orkestal-Delivery` | El identificador de la entrega (en las suscripciones de WhatsApp API) |

### Verificar la firma

La firma es el **HMAC-SHA256** de la cadena `"{timestamp}.{cuerpo}"`, calculado con tu secreto y escrito en hexadecimal, con el prefijo `sha256=`.

> [!IMPORTANTE]
> Calcula la firma sobre el **cuerpo crudo** que recibiste, no sobre un JSON que volviste a serializar: cambiar el orden de las llaves o los espacios cambia la firma. Compara con una función de **tiempo constante** y rechaza peticiones cuyo `timestamp` tenga más de **5 minutos** de diferencia con tu reloj (protección contra repeticiones).

#### Python

```python
import hmac, hashlib, time

def is_valid(headers, raw_body: bytes, secret: str) -> bool:
    ts = headers["X-Orkestal-Timestamp"]
    if abs(time.time() - int(ts)) > 300:
        return False  # protección contra replay
    expected = "sha256=" + hmac.new(
        secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, headers["X-Orkestal-Signature"])
```

#### Node.js

```javascript
const crypto = require('crypto');

function isValid(headers, rawBody, secret) {
  const ts = headers['x-orkestal-timestamp'];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`)
    .digest('hex');
  const given = headers['x-orkestal-signature'] || '';
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
```

#### En n8n

En el nodo **Webhook** activa **Raw Body**. Después del Webhook, agrega un nodo **Code** que recalcule la firma con el cuerpo crudo y lance un error si no coincide. Si tu instalación no permite verificarla, coloca un receptor verificador delante del workflow.

### Entregas de WhatsApp API

Cada cambio que Meta notifica llega como un `POST` con esta forma:

```json
{
  "event": "whatsapp.webhook",
  "delivery_id": "6f1c…",
  "business_id": "…",
  "created_at": "2026-10-28T18:00:00Z",
  "data": {
    "object": "whatsapp_business_account",
    "entry": [{
      "id": "<WABA_ID>",
      "changes": [{
        "field": "messages",
        "value": {
          "messaging_product": "whatsapp",
          "metadata": { "display_phone_number": "5215512345678", "phone_number_id": "…" },
          "contacts": [{ "profile": { "name": "Ana" }, "wa_id": "5215598765432" }],
          "messages": [{ "from": "5215598765432", "id": "wamid.…", "timestamp": "…",
                         "type": "text", "text": { "body": "Hola" } }]
        }
      }]
    }]
  }
}
```

El campo `data` tiene el formato exacto de un webhook de la Cloud API de Meta, con **un solo cambio por entrega**. La lista de `field` posibles está en [WhatsApp API](/docs/integraciones/whatsapp-api#recibir-webhooks).

#### Reintentos y desactivación

- Si no respondes `2xx`, Orkestal **reintenta 8 veces durante aproximadamente un día**: a los 30 s, 2 min, 10 min, 30 min, 1 h, 3 h, 6 h y 12 h.
- Tras **50 fallos seguidos**, el webhook se **desactiva** y te avisamos. Reactívalo desde el panel.
- **El mismo evento puede llegar más de una vez y fuera de orden.** Deduplica por `delivery_id` (o por el `id` del mensaje).
- Cada suscripción admite payloads de hasta 5 MB, y puedes tener hasta **3 suscripciones por negocio**.

#### Probar

Usa el botón **Probar** del panel, o `POST /webhook-subscriptions/{id}/test`: recibirás un evento `test.ping` firmado. En **Entregas** (o `GET /webhook-subscriptions/deliveries`) ves el resultado de cada envío y puedes reintentar los fallidos.

### Envíos de flujos

La acción «Enviar a webhook (n8n)» manda el lead en JSON (contacto, datos recolectados, etapa, último mensaje). El cuerpo completo y un ejemplo están en [n8n](/docs/integraciones/n8n#3-que-recibe-n8n). Si pones secreto, el envío va firmado igual que arriba; si no, llega sin cabeceras de firma.

### Buenas prácticas

1. **Verifica siempre la firma** antes de actuar: sin ella, cualquiera que conozca tu URL podría mandarte datos falsos.
2. **Responde rápido y procesa en segundo plano.**
3. **Hazlo idempotente**: guarda los `delivery_id` o `event_id` que ya procesaste.
4. **Guarda el secreto** como variable de entorno, nunca en el código.
5. **Rota el secreto** (`rotate-secret`) si sospechas que se expuso.


# Ayuda


## Solución de problemas

> Diagnóstico por síntoma: la IA no contesta, contesta cuando no debe, un mensaje no sale o no llega, una integración no responde, y más.
Fuente: https://orkestaliq.com/docs/ayuda/solucion-de-problemas

Busca tu síntoma y sigue los pasos **en orden**: están acomodados de lo más común a lo menos común.

> [!CONSEJO]
> [Orki](/docs/empezar/orki) puede diagnosticar por ti, con datos reales de tu cuenta, **por qué la IA no contestó en un chat concreto** o por qué tu WhatsApp no recibe. Pregúntale con el nombre del contacto. Si no ves esa función, sigue esta guía.

### La IA no contesta

Orkestal revisa estas condiciones **en este orden**. La primera que falla es la causa:

| # | Revisión | Cómo comprobarla | Cómo arreglarla |
| --- | --- | --- | --- |
| 1 | **Suscripción al corriente** | ¿Hay un aviso de «Cuenta suspendida por falta de pago» o «Tu último pago fue rechazado»? | Regulariza en Facturación. Mira [Planes y facturación](/docs/cuenta/planes-y-facturacion#cuenta-suspendida-por-falta-de-pago) |
| 2 | **Quién responde en WhatsApp** | Configuración → WhatsApp → «Quién responde en WhatsApp» | Debe estar en **Agente Orkestal**. En «Agente externo» o «Solo atención humana» la IA de Orkestal no contesta |
| 3 | **IA Global encendida** | El interruptor **IA Global** en Conversaciones | Enciéndelo |
| 4 | **Canal activo** | Canales: que el canal esté conectado y activo | Reactívalo o reconéctalo |
| 5 | **IA no pausada en ese chat** | El botón del chat dice **Activar IA para este chat** | Actívala. La pausa pudo venir de una respuesta de tu equipo, del botón o de una regla de escalamiento. Mira [Relevo humano](/docs/agente/relevo-humano) |
| 6 | **Dentro del horario de atención** | Agente IA → Horario de atención | Ajusta el horario o espera a que abra |
| 7 | **Clave de IA configurada** | El aviso «Tu agente de IA no está activo» | Configura la clave en Configuración. Mira [Clave de IA](/docs/agente/clave-de-ia) |

Si todo está bien y sigue sin contestar:

- Revisa que **tu proveedor de IA** tenga saldo y que no hayas alcanzado un límite de gasto: Orkestal solo comprueba que haya una clave, no su saldo.
- Haz la prueba en el [simulador](/docs/agente/simulador). Si ahí sí contesta, el problema es del canal; si tampoco, es de configuración o del proveedor de IA.
- Escribe a soporte@orkestaliq.com con el nombre del contacto y la hora aproximada.

### La IA contesta cuando no debería

| Situación | Causa probable | Qué hacer |
| --- | --- | --- |
| Contestó después de que una persona ya había respondido | Pasó el tiempo de **reanudación automática** | Revisa «La IA retoma el chat tras N horas» en Agente IA; pon **0** para que solo una persona la reactive |
| Contesta fuera de tu horario | El horario de atención está apagado | Actívalo en Agente IA |
| Sigue vendiendo en una conversación de queja o soporte | Falta una regla de escalamiento | Crea una [regla](/docs/agente/relevo-humano) con «Pausar a la IA» |
| Repitió el mismo mensaje | Un flujo de mensaje automático con disparador de tiempo o contexto | Revisa los [flujos](/docs/flujos/hacer): los de mensaje del cliente salen una vez por conversación; los de tiempo, hasta su máximo |
| Su tono no se parece al de tu equipo | El estilo de lenguaje no coincide con el de tu equipo | Ajusta el estilo, o prueba «Escribe como tu equipo». Mira [Perfil y estilo](/docs/agente/perfil-y-estilo) |

### El agente da una respuesta incorrecta o inventada

1. **Busca la respuesta correcta en tus fuentes.** El agente solo debe usar lo que le diste. Si no está, **cúbrela**: la pregunta aparece en **Base de Conocimiento → Brechas de Conocimiento**.
2. **Revisa contradicciones.** Un documento viejo, el inventario y un archivo pueden decir cosas distintas. Mira [Qué fuente usar](/docs/conocimiento/que-fuente-usar#cuando-dos-fuentes-se-contradicen).
3. **Revisa que el documento esté Activo** y tenga **regla de enrutamiento** o sea **base principal**. Sin eso el agente puede omitirlo.
4. **Usa Embeddings Preview** para ver qué fragmentos recuperaría el agente con esa pregunta.
5. **Revisa el inventario**: precio, existencias y disponibilidad del producto.
6. Si es un orden de la conversación lo que falla, configura un [funnel](/docs/agente/playbook-de-ventas) en lugar de meterlo en un documento.

### Un mensaje no sale

Mira el estado del mensaje en el chat.

| Estado o aviso | Qué hacer |
| --- | --- |
| **No se pudo entregar**, con un código | Busca el código en [Reglas de WhatsApp](/docs/canales/reglas-de-whatsapp#errores-de-entrega-mas-comunes) |
| **131047** o «La ventana de 24 h está cerrada» | Envía una [plantilla aprobada](/docs/campanas/plantillas) |
| **No se pudo confirmar** que el mensaje saliera | Si no lo ves en el teléfono del cliente, vuelve a enviarlo |
| «Se publicó una versión nueva de Orkestal y este mensaje NO se envió» | Recarga la página: el texto se conserva; reenvíalo |
| El mensaje se queda en «Enviando» | Recarga y revisa tu conexión; si persiste, el canal pudo desconectarse |

Si los mensajes de tu equipo se guardan pero no llegan, revisa también que en WhatsApp tengas un **método de pago en WhatsApp Manager**.

### No llegan mensajes de clientes

| Canal | Qué revisar |
| --- | --- |
| **WhatsApp** | Busca un aviso rojo arriba del panel («WhatsApp no está recibiendo mensajes»). Pulsa **Reactivar recepción**. Si pide **Reconectar WhatsApp**, vuelve a conectar. Mira [WhatsApp](/docs/canales/whatsapp#si-dejas-de-recibir-mensajes) |
| **WhatsApp por Coexistencia** | Abre la app de WhatsApp Business: Meta desconecta números inactivos pasados 14 días |
| **Instagram / Messenger** | Que el canal siga conectado y que no hayas quitado el acceso desde Meta; si lo quitaste, reconecta |
| **Telegram** | Que el token del bot siga vigente y el canal esté activo |
| **Un chat concreto** | Que no esté en **Archivados**, **Resueltos** o **Bloqueados**, y que el contacto no esté bloqueado |

Manda un mensaje de prueba a tu propio número para confirmar.

### Un documento no se procesa

| Estado | Qué hacer |
| --- | --- |
| **Falta clave de IA** | Guarda tu clave en Configuración; Orkestal reprocesa solo |
| **Procesando** por mucho tiempo | Espera unos minutos; si sigue, elimínalo y súbelo de nuevo |
| **Error** | Revisa que el archivo no esté dañado ni protegido, que tenga texto (un PDF escaneado como imagen no se puede leer) y que esté en un formato admitido (PDF, TXT, MD, CSV, XLSX) |

Mira [Base de conocimiento](/docs/conocimiento/base-de-conocimiento).

### Una plantilla no se aprueba

- **Pendiente:** Meta tarda en revisar. Pulsa **Sincronizar con Meta** para traer el estado más reciente.
- **Rechazada:** ajusta el texto (más claro, sin tono promocional si es *Utility*, sin variables sin contexto) y crea una nueva con otro nombre.
- **No aparece en la lista:** pulsa **Sincronizar con Meta**.
- **Error al crear:** Orkestal muestra el motivo de Meta. Revisa que cada variable tenga un ejemplo.

Mira [Plantillas](/docs/campanas/plantillas).

### Mi campaña está bloqueada

Orkestal bloquea las campañas cuando la **calidad de tu número** está en amarillo o rojo, incluidas las ya programadas. El bloqueo se levanta solo cuando Meta vuelve a marcarlo en verde. Revisa quejas y reportes recientes, baja el ritmo de envíos y espera. Mira [Reglas de WhatsApp](/docs/canales/reglas-de-whatsapp#calidad-de-tu-numero).

### Un flujo no se dispara

Revisa en este orden:

1. **¿Está activo?** Un flujo pausado no se ejecuta.
2. **¿El Cuando es de los que funcionan?** Algunas opciones de tiempo (día específico, fuera de horario, ventana horaria) **nunca se disparan**. Mira [Cuando](/docs/flujos/cuando).
3. **«Nuevo lead»** solo aplica a contactos con la etiqueta `nuevo_lead`.
4. **«Cambió la etapa del lead»** se dispara cuando un **flujo** cambia la etapa, no cuando alguien la cambia a mano.
5. **¿Ya se ejecutó en esa conversación?** Los mensajes disparados por un mensaje del cliente salen **una sola vez por conversación**.
6. **Esperas de tiempo:** máximo 23 horas en minutos u horas; se cancelan si el cliente contesta antes.
7. **¿Necesita una integración?** Telegram, Sheets o Calendar deben estar conectados.
8. **Un mensaje libre no llega:** puede estar fuera de la ventana de 24 horas; usa una plantilla.

### Una integración no funciona

| Integración | Qué revisar |
| --- | --- |
| **Google Calendar / Sheets** | Que la tarjeta diga Conectado; si cambiaste la contraseña de Google o quitaste el acceso, reconecta |
| **Stripe** | Que la clave siga vigente y con permiso de escritura en Payment Links |
| **WooCommerce** | Que el indicador diga «Webhook verificado recientemente» y que las claves REST sigan activas |
| **Mercado Libre** | Que el SKU sea idéntico en ambos lados; revisa tus notificaciones |
| **Todas** | Las **reglas de uso** pueden estar impidiendo que el agente la use. Mira [Integraciones: resumen](/docs/integraciones/resumen#reglas-de-uso-para-el-agente) |

### Equipo y acceso

| Síntoma | Qué hacer |
| --- | --- |
| Una persona invitada no entra a tu equipo | Debe usar el **enlace de su correo de invitación**; si se registró por su cuenta creó otra cuenta. Reenvía la invitación |
| Un Agente no ve conversaciones | Es lo esperado: un Agente solo ve **las asignadas a él**. Delega o activa la asignación automática |
| Un Manager no ve Facturación o Configuración | Son solo para Admin |
| No te asignan conversaciones | Marca que estás **disponible**; quizá te desconectó la inactividad |

### La pantalla se ve rara o se queda en blanco

- **Recarga la página.** Si ves el aviso «Hay una versión nueva de Orkestal», pulsa **Recargar**.
- Si usas el **traductor automático del navegador**, desactívalo para Orkestal: puede romper la pantalla.
- Prueba en una ventana privada o con extensiones desactivadas (los bloqueadores de anuncios pueden impedir el inicio de sesión de Meta).

### Si nada de esto resuelve tu caso

Escríbenos con los datos de la lista de [Soporte](/docs/ayuda/soporte#que-incluir-en-tu-mensaje): la respuesta es más rápida si nos das el contacto, la hora aproximada y qué esperabas que pasara.


## Preguntas frecuentes

> Respuestas cortas a lo que más nos preguntan sobre qué es Orkestal, cuánto cuesta, qué canales soporta, cómo trabaja la IA y qué pasa con tus datos.
Fuente: https://orkestaliq.com/docs/ayuda/preguntas-frecuentes

### Sobre el producto

#### ¿Qué es Orkestal?

Una plataforma para atender a tus clientes por mensajería con un **agente de IA que conoce tu negocio** y una **bandeja compartida** para tu equipo. Mira [Qué es Orkestal](/docs/empezar/que-es-orkestal).

#### ¿En qué canales funciona?

**WhatsApp, Instagram, Messenger y Telegram.** Todas las conversaciones llegan a una sola bandeja. El plan Starter incluye **un canal** conectado. Mira [Canales](/docs/canales/resumen).

#### ¿Necesito saber programar o contratar a alguien?

No. **Orki**, el asistente de instalación, te acompaña a configurar tu cuenta: te propone cada paso y tú apruebas lo que se aplica. Mira [Orki](/docs/empezar/orki) y [Primeros pasos](/docs/empezar/primeros-pasos).

#### ¿Qué tanto puedo personalizar mi agente?

Defines su tono, su información, su objetivo y sus reglas; qué acciones realiza; y cuándo pasa una conversación a tu equipo. Mira [Perfil y estilo](/docs/agente/perfil-y-estilo).

#### ¿Qué pasa cuando el agente no sabe algo?

No debe inventar. Si no encuentra la respuesta en tus fuentes, la pregunta queda registrada en **Brechas de Conocimiento** para que la cubras, y puedes definir reglas para que **pase la conversación a una persona**. Mira [Relevo humano](/docs/agente/relevo-humano).

#### ¿El agente responde las 24 horas?

Sí, por defecto. Puedes definir un **horario de atención** y un mensaje de fuera de horario. Mira [Perfil y estilo](/docs/agente/perfil-y-estilo#horario-de-atencion).

#### ¿Puedo seguir contestando yo desde mi celular?

Sí. Con la conexión de WhatsApp por **Coexistencia**, tu número sigue funcionando en la app de WhatsApp Business y en Orkestal a la vez. Cuando respondes a mano, la IA se pausa en ese chat. Mira [WhatsApp](/docs/canales/whatsapp).

#### ¿Con qué herramientas se conecta?

Google Calendar, Google Sheets, Stripe, WooCommerce, Mercado Libre, Notion, Envia.com, y más mediante n8n y la API. Mira [Integraciones](/docs/integraciones/resumen).

#### ¿Hay una app para el celular?

Orkestal funciona en el navegador del celular y se puede agregar a la pantalla de inicio para recibir notificaciones. Mira [Notificaciones](/docs/atencion/notificaciones).

### Precios y facturación

#### ¿Cuánto cuesta?

El plan Starter cuesta **$499 MXN al mes**. No incluye el consumo de IA (lo cobra tu proveedor) ni los mensajes de WhatsApp (los cobra Meta). Mira [Planes y facturación](/docs/cuenta/planes-y-facturacion).

#### ¿Qué es la clave de API y cuánto cuesta la IA?

Es la llave de **tu propia cuenta** con OpenAI o Google. Orkestal la usa para que tu agente piense y conteste, y tu proveedor te cobra directo por el uso. El costo depende de cuántas conversaciones atiendas y del modelo; puedes poner límites de gasto en tu cuenta del proveedor. Mira [Clave de IA](/docs/agente/clave-de-ia).

#### ¿Cómo funciona la prueba gratis?

Registras tu tarjeta al empezar y tienes un periodo para instalar y probar tu agente con tus propios clientes. El primer cobro del plan llega cuando termina la prueba; en **Facturación** ves cuántos días te quedan. Al registrar la tarjeta se hace además un cargo único mínimo de verificación. Mira [Planes y facturación](/docs/cuenta/planes-y-facturacion#la-prueba-gratis).

#### ¿Qué pasa si no pago?

Si un pago falla, recibes un aviso para actualizar tu método de pago. Si no se regulariza, la cuenta se **suspende** y el agente deja de contestar. Tus datos se conservan, y el servicio vuelve en cuanto pagas. Mira [Planes y facturación](/docs/cuenta/planes-y-facturacion#si-un-pago-falla).

#### ¿Hacen soluciones a la medida?

Sí: agentes de IA, automatizaciones e integraciones para los procesos de tu empresa, desde **$500 USD al mes**. Escribe a contacto@orkestaliq.com.

#### ¿Tienen opción para agencias?

Sí. Una agencia administra a varios negocios desde una cuenta matriz, cada cliente en su subcuenta, y puede usar su marca y su dominio. Mira [Agencias](/docs/cuenta/agencias).

### WhatsApp

#### ¿Por qué no puedo escribirle a un cliente?

Pasaron más de 24 horas desde su último mensaje. Fuera de esa ventana solo puedes usar una **plantilla aprobada** por Meta. Mira [Reglas de WhatsApp](/docs/canales/reglas-de-whatsapp).

#### ¿Cuántos mensajes de WhatsApp son gratis?

Meta incluye una bolsa mensual de mensajes de servicio gratuitos por cuenta de WhatsApp Business (los primeros 1,000 del mes). Los chats que llegan desde un anuncio abren una ventana de 72 horas y no la consumen. Consulta las tarifas vigentes en la documentación de Meta.

#### ¿Puedo mandar mensajes masivos?

Sí, con **plantillas aprobadas** y desde **Campañas**. Si la calidad de tu número baja a amarillo o rojo, Orkestal bloquea los envíos. Mira [Campañas](/docs/campanas/campanas).

#### ¿Puedo conectar dos números de WhatsApp?

No en la misma cuenta: hay **una cuenta por canal**. Mira [Canales, resumen](/docs/canales/resumen#una-cuenta-por-canal).

### Equipo

#### ¿Puedo dar acceso a mi equipo?

Sí, con tres roles: Admin, Manager y Agente. Un Agente solo ve las conversaciones asignadas a él. Mira [Equipo y roles](/docs/atencion/equipo-y-roles).

#### ¿Cómo se reparten las conversaciones?

Con la **asignación automática**: cuando un cliente necesita atención humana, se asigna a la persona disponible con menos conversaciones. Mira [Equipo y roles](/docs/atencion/equipo-y-roles#asignacion-automatica).

### Datos y seguridad

#### ¿Qué hacen con mis datos y los de mis clientes?

Los usamos solo para prestarte el servicio, no los vendemos, y los datos de Meta nunca se usan para entrenar modelos. Mira [Seguridad y privacidad](/docs/cuenta/seguridad-y-privacidad).

#### ¿Mis claves están seguras?

Las claves de IA, los tokens de tus canales y las credenciales de integraciones se guardan **cifrados**. Las API keys se muestran una sola vez y solo guardamos su huella.

#### ¿Cómo elimino mis datos?

Desde el panel, desde la configuración de Facebook o Instagram, o escribiendo a contacto@orkestaliq.com. La eliminación se completa en un plazo máximo de 30 días. Mira [Eliminación de datos](/eliminacion-datos).

### Soporte

#### ¿Cómo contacto a una persona?

Escribe a **soporte@orkestaliq.com**. Mira [Soporte](/docs/ayuda/soporte).


## Soporte

> Cómo hablar con una persona de Orkestal, qué incluir en tu mensaje para que te ayudemos más rápido y qué dirección usar para cada tema.
Fuente: https://orkestaliq.com/docs/ayuda/soporte

Si la documentación no resolvió tu duda, escríbenos. Una persona de Orkestal te responde.

### A dónde escribir

| Tema | Dirección |
| --- | --- |
| **Soporte técnico y de uso**: algo no funciona, dudas de configuración, facturación | [soporte@orkestaliq.com](mailto:soporte@orkestaliq.com) |
| **Asuntos generales, comerciales y legales**: soluciones a la medida, agencias, privacidad, eliminación de datos | [contacto@orkestaliq.com](mailto:contacto@orkestaliq.com) |

Dentro del panel también hay un formulario de **soporte** en el encabezado. Y [Orki](/docs/empezar/orki) responde dudas sobre la plataforma y puede diagnosticar tu cuenta.

### Qué incluir en tu mensaje

Mientras más datos nos des, más rápido llegamos a la causa.

1. **Tu correo de acceso** y el **nombre de tu negocio**.
2. **Qué esperabas que pasara** y **qué pasó en cambio**.
3. **Cuándo ocurrió**, con fecha y hora aproximada, y tu zona horaria.
4. **El contacto o la conversación** afectada (nombre o teléfono).
5. **El canal**: WhatsApp, Instagram, Messenger o Telegram.
6. **Una captura de pantalla** del error o del aviso, sin datos sensibles.
7. **Qué ya probaste**, por ejemplo lo que viste en [Solución de problemas](/docs/ayuda/solucion-de-problemas).

> [!CUIDADO]
> **Nunca nos envíes por correo ni por chat tu contraseña, tu clave de IA, tus tokens ni tus API keys.** Nuestro equipo no te las pedirá. Si crees que una credencial se expuso, revócala o rótala.

### Antes de escribir: revisiones rápidas

- ¿Aparece algún **aviso rojo o amarillo** arriba del panel? Casi siempre explica el problema.
- ¿Recargaste la página? Una versión nueva de Orkestal puede dejar una pestaña vieja funcionando mal.
- ¿El **simulador** reproduce el problema? Ayuda a distinguir si es de configuración o del canal.

### Sugerencias de producto

¿Te falta una función o una integración? Cuéntanos. En **Integraciones** hay un botón **Solicitar nueva integración**, y puedes escribirnos a soporte@orkestaliq.com con lo que necesitas y para qué.

### Estado de WhatsApp y Meta

Algunos problemas con WhatsApp, Instagram o Messenger no dependen de Orkestal sino de Meta (límites, calidad de tu número, revisión de plantillas). Orkestal te muestra el motivo que Meta devuelve; ese código es lo más útil para entender qué pasó. Mira [Reglas de WhatsApp](/docs/canales/reglas-de-whatsapp).

### Avisos legales

- [Términos de servicio](/terminos)
- [Aviso de privacidad](/privacy)
- [Eliminación de datos](/eliminacion-datos)
- [Aviso legal](/aviso-legal)