API REST

La API REST permite que tu propio servidor hable con tus agentes. Envía un mensaje y recibe la respuesta del agente, lee conversaciones y leads, añade o elimina fuentes de conocimiento y suscribe webhooks a los eventos de un agente, con JSON sobre HTTPS. Las apps de Zapier y Make están construidas sobre ella. Una respuesta a través de la API la escribe el mismo código que una respuesta en el widget del chat, con el mismo conocimiento y los mismos ajustes.

La API es para servidores. No envía cabeceras CORS, así que una página web de otro sitio no puede llamarla, y tu clave de API nunca debe aparecer en un navegador ni en tu código de inserción. Para mostrar un chat en tu web, usa la etiqueta script. Para recibir los eventos en cuanto ocurren, usa los webhooks.

Qué planes incluyen la API

La API está incluida en Starter, Pro y Enterprise. En Free no puedes crear claves.

Si una cuenta vuelve a Free, sus claves siguen en la lista, pero cada petición recibe un error 403 con el código plan_required. Vuelven a funcionar en cuanto la cuenta está en Starter o superior.

Cada respuesta que un agente escribe a través de la API cuenta como un mensaje de tu plan, exactamente igual que una respuesta en el widget, y cuenta para el tope mensual de mensajes del agente si has fijado uno. Leer datos, y añadir o eliminar fuentes, no gasta mensajes. Consulta Qué cuenta como mensaje.

Crear una clave de API

1. En la barra lateral, en Settings, haz clic en API keys.
2. En Create a key, ponle a la clave un Name que reconozcas más adelante, por ejemplo CRM sync.
3. En Access, deja Every scope, including ones added later, o elige Only the scopes I choose y marca los que necesita esta clave. Consulta Ámbitos.
4. Haz clic en Create key.
5. Haz clic en Copy, guarda la clave donde tu servidor pueda leerla, por ejemplo en una variable de entorno, y haz clic en I've saved it.

Una clave tiene el aspecto ic_live_ seguido de 32 letras y dígitos. Solo se muestra una vez: intoCHAT guarda únicamente una huella de ella, así que nadie puede volver a mostrártela. Si la pierdes, revócala y crea una nueva.

Una clave pertenece a la cuenta, no a la persona que la creó. Funciona para todos los agentes de la cuenta, dentro de sus ámbitos, y sigue funcionando si esa persona deja el equipo. Una cuenta puede tener hasta 20 claves activas.

Solo el propietario de la cuenta y los admins pueden crear y revocar claves. Los editors y los viewers ven la lista de claves, solo con sus primeros caracteres. Consulta Miembros del equipo y roles.

La lista de claves

Cada clave muestra su nombre, sus primeros caracteres (por ejemplo ic_live_3f9A…), sus ámbitos, cuándo se creó y cuándo se usó por última vez. Last used se actualiza como mucho una vez por minuto.

Revocar una clave

Haz clic en Revoke junto a la clave y confirma. La clave deja de funcionar desde su siguiente petición, y no se puede deshacer. Revoca una clave en cuanto pienses que otra persona puede tenerla.

Revocar una clave también elimina los webhooks que suscribió, por ejemplo para Zapier o Make, con su historial de envíos: de otro modo, nada podría eliminarlos. Los webhooks que añadiste en la pestaña Leads no se ven afectados.

Autenticación

Envía la clave en la cabecera Authorization de cada petición:

curl https://www.intochat.ai/api/v1/agents \
  -H "Authorization: Bearer ic_live_YOUR_KEY"

Todos los endpoints están bajo https://www.intochat.ai/api/v1. Las peticiones con cuerpo envían JSON con Content-Type: application/json, y todas las respuestas son JSON, salvo una respuesta de chat en streaming. La API no usa cookies ni sesión iniciada: solo la clave decide qué puede hacer una petición.

Una clave que falta, mal formada, desconocida o revocada recibe un error 401 con el código unauthorized.

Ámbitos

Un ámbito (scope) permite a una clave usar un grupo de endpoints. Una clave creada con Every scope, including ones added later puede usar todos los endpoints, también los que se añadan en el futuro.

