Integración de la API de chatbot: REST, Zapier y webhooks explicados

Una API de chatbot es una interfaz HTTP que te permite enviar mensajes a un chatbot de IA y recibir respuestas de forma programática, sin usar un widget visual. En lugar de que un usuario escriba en una burbuja de chat, tu código envía una solicitud, recibe una respuesta y hace algo con ella: renderiza una interfaz personalizada, registra la respuesta, dispara una acción o enruta el resultado a otro sistema.

Esta guía cubre qué es una API de chatbot, cuándo usar una en lugar de un widget incrustado, los tres métodos de conexión principales (REST, Zapier y webhooks) y patrones prácticos para construir integraciones reales.

¿Qué es una API de chatbot?

Una API de chatbot expone tu chatbot de IA entrenado como un servicio que cualquier código puede llamar por HTTP. Envías el mensaje de un usuario en el cuerpo de la solicitud, y la API devuelve la respuesta del chatbot, extraída de las fuentes que hayas usado para entrenarlo (contenido del sitio web, documentos, pares de preguntas y respuestas).

La distinción clave frente a un widget prediseñado: la API devuelve datos en bruto. Tu aplicación decide cómo presentarlos. Eso significa que puedes incrustar el mismo chatbot en una app móvil, un bot de Slack, un panel interno y un pipeline de automatización de backend, todo usando la misma base de conocimiento entrenada.

La mayoría de las API de chatbot siguen un patrón similar:

1. Autentícate: incluye una clave de API en el encabezado Authorization.
2. Envía un mensaje por POST: envía el texto del usuario, un ID de chatbot y, opcionalmente, un ID de conversación para dar contexto en interacciones de varios turnos.
3. Maneja la respuesta: procesa la respuesta, opcionalmente transmite los tokens en tiempo real para una sensación fluida, y guarda el conversationId para el siguiente turno.

Para equipos que están comparando opciones de chatbot antes de comprometerse con una plataforma, esta visión general de los mejores chatbots de IA para sitios web cubre qué buscar entre las distintas herramientas.

Cuándo usar la API vs. el widget

El widget incrustado maneja la mayoría de los casos de uso de sitios web. La API es la opción correcta cuando necesitas algo que el widget no puede ofrecer.

Si tu caso de uso cae en la columna derecha, la API es la herramienta correcta. Para conocer todas las opciones de incrustación (widget, componente de React, iframe y plugin de WordPress), consulta la guía de integración de chatbot.

Métodos de conexión y disponibilidad por plan

Hay tres formas de conectar tu chatbot con sistemas externos. Cumplen propósitos distintos y están disponibles en distintos planes.

La API REST te da el mayor control. Zapier es más rápido de configurar si no necesitas código personalizado. Los webhooks complementan a ambos: te envían datos en lugar de que tengas que ir a buscarlos.

Para un desglose completo de lo que incluye cada plan, consulta la guía de costos y precios de chatbots.

Requisitos por plan

La facturación anual reduce el precio de cada plan en aproximadamente un 20%. Los mensajes de la API se descuentan de tu cuota mensual igual que los mensajes del widget.

Autenticación

Toda solicitud a la API requiere un token Bearer. Generas las claves de API desde la configuración del espacio de trabajo en tu panel de Agentkit.

Generar una clave de API

1. Abre tu espacio de trabajo de Agentkit.
2. Ve a Configuración y luego a Claves de API.
3. Haz clic en Crear clave de API.
4. Dale un nombre descriptivo (por ejemplo, "Bot de Slack (producción)").
5. Copia la clave de inmediato. No se volverá a mostrar.

Usar la clave en las solicitudes

Incluye tu clave de API en el encabezado Authorization:

Authorization: Bearer ak_live_your_api_key_here

Todas las solicitudes deben enviarse por HTTPS. Las solicitudes sin un token válido devuelven una respuesta 401 Unauthorized.

Buenas prácticas de gestión de claves

• Guarda las claves de API en variables de entorno, nunca en código del lado del cliente.
• Rota las claves periódicamente, especialmente después de cambios en el equipo.
• Crea claves separadas para integraciones separadas, así puedes revocar una sin afectar a las demás.
• Elimina las claves que ya no uses.

