Ir al contenido

Enviar mensajes

El endpoint principal del Canal API es POST /channel/message. Devuelve un 200 inmediato confirmando que el mensaje se encoló; la respuesta del bot llega después por webhook o por el stream SSE.

POST https://api.overtaker.online/api/v1/channel/message
Authorization: Bearer sk_live_YOUR_KEY
Content-Type: application/json
X-Overtaker-Version: 1
Idempotency-Key: msg-001 # opcional — recomendado, evita duplicados (TTL 24h)
{
"session_id": "user-123", // recomendado — identidad opaca de la sesión (≤200 chars)
"email": "cliente@empresa.com", // opcional — solo si lo conoces (se usa para el Lead)
"contact_name": "Café Aroma", // opcional — nombre legible del contacto (≤120 chars)
"message": "Hola, necesito ayuda", // requerido — texto (máx. 5000 chars). OPCIONAL en audio (se transcribe)
"message_type": "text", // opcional — ver tabla abajo (default: "text")
"media_base64": "<base64>", // opcional — archivo en base64
"media_mime_type": "image/jpeg", // obligatorio si hay media_base64
"geo_lat": -33.4489, // opcional — latitud (número)
"geo_lng": -70.6693 // opcional — longitud (número)
}

Los dos campos de geolocalización son opcionales y retrocompatibles. Sirven para casos de survey / mystery shopper: verifican la presencia del usuario en el punto (sucursal, local) y sellan la procedencia de las fotos adjuntas (watermark). Aplican igual en POST /channel/message y en POST /channel/message/stream.

Respuesta:

{
"message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "received"
}

session_id es el identificador opaco de la sesión. El bot lo usa para reconocer al usuario y mantener contexto entre mensajes. Puede ser cualquier string de hasta 200 caracteres (UUID, ID interno, teléfono, lo que sea).

Qué envíasComportamiento
Solo session_idSesión anónima válida — el bot opera sin email del usuario.
Solo emailCompat histórica — el session_id se deriva del email.
Ambossession_id manda como identidad de sesión; email se preserva para identificar/crear el Lead.
// Mismo session_id = misma sesión, el bot recuerda el contexto
{"session_id": "user-123", "message": "Hola"}
{"session_id": "user-123", "message": "¿Qué me dijiste antes?"} // ✓ recuerda
// session_id distinto = sesión nueva, sin contexto previo
{"session_id": "user-456", "message": "Hola"} // conversación independiente

contact_name es opcional y le da al contacto un nombre legible en el panel (de lo contrario aparece como api:<session_id>, ilegible y no-buscable). Útil cuando ya conoces el nombre del cliente/empresa al iniciar la sesión.

AspectoComportamiento
Cuándo aplicaAl crear el contacto, y en mensajes posteriores mientras aún no tenga nombre.
Si ya tiene nombreNo se pisa — un nombre ya capturado (por ti o por el agente) tiene prioridad.
Ausente / vacíoNo-op, flujo idéntico al actual.
LargoSe recorta a 120 caracteres.
{ "session_id": "proyecto-42", "message": "Hola", "contact_name": "Café Aroma" }
// → el contacto queda como "Café Aroma" en el panel y en el evento contact.updated

Si necesitas capturar más datos del contacto durante la conversación (no solo el nombre), eso lo hace el agente vía protocolo — ver Completar datos estructurados.

message_typeFormatos soportadosmedia_mime_type (ejemplos)
textTexto plano (default)— (no lleva media)
imageJPEG, PNG, WebP, GIFimage/jpeg, image/png, image/webp, image/gif
videoMP4, 3GPPvideo/mp4
audioMP3, OGG, MP4 audio, WebMaudio/mpeg, audio/ogg, audio/mp4, audio/webm
documentPDF, Word, Excel, PowerPoint, TXTapplication/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document (.docx)

Para mensajes con media, codifica el archivo en base64 y declara su media_mime_type:

# Python
import base64, requests
with open("imagen.jpg", "rb") as f:
b64 = base64.b64encode(f.read()).decode()
requests.post(f"{BASE}/channel/message", headers=HEADERS, json={
"session_id": "user-123",
"message": "Mira esta imagen",
"message_type": "image",
"media_base64": b64,
"media_mime_type": "image/jpeg",
})
Node.js
const fs = require("fs");
const b64 = fs.readFileSync("./imagen.jpg").toString("base64");
await fetch(`${BASE}/channel/message`, {
method: "POST",
headers: HEADERS,
body: JSON.stringify({
session_id: "user-123",
message: "Mira esta imagen",
message_type: "image",
media_base64: b64,
media_mime_type: "image/jpeg",
}),
});

Si tu request falla por timeout o red, puedes reintentarlo con la misma clave de idempotencia y el mensaje no se procesa dos veces. Usa el header HTTP estándar Idempotency-Key (estilo Stripe / PayPal):

POST https://api.overtaker.online/api/v1/channel/message
Authorization: Bearer sk_live_YOUR_KEY
Content-Type: application/json
X-Overtaker-Version: 1
Idempotency-Key: mi-sistema-msg-id-20260527-001
{ "session_id": "user-123", "message": "Quiero cotizar" }
// Reintento con la misma key dentro de 24h → mismo message_id, sin reprocesar.
  • TTL: 24 horas.
  • Máximo: 200 caracteres (si supera → 400).

