API de chatbot
Una API de chatbot para tus apps, tu backend y tus datos
La API REST de intoCHAT permite que tu servidor hable con el agente que entrenaste en el panel. Envía un mensaje y recibe la misma respuesta que daría el widget de chat, lee conversaciones y leads, mantén los contactos sincronizados, añade conocimiento y suscribe webhooks, con JSON sobre HTTPS y una especificación OpenAPI 3.1 que describe cada endpoint.
Tu chatbot no debería quedarse en el widget de la web
El widget cubre a los visitantes de tu web. Pero las mismas preguntas llegan también a tu app móvil, a tu portal de clientes, a una herramienta interna o a un formulario de soporte, y las conversaciones y leads que recoge el agente tienen que acabar en tu CRM, tu data warehouse o tu sistema de tickets, no solo en un panel. Reconstruir el bot para cada sitio supone una segunda base de conocimiento y un segundo conjunto de reglas que acaban separándose. Con una API de chatbot, cada canal que construyes usa el único agente que ya entrenaste, y tus propios sistemas leen lo que ha recogido.
Lo que te da la API de chatbot
Un agente, entrenado una vez, que responde dondequiera que corra tu código.
El mismo agente, las mismas respuestas
Una respuesta a través de la API la escribe el mismo código que una respuesta en el widget, con el mismo conocimiento, las mismas instrucciones y el mismo modelo. Tus acciones de API, botones personalizados, formularios de chat y reservas también funcionan en los chats por API.
Conversaciones que continúan
Pasa tu propio sessionId, por ejemplo el ID de usuario, y la misma persona continúa siempre la misma conversación. El agente ve los últimos 40 mensajes como historial, y cada chat por API aparece en la pestaña Conversations junto a los chats del widget.
Tus datos en tus sistemas
Recorre las conversaciones con sus transcripciones completas, los leads con sus campos personalizados y los contactos, de más reciente a más antiguo, con el parámetro since para sincronizaciones incrementales. El orden es fijo, así que nada se lee dos veces ni se pierde mientras llegan chats nuevos.
Una clave con sus ámbitos para cada tarea
Da a cada integración su propia clave con solo los ámbitos que necesita, por ejemplo conversations:read para un informe y chat para tu app. Las claves pertenecen a la cuenta, no a una persona, y dejan de funcionar en cuanto las revocas.
Una especificación OpenAPI para empezar
Cada endpoint, campo, error y contenido de webhook está descrito en un único archivo OpenAPI 3.1. Impórtalo en Postman o Insomnia, o genera una biblioteca cliente con una herramienta como OpenAPI Generator.
Cómo empezar con la API de chatbot
Entrena a tu agente
Crea el agente en el panel, añade tu web, archivos o preguntas y respuestas, y define sus instrucciones y su modelo. La API usa el agente tal y como está configurado allí; los agentes se crean y se cambian en el panel, no a través de la API.
Crea una clave de API
En la barra lateral, en Settings, haz clic en API keys. Ponle un nombre a la clave, deja Every scope, including ones added later o elige Only the scopes I choose, y haz clic en Create key. Copia la clave, que empieza por ic_live_, en una variable de entorno de tu servidor: solo se muestra una vez.
Envía tu primer mensaje
Envía el mensaje con un POST a /api/v1/agents/{agentId}/chat, con la clave como token Bearer en la cabecera Authorization. La respuesta JSON trae el texto, el conversationId y el sessionId para continuar, las fuentes usadas y, si los hay, preguntas de seguimiento, botones, productos, formularios u horarios para reservar. Con stream en true recibes el texto a medida que se escribe.
Sincroniza y suscríbete
Lee conversaciones, leads y contactos de forma periódica con since, añade textos o pares de preguntas y respuestas cuando cambie tu contenido, y suscribe un webhook a eventos como lead.created o handoff.requested para que lleguen a tu servidor en cuanto ocurren.
La API de chatbot en detalle
Enviar un mensaje
El endpoint de chat acepta un mensaje de hasta 10.000 caracteres, un conversationId o sessionId opcional para continuar, stream para recibir el texto en streaming y timeZone para los horarios de reserva. Sin ninguno de los dos ID, cada mensaje abre una conversación nueva.
Campos de respuesta estructurados
Además de la respuesta en Markdown, la respuesta de la API incluye las páginas usadas, preguntas de seguimiento sugeridas, botones personalizados, fichas de producto con precio y disponibilidad, un formulario de chat o de contacto ofrecido, horarios libres, bloques de respuestas enriquecidas como tablas y tarjetas, y el estado del chat en vivo.
Tiene en cuenta el chat en vivo
Si alguien de tu equipo ha tomado la conversación en la bandeja del chat en vivo, tu mensaje se guarda, la respuesta queda vacía y liveChat vale paused. Lee las respuestas de tu compañero, con su nombre, desde el endpoint de la conversación. Esos mensajes no consumen mensajes de tu plan.
Conversaciones e Inbox
Lista las conversaciones de un agente, del widget y de la API, con temas, sentimiento, estado del chat en vivo y puntuación CSAT, fíltralas por estado en el Inbox y obtén una con todos sus mensajes. Con conversations:write fijas su estado, prioridad, etiquetas y responsable en el Inbox.
Leads y contactos
Lista los leads con nombre, email, teléfono y los campos personalizados de tu formulario. Crea o actualiza contactos por tu propio ID externo o por email, cada uno con hasta 50 atributos personalizados, para que los contactos del agente coincidan con los usuarios de tu app.
Conocimiento que puedes actualizar
Lista las fuentes de un agente con su estado de entrenamiento, añade un texto o un par de pregunta y respuesta, que se entrena al momento, y elimina una fuente junto con lo que el agente aprendió de ella. Un par con la misma pregunta se actualiza en lugar de duplicarse.
Webhooks y eventos
Suscribe hasta 25 webhooks por agente a eventos como lead.created, form.submitted, booking.created, handoff.requested y conversation.status_changed, cada uno firmado con su propio secreto. O consulta los últimos eventos de un tipo, con la misma estructura que una entrega de webhook.
Límites y errores claros
Cada clave puede hacer 60 peticiones por minuto, y cada respuesta lleva las cabeceras X-RateLimit. Los errores tienen siempre la misma forma JSON con un código estable, como insufficient_scope, rate_limited o message_limit_reached, para que tu código pueda tratar cada caso.
Preguntas frecuentes
¿Qué es una API de chatbot?
Una API de chatbot permite que tu propio software envíe mensajes a un chatbot y reciba sus respuestas, en lugar de hacerlo solo a través de una ventana de chat en una web. La API REST de intoCHAT lo hace con el agente que entrenaste en el panel, y además permite a tu servidor leer sus conversaciones, leads y contactos, actualizar su conocimiento y suscribirse a sus eventos.
¿Qué plan necesito para la API?
La API está incluida en Starter, Pro y Enterprise. En el plan Free no puedes crear claves. Si una cuenta vuelve a Free, sus claves existentes responden a cada petición con el error plan_required y vuelven a funcionar en cuanto la cuenta está al menos en Starter.
¿Las respuestas por API cuentan como mensajes?
Sí. Cada respuesta que el agente escribe a través de la API cuenta en tu plan igual que una respuesta en el widget: un mensaje con el modelo predeterminado, más con un modelo mayor, y cuenta también para el tope mensual del agente si fijaste uno. Leer conversaciones, leads y contactos, y añadir o eliminar fuentes, no consume mensajes.
¿Puedo llamar a la API desde el navegador o mi código de inserción?
No. La API es para servidores: no envía cabeceras CORS, y una clave en una página web la podría copiar cualquiera. Para mostrar un chat en tu web, usa la etiqueta script o el SDK de JavaScript, y llama a la API desde tu backend. Solo la especificación OpenAPI se puede cargar desde cualquier sitio.
¿Cómo continúo una conversación?
Envía el conversationId de una respuesta anterior, o tu propio sessionId, por ejemplo el ID de usuario: el mismo sessionId continúa siempre la misma conversación. A través de la API solo se pueden continuar las conversaciones iniciadas por la API, y el agente ve los últimos 40 mensajes como historial.
¿Qué límites de frecuencia hay?
Cada clave puede hacer 60 peticiones por minuto entre todos los endpoints, y una cuenta puede tener hasta 20 claves activas. Un agente responde como mucho a 1.000 mensajes por hora, widget y API juntos, y una respuesta tiene que terminar en 55 segundos o la petición acaba con un error de timeout.
¿Qué no puede hacer todavía la API?
Todavía no hay endpoints para crear o cambiar agentes, enviar formularios de chat, reservar citas o tomar el control de un chat en vivo. Por la API añades textos y pares de preguntas y respuestas; las páginas web, archivos y páginas de Notion se añaden en el panel. Los mensajes por API no pueden llevar archivos, y las acciones de cliente, que se ejecutan en el navegador del visitante, no se ofrecen en los chats por API.
¿En qué se diferencia de las acciones de IA?
Van en direcciones opuestas. Con las acciones de IA, el agente llama a tu API durante un chat para consultar algo, como un pedido o una cuenta. Con la API de chatbot, es tu servidor el que llama a intoCHAT para enviar mensajes y leer datos. Muchas configuraciones usan ambas.
Construye sobre el agente que ya entrenaste
Crea tu agente gratis y entrénalo con tu web, después pasa a Starter, crea una clave de API y envía tu primer mensaje con un solo comando curl.
Crea tu agente gratisPlan gratuito, sin tarjeta de crédito.