Para todos los detalles de autenticación, consulta la documentación de autenticación.

El endpoint de chat

El núcleo de la API es un único endpoint que envía el mensaje de un usuario a tu chatbot y devuelve la respuesta de la IA.

Solicitud

POST /api/v1/chat
Content-Type: application/json
Authorization: Bearer ak_live_your_api_key_here

Cuerpo de la solicitud:

{
  "chatbotId": "your-chatbot-id",
  "message": "What are your shipping options?",
  "conversationId": "optional-conversation-id",
  "visitorId": "optional-visitor-id",
  "metadata": {
    "page": "/products/shoes",
    "userTier": "premium"
  }
}

Respuesta

{
  "id": "msg_abc123",
  "conversationId": "conv_xyz789",
  "message": "We offer three shipping options: Standard (5-7 business days, free over $50), Express (2-3 business days, $9.99), and Overnight ($24.99). All orders include tracking.",
  "sources": [
    {
      "title": "Shipping Policy",
      "url": "https://example.com/shipping"
    }
  ],
  "createdAt": "2026-02-22T14:30:00Z"
}

El conversationId de la respuesta es importante. Guárdalo y pásalo de vuelta en las siguientes solicitudes para mantener el contexto de la conversación. Sin él, cada mensaje empieza una conversación nueva y el chatbot pierde el hilo.

Respuestas de error

Para la referencia completa del endpoint, consulta la documentación de la API.

Respuestas en streaming

Para aplicaciones en tiempo real donde quieres mostrar la respuesta a medida que se genera (el efecto de máquina de escribir que los usuarios esperan del chat con IA), usa Server-Sent Events (SSE).

Agrega el parámetro stream: true a tu solicitud:

{
  "chatbotId": "your-chatbot-id",
  "message": "Explain your return policy",
  "conversationId": "conv_xyz789",
  "stream": true
}

La respuesta llega como un stream de eventos SSE:

data: {"type": "token", "content": "Our"}
data: {"type": "token", "content": " return"}
data: {"type": "token", "content": " policy"}
data: {"type": "token", "content": " allows"}
...
data: {"type": "sources", "sources": [{"title": "Return Policy", "url": "https://example.com/returns"}]}
data: {"type": "done", "conversationId": "conv_xyz789", "messageId": "msg_def456"}

Manejar el stream en JavaScript