conversations:read también cubre los eventos de traspaso, chat en vivo y conversación nueva de Listar eventos.

Una petición a un endpoint para el que la clave no tiene ámbito recibe un error 403 con el código insufficient_scope. Para cambiar los ámbitos de una clave, crea una clave nueva y revoca la anterior.

Límites de frecuencia

Cada clave puede hacer 60 peticiones por minuto, entre todos los endpoints. Cada respuesta que superó la comprobación de la clave lleva estas cabeceras:

Por encima del límite, la petición recibe un error 429 con el código rate_limited y una cabecera Retry-After con los segundos que hay que esperar.

El chat tiene dos límites más que no dependen de la clave: los mensajes del plan, y que un agente responde como mucho 1.000 mensajes por hora, entre el widget y la API. Por encima de eso, una petición de chat recibe un error 429 con el código agent_busy.

Errores

Todos los errores tienen la misma forma:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key doesn't have the \"chat\" scope."
  }
}

Usa code en tu código; message lo explica para una persona y puede cambiar.

Un agente, una conversación o una fuente que pertenece a otra cuenta recibe 404, igual que uno que no existe.

Paginación

Listar conversaciones y listar leads devuelven una página cada vez, de la más reciente a la más antigua. Admiten estos parámetros de consulta:

Una página tiene este aspecto:

{
  "data": [ ],
  "hasMore": true,
  "nextCursor": "MjAyNi0xMC0wNFQwOTowMDowMC4wMDBafGNsdjEyMw"
}

Pide la página siguiente con ?cursor= y ese valor, con los mismos limit y since, hasta que hasMore sea false y nextCursor sea null. El orden lo fija la fecha de creación, así que la actividad nueva mientras recorres las páginas no hace que un elemento aparezca dos veces ni que falte. Para sincronizar con regularidad, guarda la hora en que empezaste la última sincronización y pásala como since la próxima vez.

Listar agentes

GET /api/v1/agents · ámbito agents:read

Todos los agentes de la cuenta, del más reciente al más antiguo.

curl https://www.intochat.ai/api/v1/agents \
  -H "Authorization: Bearer ic_live_YOUR_KEY"

{
  "data": [
    {
      "id": "AGENT_ID",
      "name": "Acme Assistant",
      "private": false,
      "status": "trained",
      "trainedAt": "2026-10-02T09:00:00.000Z",
      "characters": 48210,
      "counts": { "conversations": 312, "messages": 2240, "leads": 41, "sources": 18 },
      "createdAt": "2026-09-01T09:00:00.000Z",
      "updatedAt": "2026-10-02T09:00:00.000Z"
    }
  ]
}

status es untrained, training, trained o error (el último entrenamiento falló). characters es cuántos caracteres de entrenamiento usan las fuentes entrenadas del agente.

Obtener un agente

GET /api/v1/agents/{agentId} · ámbito agents:read

Un agente, en data, con los mismos campos que en Listar agentes.

Enviar un mensaje

POST /api/v1/agents/{agentId}/chat · ámbito chat

Envía un mensaje al agente y devuelve su respuesta. El agente responde como en el widget: a partir de su conocimiento y sus instrucciones, con tus acciones API, botones personalizados, formularios de chat, reservas, traspaso por correo y chat en vivo donde los hayas configurado.

Sin conversationId ni sessionId, cada mensaje empieza una conversación nueva.

curl https://www.intochat.ai/api/v1/agents/AGENT_ID/chat \
  -H "Authorization: Bearer ic_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Do you ship to Switzerland?", "sessionId": "customer-4821" }'

{
  "reply": "Yes, we ship to Switzerland. Delivery takes 3 to 5 working days.",
  "conversationId": "CONVERSATION_ID",
  "sessionId": "icapi5f0c2b9e4d7a41f8a3c6e1b2d9f07a64",
  "sources": [
    { "title": "Shipping", "url": "https://www.example.com/shipping" }
  ],
  "followUps": ["How much does shipping cost?", "Can I track my order?"],
  "buttons": [],
  "products": [],
  "form": null,
  "leadForm": null,
  "booking": null,
  "liveChat": null
}

