API de XBASE: visión general
Qué hace la API de XBASE, la dirección base, cómo autenticarse y la lista de endpoints de WhatsApp, Instagram, webhooks y agentes externos.
Actualizado el
La API de XBASE permite que otro sistema use tu workspace: enviar plantillas y mensajes de WhatsApp, responder comentarios y DM de Instagram, recibir eventos por webhook y revisar las respuestas de un agente externo.
Cada llamada usa una clave de API del workspace, solo con los permisos que elijas.
Dirección base
Todas las rutas están en:
https://api.xbase.app/api/external/v1El cuerpo de las solicitudes y de las respuestas es JSON (Content-Type: application/json). Las fechas vienen en ISO 8601, en UTC.
Autenticación
Envía la clave en el encabezado Authorization de cada solicitud:
Authorization: Bearer xsk_...La clave empieza con xsk_, solo vale en el workspace en el que se creó y solo para los alcances marcados en ella. Mira cómo crearla en Autenticación.
Endpoints
| Método y ruta | Alcance | Qué hace |
|---|---|---|
GET /me | cualquiera | Workspace y alcances de la clave |
GET /whatsapp/numbers | whatsapp:send | Números de WhatsApp del workspace |
GET /whatsapp/templates | whatsapp:send | Plantillas de cada número |
POST /whatsapp/templates | whatsapp:send | Envía una plantilla aprobada, a cualquier hora |
POST /whatsapp/messages | whatsapp:send | Envía un mensaje (texto, multimedia, ubicación, botones, lista o Flow) en la ventana de 24 horas |
POST /whatsapp/messages/{messageId}/reaction | whatsapp:send | Reacciona a un mensaje |
POST /whatsapp/messages/{messageId}/read | whatsapp:send | Marca como leído un mensaje recibido |
GET /whatsapp/flows | whatsapp:send | Flows publicados de un número |
GET /instagram/accounts | instagram:read | Cuentas de Instagram conectadas |
POST /instagram/comments/{commentId}/reply | instagram:act | Responde un comentario en público |
POST /instagram/comments/{commentId}/private-reply | instagram:act | Responde al autor del comentario por DM |
POST /instagram/comments/{commentId}/hide | instagram:act | Oculta o muestra un comentario |
POST /instagram/messages | instagram:act | Envía un DM |
GET /webhook · PUT /webhook · DELETE /webhook | webhooks:manage | Consulta, registra o desactiva el webhook de la clave |
POST /agents/{agentId}/output-review | guardrails:review | Revisa la respuesta de un agente externo |
Alcances
Al crear la clave, marcas los permisos. Cada uno es un alcance (scope):
| Alcance | En pantalla | Permite |
|---|---|---|
whatsapp:send | Enviar mensajes de WhatsApp | listar números, plantillas y Flows, enviar plantillas y mensajes, reaccionar y marcar como leído |
instagram:read | Leer cuentas de Instagram | listar las cuentas conectadas |
instagram:act | Responder, ocultar y enviar DM en Instagram | responder y ocultar comentarios y enviar DM |
webhooks:manage | Recibir eventos (comentarios y DM) por webhook | registrar y desactivar el webhook |
guardrails:review | Revisar respuestas del agente (guardrails) | revisar la respuesta de un agente externo |
Una ruta llamada sin el alcance responde 403 MISSING_SCOPE.
Reglas y límites
- Todo queda atado al workspace de la clave. Un número, cuenta, agente o conversación de otro workspace responde 404, como si no existiera.
- La clave no es una persona. No entra en XBASE por la pantalla y no usa los permisos de quien la creó: solo vale lo que permiten los alcances.
- Los límites de Meta siguen valiendo. Por ejemplo, el DM de Instagram y el mensaje libre de WhatsApp solo salen dentro de la ventana de 24 horas, y la plantilla de WhatsApp tiene que estar aprobada.
- Los errores tienen un
codeestable, que tu integración debe tratar en lugar del texto del mensaje: Errores.
Preguntas frecuentes
Ver también
Facturación
Cómo cobra XBASE: plan mensual, créditos de IA, billetera para la IA extra, tarifas de Meta (pagadas a Meta), recarga y dónde ver facturas y consumo.
Autenticación: claves de API
Cómo crear una clave de API de XBASE, elegir los alcances, enviar la clave en las solicitudes, comprobarla con GET /me y revocarla.