Quickstart

Este tutorial te lleva de cero a recibir la primera respuesta del bot en tu webhook. Elegí tu lenguaje arriba en cualquier bloque — la selección se sincroniza en toda la página.

Prerrequisitos

• Una API key sk_live_* del Canal API. La generás vos mismo desde el panel del tenant, en la pestaña Canal API (rol OWNER o MANAGER) — esta key es exclusiva del Canal API. Ver dónde obtener tu API key.
• El bot del tenant ya configurado (rol asignado y, idealmente, conocimiento cargado). Si todavía no lo configuraste, seguí el Quickstart de Partner API.
• Un endpoint HTTPS público que acepte POST para recibir los webhooks.

Configuración

Todas las llamadas usan la misma base y headers:

curl

BASE="https://api.overtaker.online/api/v1"
KEY="sk_live_xxx"
# En cada request: -H "Authorization: Bearer $KEY" -H "X-Overtaker-Version: 1"

Python

import requests

BASE = "https://api.overtaker.online/api/v1"
HEADERS = {
    "Authorization": "Bearer sk_live_xxx",
    "X-Overtaker-Version": "1",
}

Node

const BASE = "https://api.overtaker.online/api/v1";
const HEADERS = {
  Authorization: "Bearer sk_live_xxx",
  "Content-Type": "application/json",
  "X-Overtaker-Version": "1",
};

Paso 1 — Validar la API key

GET /channel/ping confirma que tu key es válida y que el plan incluye Canal API, sin consumir cuota de conversación.

curl

curl "$BASE/channel/ping" \
  -H "Authorization: Bearer $KEY" -H "X-Overtaker-Version: 1"

Python

ping = requests.get(f"{BASE}/channel/ping", headers=HEADERS).json()

Node

const ping = await fetch(`${BASE}/channel/ping`, { headers: HEADERS })
  .then((r) => r.json());

{
  "tenant_id": "uuid-del-tenant",
  "tenant_name": "Mi Empresa S.A.",
  "channel_api_enabled": true,
  "api_version": "1"
}

Paso 2 — Configurar tu webhook

El webhook se configura al crear la API key, en el mismo formulario del panel (campo webhook URL). Poné ahí la URL de tu endpoint público — ver Registrar tu webhook URL para el detalle y cómo cambiarla después.

Precaución

Guardá el webhook_secret que recibís al crear la key: solo se muestra una vez y lo necesitás para verificar la firma HMAC de cada evento.

Paso 3 — Enviar el primer mensaje

curl

curl -X POST "$BASE/channel/message" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "X-Overtaker-Version: 1" \
  -d '{ "session_id": "user-123", "message": "Hola, ¿en qué horario atienden?" }'

Python

res = requests.post(f"{BASE}/channel/message", headers=HEADERS, json={
    "session_id": "user-123",
    "message": "Hola, ¿en qué horario atienden?",
}).json()

Node

const res = await fetch(`${BASE}/channel/message`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({ session_id: "user-123", message: "Hola, ¿en qué horario atienden?" }),
}).then((r) => r.json());

Respuesta inmediata — el mensaje quedó encolado, todavía no es la respuesta del bot:

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

Paso 4 — Recibir la respuesta del bot

Segundos después, el bot procesa el mensaje y hace POST a tu webhook con el evento message.response:

{
  "event": "message.response",
  "session_id": "user-123",
  "message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "conversation_id": "conv-uuid",
  "response": {
    "text": "¡Hola! Atendemos de lunes a viernes de 9:00 a 18:00 hrs. ¿En qué más puedo ayudarte?",
    "quick_replies": ["Ver planes", "Hablar con un asesor"]
  },
  "timestamp": "2026-05-27T12:00:00Z"
}

Tu webhook debe responder HTTP 200 dentro de 10 segundos. Si no, OvertakerAI reintenta hasta 4 veces con espera creciente (10s, 30s, 2min, 10min).

¿No querés manejar webhooks?

Si preferís un flujo de request/response sincrónico (el texto te llega a medida que se genera), usá streaming SSE en lugar de webhooks.

---

¡Listo! Ya tenés el ciclo completo. Seguí con Enviar mensajes para media y streaming, o mirá los Casos de uso para patrones de integración completos.