En qué se diferencian los chats por API del widget

• La conversación se guarda como un chat del widget y aparece en la pestaña Conversations del agente, con sus leads, valoraciones y estadísticas. No tiene país ni página.
• Los dominios permitidos, los países bloqueados y los mensajes por visitante no se aplican: no hay página ni dirección del visitante que comprobar. Sí se aplican los mensajes del plan, el tope mensual del agente y el límite de frecuencia de la clave.
• Un agente privado rechaza los chats por API con agent_private.
• Las acciones del lado del cliente se ejecutan en el navegador de un visitante, así que el agente no las tiene disponibles en los chats por API. Las acciones API, los botones, los formularios y las reservas funcionan.
• No se pueden adjuntar archivos y no hay chats temporales.
• Solo las conversaciones empezadas a través de la API se pueden continuar a través de la API. El agente ve como historial los últimos 40 mensajes de la conversación.
• Mientras alguien de tu equipo ha tomado el control del chat en la bandeja de Live chat, tu mensaje se guarda, reply está vacío y liveChat es paused. Las respuestas del miembro del equipo aparecen en la conversación: léelas con Obtener una conversación, donde tienen un authorName. Un mensaje durante una toma de control no gasta ningún mensaje de tu plan.
• Una respuesta que tarda más de 55 segundos termina con un error 504 y el código timeout. Puede contar igualmente como mensaje.

Streaming

Con "stream": true, la respuesta es el texto de la respuesta a medida que se escribe, como text/plain, sin los campos JSON. Las cabeceras X-Conversation-Id y X-Session-Id llevan la conversación y la sesión, y X-Live-Chat el estado del chat en vivo cuando lo hay. Las fuentes, los botones y los demás bloques no se envían en streaming; léelos después con Obtener una conversación. Los errores son JSON, igual que sin streaming.

curl -N https://www.intochat.ai/api/v1/agents/AGENT_ID/chat \
  -H "Authorization: Bearer ic_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "What are your opening hours?", "stream": true }'

Listar conversaciones

GET /api/v1/agents/{agentId}/conversations · ámbito conversations:read

Las conversaciones del agente, del widget y de la API, de la más reciente a la más antigua, sin sus mensajes. Admite limit, cursor y since; consulta Paginación.

curl "https://www.intochat.ai/api/v1/agents/AGENT_ID/conversations?limit=50&since=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer ic_live_YOUR_KEY"

