Integración de API de Chatbot
Integre WebChatAgent en apps de escritorio, terminales y herramientas internas mediante REST API y use WebSocket para live chat real.
Lleve el chat a su app, no solo a su web.
No todo es un navegador. Con nuestra API puede crear experiencias conversacionales dentro de su software: clientes desktop, CLI y portales internos.
¿Qué problemas resuelve la API de Chatbot?
Bloqueos típicos de integración y cómo una API los resuelve de forma limpia.
Un widget web no encaja
Apps de escritorio, herramientas internas o terminales necesitan una integración nativa, no un widget web embebido.
Experiencias de chat inconsistentes
Sin una API clara, el chat se vuelve un caso especial. Con endpoints dedicados mantiene el UX consistente en sus flujos y componentes.
Live chat requiere tiempo real
Cuando un humano toma el control, importa el tiempo real: estado, mensajes y archivos deben llegar al instante. Para eso es WebSocket.
¿Cómo lo resuelve la API?
Empiece con REST para bot chat y cambie sin fricción a WebSocket para human takeover.
REST API para cualquier frontend
Envíe mensajes por POST a /api/chat y muestre la respuesta en su UI. Ideal para desktop, móvil, backoffice y CLI.
WebSocket para Live Chat (human takeover)
Cuando el modo cambia a human, conéctese por WebSocket y envíe/reciba mensajes en tiempo real, incluyendo session guards.
Ejemplos de código
Arranque en minutos: cURL para pruebas rápidas y JavaScript para integraciones productivas.
# 1) First request (no session id). Use -i to see response headers.
curl -i -X POST https://webchatagent.com/api/chat \
-H "Content-Type: application/json" \
-d '{
"message": "Hello, how can you help me?",
"chatbotId": "<your-chatbot-id>"
}'
# 2) Reuse the X-Chat-Session-Id from the response header for the conversation.
curl -X POST https://webchatagent.com/api/chat \
-H "Content-Type: application/json" \
-H "X-Chat-Session-Id: <session-id-from-response>" \
-d '{
"message": "Continue the conversation.",
"chatbotId": "<your-chatbot-id>"
}'async function sendChatMessage({ baseUrl, chatbotId, message, sessionId }) {
const res = await fetch(`${baseUrl}/api/chat`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Chat-Session-Id': sessionId || ''
},
body: JSON.stringify({ message, chatbotId })
});
const nextSessionId = res.headers.get('X-Chat-Session-Id') || sessionId || '';
if (!res.ok) throw new Error(await res.text());
const data = await res.json();
// data: { reply, sources, mode, status }
// If mode === 'human' and status === 'waiting' or 'open', switch to WebSocket
if (data.mode === 'human' && (data.status === 'waiting' || data.status === 'open')) {
// Switch to WebSocket for live chat
connectToLiveChat(nextSessionId, chatbotId);
}
return { data, sessionId: nextSessionId };
}Gestión de sesión: si no envía X-Chat-Session-Id, el servidor crea una nueva sesión y devuelve la session id en el header de respuesta. Guárdela y envíela en las siguientes peticiones.
Ejemplo de respuesta al cambiar a live chat: [ "reply": "...", "sources": [], "mode": "human", "status": "waiting" ] — luego cambie a WebSocket.
Qué tener en cuenta en Live Chat
Live Chat funciona con WebSocket. Tras conectar, haga join con chatbotId + sessionId y envíe mensajes como client:message. Procese solo eventos de su sesión actual.
// Use the same base URL as your REST calls (WebChatAgent domain).
const ws = new WebSocket('wss://webchatagent.com/api/livechat');
ws.onopen = () => {
ws.send(JSON.stringify({
type: 'client:join',
chatbotId: '<your-chatbot-id>',
sessionId: '<your-session-id>',
as: 'user'
}));
};
function sendLiveChatMessage(text) {
ws.send(JSON.stringify({
type: 'client:message',
chatbotId: '<your-chatbot-id>',
sessionId: '<your-session-id>',
sender: 'user',
content: text
}));
}
ws.onmessage = (event) => {
const data = JSON.parse(event.data || '{}');
// data.type === 'livechat:message'
// data.sessionId guard recommended (handle only current session)
};Use REST (/api/chat) mientras la conversación esté en modo bot.
Compruebe la respuesta: Si mode='human' y status='waiting' o 'open' se devuelve, cambie a WebSocket (/api/livechat).
Aplique un session guard: ignore eventos sin sessionId o con otra sessionId.
Casos de uso típicos
Ejemplos de cómo los equipos integran soporte y flujos directamente en su software.
Soporte en app de escritorio
Ayuda, troubleshooting y onboarding dentro de la app, sin cambiar al navegador.
Asistente en terminal / CLI
Respuestas e instrucciones en el terminal, ideal para DevOps, TI y tooling interno.
Portales internos y backoffice
Autoservicio para empleados: políticas, procesos y conocimiento dentro del intranet.
Escalación a live chat
Automatice con bot y entregue a un humano cuando sea necesario (WebSocket).
Integre chat donde ya están sus usuarios.
Empiece con REST y añada live chat cuando lo necesite. Pensado para integraciones en producción: rápido, estable y fácil de mantener.
Crear cuenta