El bot puede decidir no responder. En ese caso no llega ningún evento message.response a tu webhook. Ocurre cuando el bot detecta un mensaje fuera de contexto, spam, o está en modo handoff activo.

Si tu integración reenvía cada línea que escribe el usuario como un mensaje separado, el bot respondería a cada una. Con la opción Agrupar de la API key (interruptor en el panel → Canal API), los mensajes que llegan seguidos de una misma sesión se juntan y el bot responde una sola vez, pocos segundos después.

Con la agrupación activa:

  • Llega un solo message.response, con el message_id del último mensaje del grupo. Los message_id anteriores no reciben webhook: no esperes una respuesta por cada envío.
  • No se aplica a los mensajes con archivos ni a POST /channel/message/stream.

POST /channel/message/stream es la variante streaming. Mismo body que /channel/message (con una diferencia: aquí no hay idempotencia, ver la nota de abajo), pero la respuesta llega como Server-Sent Events — pensado para chats con efecto “typing” donde muestras el texto a medida que se genera. Bucket write (60/min).

POST https://api.overtaker.online/api/v1/channel/message/stream
Authorization: Bearer sk_live_YOUR_KEY
Content-Type: application/json
X-Overtaker-Version: 1
Accept: text/event-stream
{ "session_id": "user-123", "message": "Cuéntame de sus planes" }

Response (text/event-stream):

event: token
data: {"text": "Tenemos tres "}
event: token
data: {"text": "planes principales: "}
event: token
data: {"text": "Starter, Pro y Enterprise..."}
event: done
data: {
"message_id": "uuid",
"conversation_id": "uuid",
"lead_id": "uuid o vacío",
"session_id": "user-123",
"full_text": "Tenemos tres planes principales: Starter, Pro y Enterprise...",
"quick_replies": ["Ver Starter", "Ver Pro"],
"voice_url": null,
"action": "REPLY",
"silenced": false
}
// En caso de error
event: error
data: {"detail": "Error interno procesando el mensaje", "trace_id": "…"}
  • voice_url: audio de la respuesta si el tenant tiene la voz activada (URL temporal); null si no.
  • silenced: true cuando el bot no responde a propósito y no hay texto que mostrar (la conversación la tomó una persona). No dibujes una burbuja vacía.
  • trace_id: inclúyelo si nos escribes por un error.
// Node.js — consumir el stream con fetch + ReadableStream
const res = await fetch(`${BASE}/channel/message/stream`, {
method: "POST",
headers: { ...HEADERS, Accept: "text/event-stream" },
body: JSON.stringify({ session_id: "user-123", message: "Hola" }),
});
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
while (true) {
const { value, done } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
const blocks = buffer.split("\n\n"); // \n\n delimita un evento SSE
buffer = blocks.pop() || ""; // resto incompleto
for (const block of blocks) {
const event = block.match(/^event:\s*(.+)$/m)?.[1];
const data = block.match(/^data:\s*(.+)$/m)?.[1];
if (!event || !data) continue;
const payload = JSON.parse(data);
if (event === "token") process.stdout.write(payload.text);
if (event === "done") console.log("\n[FIN]", payload.message_id);
if (event === "error") console.error("[ERROR]", payload.detail);
}
}

POST /channel/outbound — empujar un saliente controlado

Sección titulada «POST /channel/outbound — empujar un saliente controlado»

POST /channel/outbound empuja un mensaje saliente a una sesión. Si la sesión todavía no tiene conversación, se crea. A diferencia de POST /channel/message —que inyecta un inbound y deja que el bot genere la respuesta—, aquí el texto de salida lo controla tu integración: el mensaje se persiste tal cual lo mandaste y no dispara una respuesta del bot. Úsalo para empujar avisos, seguimientos o mensajes proactivos disparados por tu propio sistema.

El saliente queda registrado en la conversación (se lee después por el historial) y, si tu key está suscrita, se confirma con el webhook outbound.sent. Ese evento es opt-in: sin suscripción no llega.

POST https://api.overtaker.online/api/v1/channel/outbound
Authorization: Bearer sk_live_YOUR_KEY
Content-Type: application/json
X-Overtaker-Version: 1
Idempotency-Key: out-001 # opcional — evita duplicados en reintentos
{
"session_id": "user-123", // requerido — sesión destino (≤200 chars)
"message": "Tu pedido ya salió 🚚", // requerido — texto (máx. 5000 chars)
"message_type": "text", // opcional — default "text"
"image_url": "https://.../foto.jpg" // opcional — URL de imagen a adjuntar
}

Respuesta (ChannelApiOutboundResponse):

{
"status": "sent",
"message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"conversation_id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890"
}

El campo status indica el resultado del empuje:

statusSignificado
sentSaliente registrado en la conversación (fuente de verdad en el historial).
opted_outEl contacto se dio de baja — no se envía.

message_id y conversation_id vienen null cuando el saliente no se registró (opted_out).

Rate limit: bucket write (60/min).