const response = await fetch('https://api.agentkit.com/api/v1/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ak_live_your_api_key_here'
  },
  body: JSON.stringify({
    chatbotId: 'your-chatbot-id',
    message: 'Explain your return policy',
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n').filter(line => line.startsWith('data: '));

  for (const line of lines) {
    const data = JSON.parse(line.slice(6));
    if (data.type === 'token') {
      appendToUI(data.content);
    }
  }
}

El streaming se recomienda para cualquier integración de cara al usuario. Hace que el chatbot se sienta más ágil incluso cuando genera respuestas largas.

Webhooks

Mientras que el endpoint de chat te permite enviar mensajes al chatbot, los webhooks dejan que el chatbot te envíe datos a ti. Cuando ocurren eventos específicos, Agentkit envía una solicitud HTTP POST a una URL que tú configuras. Los webhooks están disponibles desde el plan Hobby en adelante.

Configurar webhooks

1. Ve a Configuración de tu espacio de trabajo y luego a Webhooks.
2. Ingresa la URL de tu endpoint (debe ser HTTPS).
3. Selecciona a qué eventos quieres suscribirte.
4. Guarda. Agentkit envía una solicitud de verificación para confirmar que tu endpoint es accesible.

Eventos disponibles

Payload del webhook

Cada POST de webhook incluye un cuerpo JSON con una estructura consistente:

{
  "event": "lead.captured",
  "timestamp": "2026-02-22T15:45:00Z",
  "chatbotId": "your-chatbot-id",
  "conversationId": "conv_xyz789",
  "data": {
    "name": "Alex Chen",
    "email": "[email protected]",
    "message": "Interested in the enterprise plan"
  },
  "signature": "sha256=abc123..."
}

Verifica siempre el campo signature contra tu secreto de webhook para confirmar que la solicitud viene de Agentkit y no de un tercero.

Comportamiento de reintentos

Si tu endpoint devuelve un código de estado que no es 2xx, Agentkit reintenta con backoff exponencial: después de 1 minuto, 5 minutos, 30 minutos, y luego se detiene. Las entregas fallidas son visibles en los registros de webhooks de tu panel.

Patrones de integración comunes

Patrón 1: bot de Slack

Envía las preguntas de clientes de tu chatbot del sitio web a un canal de Slack, y deja que tu equipo responda cuando la IA no pueda hacerlo.

1. Crea una app de Slack con webhooks entrantes habilitados.
2. Configura un webhook de Agentkit para eventos conversation.completed.
3. En tu manejador de webhook, revisa si la conversación se resolvió o se escaló.
4. Si se escaló, envía por POST un mensaje con formato a la URL de tu webhook de Slack con la transcripción de la conversación.

Esto le da visibilidad a tu equipo de soporte sin necesidad de que monitoreen el panel de Agentkit.

Patrón 2: interfaz de chat personalizada

Reemplaza el widget predeterminado con una experiencia de chat construida dentro de tu aplicación.

1. Construye tu interfaz de chat con el framework que prefieras.
2. Al enviar un mensaje, llama al endpoint de chat con stream: true.
3. Renderiza los tokens a medida que llegan para dar retroalimentación en tiempo real.
4. Guarda el conversationId en el estado local para mantener el contexto entre mensajes.

Este es el enfoque correcto para apps móviles, aplicaciones de escritorio o cualquier producto donde el widget flotante no encaje con el diseño. Para equipos que quieren quedarse con el widget pero necesitan más control sobre su ubicación, la guía para incrustar un chatbot en tu sitio web cubre las cuatro opciones de incrustación.

Patrón 3: automatización de backend

Usa el chatbot como una capa de IA dentro de un flujo de trabajo más grande, sin ninguna interfaz de chat de por medio.

Ejemplo: procesamiento de tickets de soporte.

1. Llega un ticket nuevo a tu sistema de tickets.
2. Tu backend envía el contenido del ticket al endpoint de chat.
3. El chatbot genera una respuesta sugerida basada en tu base de conocimiento entrenada.
4. Tu sistema responde automáticamente (si la confianza es alta) o pone la sugerencia en cola para revisión humana.

Este patrón funciona porque el chatbot está entrenado con la misma base de conocimiento que usa tu equipo de soporte. La API te da acceso programático a esa inteligencia. Para más información sobre con qué puedes entrenar un chatbot (rastreo de sitio web, archivos PDF y CSV, pares de preguntas y respuestas), consulta cómo entrenar un chatbot.

Patrón 4: pipeline de analíticas

Captura cada conversación para su análisis.

1. Suscríbete a los eventos de webhook message.received y message.sent.
2. Tu manejador de webhook escribe los eventos en tu almacén de datos (BigQuery, Snowflake, etc.).
3. Construye paneles que muestren preguntas frecuentes, tasas de resolución, horas pico y tendencias de conversación.

El campo de metadatos en el endpoint de chat te permite adjuntar contexto (URL de la página, segmento de usuario, variante de prueba A/B) que enriquece tus analíticas.

Límite de frecuencia

La API aplica límites de frecuencia para garantizar confiabilidad a todos los usuarios.

Cuando alcanzas el límite, la API devuelve un código de estado 429 con un encabezado Retry-After que indica cuántos segundos esperar. Incorpora lógica de reintento en tu integración:

async function sendMessage(payload, retries = 3) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(payload)
  });

  if (response.status === 429 && retries > 0) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '5');
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return sendMessage(payload, retries - 1);
  }

  return response.json();
}

Consideraciones de seguridad

Al construir integraciones con la API, ten en cuenta estas prácticas:

• Nunca expongas claves de API en código del lado del cliente. Si estás construyendo una interfaz de chat personalizada para una app web, redirige las solicitudes a través de tu propio backend.
• Valida las firmas de los webhooks. Verifica siempre la firma HMAC antes de procesar los payloads de webhooks.
• Usa restricciones de dominio. En la configuración de tu chatbot, restringe qué dominios pueden interactuar con tu chatbot.
• Monitorea el uso. Revisa el uso de tu API en el panel con regularidad para detectar picos inesperados que puedan indicar una clave filtrada.
• Usa el principio de menor privilegio. Si una integración solo necesita enviar mensajes, no le des una clave con permisos de administrador.