{
  "data": [
    {
      "id": "CONVERSATION_ID",
      "sessionId": "8f14e45f-ceea-467a-9575-1a2b3c4d5e6f",
      "channel": "widget",
      "createdAt": "2026-10-04T09:00:00.000Z",
      "lastActivityAt": "2026-10-04T09:12:00.000Z",
      "country": "CH",
      "page": "https://www.example.com/pricing",
      "messageCount": 6,
      "topics": ["Pricing"],
      "sentiment": "positive",
      "liveChat": null,
      "csatScore": null
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

channel es api para una conversación empezada a través de la API y, si no, widget (la etiqueta script, el iframe en la página, el enlace directo y el Playground). topics y sentiment los asigna el análisis de temas cuando está activado. liveChat es null, requested, active o ended. csatScore es la valoración del visitante de 1 a 5 después de un chat en vivo, o null.

Obtener una conversación

GET /api/v1/conversations/{conversationId} · ámbito conversations:read

Una conversación de cualquier agente de la cuenta, con todos sus mensajes en orden.

{
  "data": {
    "id": "CONVERSATION_ID",
    "agentId": "AGENT_ID",
    "sessionId": "icapi5f0c2b9e4d7a41f8a3c6e1b2d9f07a64",
    "channel": "api",
    "createdAt": "2026-10-04T09:00:00.000Z",
    "lastActivityAt": "2026-10-04T09:14:00.000Z",
    "country": null,
    "page": null,
    "topics": [],
    "sentiment": null,
    "handoffRequestedAt": null,
    "liveChat": { "status": "ended", "startedAt": "2026-10-04T09:05:00.000Z", "endedAt": "2026-10-04T09:13:00.000Z" },
    "csat": { "score": 5, "comment": "Quick and friendly.", "ratedAt": "2026-10-04T09:14:00.000Z" },
    "messages": [
      { "id": "MESSAGE_ID", "role": "assistant", "content": "Hello! How can I help you today?", "createdAt": "2026-10-04T09:00:00.000Z", "authorName": null, "sources": [] },
      { "id": "MESSAGE_ID", "role": "user", "content": "Can I change my delivery address?", "createdAt": "2026-10-04T09:01:00.000Z", "authorName": null, "sources": [] },
      { "id": "MESSAGE_ID", "role": "assistant", "content": "Yes, I'm on it. What's your order number?", "createdAt": "2026-10-04T09:06:00.000Z", "authorName": "Anna", "sources": [] }
    ]
  }
}

role es user para el visitante o tus mensajes por API, y assistant para el agente y tu equipo. authorName es el nombre de pila del miembro del equipo que escribió una respuesta de chat en vivo, o null cuando la escribió el agente. content es el texto sin los bloques de control del widget; las sources de una respuesta del agente listan las páginas que mostró. handoffRequestedAt es cuándo el agente envió la conversación a tu equipo por correo, o null. liveChat y csat son null cuando no hubo chat en vivo o valoración.

Listar leads

GET /api/v1/agents/{agentId}/leads · ámbito leads:read

Los leads del agente, del más reciente al más antiguo. Admite limit, cursor y since; consulta Paginación.

{
  "data": [
    {
      "id": "LEAD_ID",
      "email": "jane@example.com",
      "phone": null,
      "name": "Jane",
      "customFields": [{ "id": "FIELD_ID", "label": "Company", "value": "Acme" }],
      "source": "form",
      "conversationId": "CONVERSATION_ID",
      "collectedAt": "2026-10-04T09:03:00.000Z",
      "lastSeenAt": "2026-10-04T09:03:00.000Z",
      "submissionCount": 1
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

source es form para el formulario de leads o chat para datos de contacto escritos en un mensaje. customFields usa las etiquetas que tiene tu formulario ahora. lastSeenAt y submissionCount cambian cuando la misma persona vuelve a enviarlo. conversationId es null cuando se borró la conversación.

Listar fuentes

GET /api/v1/agents/{agentId}/sources · ámbito sources:read

Las fuentes de conocimiento del agente en el orden de su pestaña Knowledge, con el progreso del entrenamiento. El texto de una fuente no se incluye, salvo la pregunta y la respuesta de un par de pregunta y respuesta.

{
  "data": [
    {
      "id": "SOURCE_ID",
      "type": "qa",
      "title": "Do you ship to Switzerland?",
      "url": null,
      "filename": null,
      "question": "Do you ship to Switzerland?",
      "answer": "Yes, in 3 to 5 working days.",
      "characters": 71,
      "status": "trained",
      "error": null,
      "trainedAt": "2026-10-02T09:00:00.000Z",
      "createdAt": "2026-10-02T08:59:00.000Z",
      "updatedAt": "2026-10-02T09:00:00.000Z"
    }
  ],
  "training": { "total": 18, "trained": 18, "pending": 0, "processing": 0, "failed": 0, "done": true },
  "characters": { "used": 48210, "limit": 500000 }
}

type es website, file, text, qa o notion. status es pending, processing, trained o failed, con el motivo en error. characters.limit son los caracteres de entrenamiento por agente de tu plan.

Añadir una fuente

POST /api/v1/agents/{agentId}/sources · ámbito sources:write

Añade un texto o un par de pregunta y respuesta e inicia el entrenamiento, como hace la pestaña Knowledge. El agente usa la fuente nueva en cuanto está entrenada; sigue su status con Listar fuentes.

Un texto:

curl https://www.intochat.ai/api/v1/agents/AGENT_ID/sources \
  -H "Authorization: Bearer ic_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "text", "title": "Opening hours", "content": "We are open Monday to Friday, 9:00 to 17:00." }'

Un par de pregunta y respuesta:

{ "type": "qa", "question": "Do you ship to Switzerland?", "answer": "Yes, in 3 to 5 working days." }

{
  "data": { "id": "SOURCE_ID", "type": "text", "title": "Opening hours", "status": "pending", "characters": 44 },
  "result": "created",
  "training": { "total": 19, "trained": 18, "pending": 1, "processing": 0, "failed": 0, "done": false }
}

data tiene todos los campos de Listar fuentes; arriba se omiten algunos. result es created (estado 201), updated cuando ya existía un par con la misma pregunta, sin distinguir mayúsculas y minúsculas, y ahora tiene la respuesta nueva, o unchanged cuando ya tenía exactamente esta respuesta (ambos con estado 200). Un texto siempre se añade como fuente nueva. Un título y una pregunta pueden tener cada uno hasta 200 caracteres.

La fuente cuenta para los caracteres de entrenamiento del agente. Una fuente que superaría el límite de tu plan recibe un error 403 con el código character_limit_exceeded, y no se añade nada. Consulta Caracteres de entrenamiento por agente.

Eliminar una fuente

DELETE /api/v1/agents/{agentId}/sources/{sourceId} · ámbito sources:write

Elimina la fuente y lo que el agente aprendió de ella, al momento, como al eliminarla en la pestaña Knowledge. No hay que volver a entrenar nada más.

{ "id": "SOURCE_ID", "deleted": true, "training": { "total": 17, "trained": 17, "pending": 0, "processing": 0, "failed": 0, "done": true } }

Suscribir un webhook

POST /api/v1/agents/{agentId}/webhooks · ámbito webhooks:write

Suscribe un webhook a los eventos del agente: un REST hook, como los que usan los disparadores instantáneos de Zapier y Make. Después, intoCHAT envía cada evento a la dirección como se explica en Webhooks, firmado y con reintentos, igual que un webhook añadido en la pestaña Leads.

curl https://www.intochat.ai/api/v1/agents/AGENT_ID/webhooks \
  -H "Authorization: Bearer ic_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://hooks.example.com/intochat", "events": ["lead.created"], "source": "api" }'

{
  "id": "WEBHOOK_ID",
  "agentId": "AGENT_ID",
  "url": "https://hooks.example.com/intochat",
  "events": ["lead.created"],
  "source": "api",
  "secret": "whsec_…",
  "createdAt": "2026-10-08T09:00:00.000Z"
}

La respuesta tiene el estado 201. Guarda id para cancelar la suscripción más adelante. secret es el secreto de firma del webhook, y solo se devuelve aquí; úsalo para comprobar la firma si tu receptor puede hacerlo. Las herramientas que no pueden comprobar firmas, como Zapier y Make, pueden ignorarlo.

Un webhook suscrito aparece en la pestaña Leads del agente con una etiqueta via Zapier, via Make o via API, donde el propietario puede pausarlo o eliminarlo. Recuerda la clave que lo suscribió: revocar esa clave lo elimina. Un agente puede tener hasta 25 webhooks suscritos, aparte de los 5 añadidos en la pestaña Leads; por encima de eso, la petición recibe un error 400.

Cancelar la suscripción de un webhook

DELETE /api/v1/webhooks/{webhookId} · ámbito webhooks:write

Elimina un webhook que se suscribió a través de la API, con su historial de envíos. Puede hacerlo cualquier clave de la misma cuenta. Un webhook añadido en la pestaña Leads, un webhook de otra cuenta o uno ya eliminado recibe 404.

{ "id": "WEBHOOK_ID", "deleted": true }

Listar eventos

GET /api/v1/agents/{agentId}/events/{event} · ámbito agents:read, más leads:read o conversations:read

Los últimos eventos de un tipo del agente, del más reciente al más antiguo, cada uno con exactamente la misma forma que el cuerpo de un envío de webhook. Las herramientas de automatización lo consultan periódicamente en lugar de esperar a un webhook, por ejemplo para mostrar datos de ejemplo reales. Admite limit, de 1 a 100 (por defecto, 20).

curl "https://www.intochat.ai/api/v1/agents/AGENT_ID/events/lead.created?limit=5" \
  -H "Authorization: Bearer ic_live_YOUR_KEY"

{
  "data": [
    {
      "id": "LEAD_ID",
      "event": "lead.created",
      "created_at": "2026-10-07T09:30:00.000Z",
      "agent": { "id": "AGENT_ID", "name": "Acme Assistant" },
      "data": {
        "leadId": "LEAD_ID",
        "agentId": "AGENT_ID",
        "agentName": "Acme Assistant",
        "email": "jane@example.com",
        "phone": null,
        "name": "Jane",
        "customFields": [],
        "source": "form",
        "conversationId": "CONVERSATION_ID",
        "collectedAt": "2026-10-07T09:30:00.000Z"
      }
    }
  ]
}

Las diferencias con un envío:

• id es el ID del registro, no un ID de envío, así que el mismo evento siempre tiene el mismo id: el ID del lead, del envío del formulario, de la reserva, de la petición de devolución o de la conversación. En los traspasos y las peticiones de chat en vivo es el ID de la conversación, dos puntos y la hora en milisegundos, porque una conversación puede volver a pedirlo más tarde.
• created_at es cuándo se guardó el registro.
• Los datos se reconstruyen a partir de lo que guarda intoCHAT. El summary de un traspaso no se guarda, así que es null, y test es false. Un traspaso que abrió un ticket de helpdesk lleva su ticket, igual que el webhook. El providerStatus de una reserva es pending mientras espera tu confirmación y, si no, accepted. Una petición de devolución tiene su status actual, requested o handled.
• Los datos de conversation.created tienen conversationId, channel (widget o api), page, country y createdAt.

Obtener eventos de ejemplo

GET /api/v1/agents/{agentId}/events/{event}/samples · ámbito agents:read

Hasta 3 de los últimos eventos del agente, como en Listar eventos, para que una herramienta siempre tenga datos a partir de los que asignar campos. Cuando el agente todavía no tiene ninguno, o la clave no tiene el ámbito que necesita ese evento (leads:read o conversations:read), devuelve en su lugar un ejemplo documentado con los mismos campos, y sample es true.

{
  "data": [
    {
      "id": "sample_booking.created",
      "event": "booking.created",
      "created_at": "2026-10-07T09:30:00.000Z",
      "agent": { "id": "AGENT_ID", "name": "Acme Assistant" },
      "data": { "bookingId": "sample_booking", "eventTitle": "30 min intro call", "attendeeEmail": "jane@example.com" }
    }
  ],
  "sample": true
}

Los data del ejemplo tienen todos los campos del evento; arriba se omiten algunos.

Límites

• La API está incluida a partir de Starter. En Free no se pueden crear claves y las existentes reciben plan_required.
• 60 peticiones por minuto por clave, y como mucho 20 claves activas por cuenta.
• Cada respuesta del chat cuenta como un mensaje de tu plan. Un agente responde como mucho 1.000 mensajes por hora, entre el widget y la API.
• Una respuesta del chat tiene que terminar en 55 segundos.
• Fuentes: solo textos y pares de pregunta y respuesta. Las páginas web, los archivos y las páginas de Notion se añaden en el panel.
• Hasta 25 webhooks suscritos por agente, aparte de los 5 añadidos en la pestaña Leads.
• Todavía no hay endpoints para crear o cambiar agentes, enviar formularios, reservar citas ni tomar el control de chats en vivo.

Siguientes pasos

• Recibe en tu servidor los leads y los traspasos en cuanto ocurren: Webhooks.
• Usa intoCHAT en Zapier o Make: Zapier y Make.
• Deja que tu agente llame a tu propia API mientras responde: Acciones API.
• Escribe buenos textos y pares de pregunta y respuesta: Texto y preguntas.
• Comprueba qué incluye tu plan: Planes y límites.