ChatBot Platform

Referencia de la API REST

Envía mensajes de WhatsApp y gestiona llamadas con claves API.

Introducción

La API REST acepta y devuelve JSON. CORS está habilitado para integraciones desde el navegador. Todas las rutas documentadas requieren el header X-API-Key.

URL base

https://api.integracionessh.lat

Autenticación

Incluye tu clave API en cada solicitud. Las claves se asocian a un bot y heredan sus permisos (scopes).

Header requerido

X-API-Key: YOUR_API_KEY

Para crear una clave API, inicia sesión y ve a Developer API. Iniciar sesión

Scopes

Cada clave API incluye uno o más scopes. Si falta un scope, la API responde 403.

ScopeEndpoints
messages:sendPOST /v1/messages
calls:initiatePOST /v1/calls · POST /v1/calls/permission-request · GET /v1/calls/permission/{userWaId}
calls:managePOST /v1/calls/{callId} · GET /v1/calls/{callId}
calls:settingsGET /v1/calls/settings · PUT /v1/calls/settings

Límites de tasa

Las respuestas incluyen headers de rate limit. Si superas el límite, recibirás 429 con Retry-After.

Headers de respuesta

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1718640060

Errores

Los errores devuelven un objeto JSON con el campo error.

CódigoSignificado
400Solicitud inválida (validación Zod)
401Clave API ausente o inválida
403Clave deshabilitada, expirada o sin scope
404Recurso no encontrado
429Límite de tasa excedido
502Error al comunicarse con WhatsApp

Ejemplo

{ "error": "Invalid request body" }

Endpoints

Referencia de las rutas públicas /v1/*. El número to debe contener solo dígitos (código de país + número).

POST/v1/messagesmessages:send

Envía un mensaje de texto de WhatsApp al número indicado.

Usa type text o type template. Para templates, name y language deben coincidir con un template aprobado.

Cuerpo de la solicitud

{"to":"521234567890","type":"text","text":"Hello!"}

Respuesta

{
  "messageId": "wamid.xxx",
  "status": "sent",
  "timestamp": "2026-06-17T12:00:00.000Z"
}

Ejemplo curl

curl -X POST \
  https://api.integracionessh.lat/v1/messages \
  -H "X-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json" \
  -d '{"to":"521234567890","type":"text","text":"Hello!"}'
POST/v1/messagesmessages:send

Envía un template de WhatsApp aprobado por Meta.

Cuerpo de la solicitud

{
  "to": "521234567890",
  "type": "template",
  "template": {
    "name": "hello_world",
    "language": "en_US"
  }
}

Respuesta

{
  "messageId": "wamid.xxx",
  "status": "sent",
  "timestamp": "2026-06-17T12:00:00.000Z"
}

Ejemplo curl

curl -X POST \
  https://api.integracionessh.lat/v1/messages \
  -H "X-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json" \
  -d '{"to": "521234567890","type": "template","template": {"name": "hello_world","language": "en_US"}}'
POST/v1/callscalls:initiate

Inicia una llamada saliente de WhatsApp (WebRTC). session.sdp_type debe ser offer.

Requiere permiso de llamada del usuario. Usa permission-request y getCallPermission antes de llamar.

Cuerpo de la solicitud

{
  "to": "521234567890",
  "session": {
    "sdp_type": "offer",
    "sdp": "v=0..."
  }
}

Respuesta

{
  "callId": "call_xxx",
  "status": "initiated",
  "timestamp": "2026-06-17T12:00:00.000Z"
}

Ejemplo curl

curl -X POST \
  https://api.integracionessh.lat/v1/calls \
  -H "X-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json" \
  -d '{"to": "521234567890","session": {"sdp_type": "offer","sdp": "v=0..."}}'
POST/v1/calls/{callId}calls:manage

Ejecuta una acción sobre una llamada activa: pre_accept, accept, reject o terminate.

Las acciones pre_accept y accept requieren session con sdp_type answer u offer según el flujo WebRTC.

Cuerpo de la solicitud

{
  "action": "accept",
  "session": {
    "sdp_type": "answer",
    "sdp": "v=0..."
  }
}

Respuesta

{
  "callId": "call_xxx",
  "action": "accept",
  "success": true
}

Ejemplo curl

curl -X POST \
  https://api.integracionessh.lat/v1/calls/call_xxx \
  -H "X-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json" \
  -d '{"action": "accept","session": {"sdp_type": "answer","sdp": "v=0..."}}'
GET/v1/calls/{callId}calls:manage

Obtiene el estado de una llamada por callId.

Respuesta

{
  "callId": "call_xxx",
  "tenantId": "tenant_xxx",
  "botId": "bot_xxx",
  "phoneNumber": "521234567890",
  "direction": "BUSINESS_INITIATED",
  "status": "initiated",
  "startedAt": "2026-06-17T12:00:00.000Z",
  "createdAt": "2026-06-17T12:00:00.000Z",
  "updatedAt": "2026-06-17T12:00:00.000Z"
}

Ejemplo curl

curl -X GET \
  https://api.integracionessh.lat/v1/calls/call_xxx \
  -H "X-API-Key: YOUR_API_KEY"
GET/v1/calls/settingscalls:settings

Lee la configuración de llamadas del número de WhatsApp del bot.

Respuesta

{
  "calling": {
    "status": "ENABLED"
  }
}

Ejemplo curl

curl -X GET \
  https://api.integracionessh.lat/v1/calls/settings \
  -H "X-API-Key: YOUR_API_KEY"
PUT/v1/calls/settingscalls:settings

Actualiza la configuración de llamadas del número de WhatsApp del bot.

Cuerpo de la solicitud

{
  "calling": {
    "status": "ENABLED"
  }
}

Respuesta

{
  "calling": {
    "status": "ENABLED"
  }
}

Ejemplo curl

curl -X PUT \
  https://api.integracionessh.lat/v1/calls/settings \
  -H "X-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json" \
  -d '{"calling": {"status": "ENABLED"}}'
POST/v1/calls/permission-requestcalls:initiate

Envía un mensaje solicitando permiso de llamada al usuario.

Cuerpo de la solicitud

{"to":"521234567890","bodyText":"Can we call you?"}

Respuesta

{
  "messageId": "wamid.xxx",
  "status": "sent"
}

Ejemplo curl

curl -X POST \
  https://api.integracionessh.lat/v1/calls/permission-request \
  -H "X-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json" \
  -d '{"to":"521234567890","bodyText":"Can we call you?"}'
GET/v1/calls/permission/{userWaId}calls:initiate

Consulta si un usuario ha concedido permiso de llamada.

Respuesta

{
  "permission": {
    "status": "granted",
    "expiration_time": 1718640000
  }
}

Ejemplo curl

curl -X GET \
  https://api.integracionessh.lat/v1/calls/permission/521234567890 \
  -H "X-API-Key: YOUR_API_KEY"