Para equipos que quieren explorar cómo las API de chatbot con IA se conectan a ecosistemas de herramientas más amplios, vale la pena entender MCP (Model Context Protocol): es un estándar emergente para darles a los modelos de IA acceso estructurado a herramientas y datos externos.

Cómo empezar

El camino más rápido de cero a una integración funcionando:

1. Regístrate en una cuenta de Agentkit y crea tu primer chatbot.
2. Entrena el chatbot con tu contenido (consulta cómo entrenar un chatbot).
3. Mejora tu plan a Hobby ($29.99/mes) para habilitar el acceso a la API.
4. Genera una clave de API en la configuración de tu espacio de trabajo.
5. Envía tu primera solicitud de prueba usando cURL o Postman.
6. Construye a partir de ahí: interfaz personalizada, bot de Slack, automatización o lo que necesite tu caso de uso.

Preguntas frecuentes

¿Qué es una clave de API de chatbot?

Una clave de API de chatbot es un token secreto que autentica tu aplicación cuando hace solicitudes a la API del chatbot. La generas en la configuración de tu espacio de trabajo, la incluyes en el encabezado Authorization: Bearer de cada solicitud, y la tratas como una contraseña: la guardas en variables de entorno, nunca en código del lado del cliente, y la rotas si sospechas que quedó expuesta. Cada clave puede limitarse a una integración específica, así puedes revocar una sin afectar a las demás.

¿Existe una API de chatbot gratis?

El plan Free de Agentkit ($0/mes) no incluye acceso a la API REST; eso requiere el plan Hobby, a $29.99/mes. El plan Free sí incluye el widget de JS incrustable, la captura de leads y las restricciones de dominio, que cubren la mayoría de los casos de uso de sitios web sin necesidad de código. Si necesitas acceso programático desde el primer día, el plan Hobby es el punto de entrada, y puedes probar la plataforma completa gratis antes de mejorar tu plan.

¿Necesito programar para usar una API de chatbot?

No siempre. Si necesitas acceso a la API REST para integraciones personalizadas, vas a tener que escribir código, o usar una herramienta como Postman para probar las llamadas manualmente. Pero si tu objetivo es conectar el chatbot con otras apps sin código, la integración con Zapier (disponible en el plan Hobby y superiores) se conecta con más de 7000 apps mediante una interfaz sin código. Para la incrustación en sitios web, no se necesita más código que pegar una etiqueta <script>.

¿Qué modelos de IA admite la API de chatbot?

El modelo de IA subyacente se configura por chatbot desde el panel. Agentkit admite modelos de tres proveedores: OpenAI (GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna), Anthropic (Claude Opus 5, Claude Sonnet 5, Claude Haiku 4.5) y Google (Gemini 3.7 Flash, Gemini 3.1 Pro). El predeterminado es GPT-5.6 Luna. Tus llamadas a la API usan el modelo que esté seleccionado para ese chatbot; no especificas el modelo a nivel de la llamada a la API.

¿Puedo usar la API de chatbot para incrustar el chat en mi sitio web?

Sí, pero la incrustación con el widget de JS suele ser más simple para casos de uso de sitios web. El widget se carga de forma asíncrona mediante una sola etiqueta <script> y maneja la interfaz, el estado de la conversación y el streaming automáticamente. Usa la API cuando necesites una interfaz totalmente personalizada, integración en app móvil o automatización de backend. Para una comparación lado a lado de todas las opciones de incrustación, consulta la guía para incrustar un chatbot en tu sitio web.

Una API de chatbot convierte una base de conocimiento entrenada en un servicio invocable: las mismas respuestas de IA que aparecen en el widget están disponibles para cualquier sistema que pueda hacer una solicitud HTTP. Ya sea que estés construyendo una interfaz personalizada, automatizando un flujo de soporte o conectando tu chatbot a un ecosistema de herramientas más amplio, la API te da el control que un widget prediseñado no puede ofrecer.

Crea tu chatbot gratis → No se necesita tarjeta de crédito.