Saltar al contenido
Documentación

Referencia de la API

Todas las rutas de la API pública de Orkestal con el permiso que exigen, sus parámetros y ejemplos de uso.

Actualizado el 4 de noviembre de 20264 min de lectura

Todas las rutas cuelgan de la URL base https://orkestal-backend-production.up.railway.app/api/public/v1 y requieren Authorization: Bearer ork_live_…. Antes de empezar, lee Autenticación y permisos.

Identidad#

GET /me#

Comprueba que la key funciona. No requiere permisos especiales.

json
{
  "business_id": "…",
  "business_name": "Mi Negocio",
  "api_key_name": "n8n producción",
  "scopes": ["contacts:read", "messages:write"]
}

Contactos#

Método y rutaPermisoQué hace
GET /contactscontacts:readLista contactos
POST /contactscontacts:writeCrea un contacto, o lo actualiza si el teléfono ya existe
GET /contacts/{id}contacts:readUn contacto
PATCH /contacts/{id}contacts:writeEdita nombre, correo, etiquetas o metadata
POST /contacts/{id}/tagstags:writeSuma etiquetas
DELETE /contacts/{id}/tags/{etiqueta}tags:writeQuita una etiqueta

Filtros de GET /contacts: search (busca en nombre, teléfono o correo), tag (una etiqueta), limit (1 a 100, por defecto 25) y cursor.

Objeto contacto:

json
{
  "id": "…",
  "phone": "+5215550001111",
  "name": "María López",
  "email": "maria@ejemplo.com",
  "tags": ["nuevo_lead"],
  "metadata": {},
  "created_at": "2026-11-04T18:22:04Z"
}

POST /contacts: el único campo obligatorio es phone. Es un upsert: si ya existe un contacto con ese teléfono, se actualiza. Las etiquetas se suman, nunca reemplazan las existentes, para que dos automatizaciones distintas no se pisen.

json
POST /contacts
{ "phone": "+5215550001111", "name": "María López", "tags": ["colegios"] }

Conversaciones#

Método y rutaPermisoQué hace
GET /conversationsconversations:readLista conversaciones
GET /conversations/{id}/messagesmessages:readHistorial de una conversación
PATCH /conversations/{id}conversations:writeCambia estado, etapa o asignación
POST /conversations/{id}/pause-agentconversations:writePausa la IA en ese chat
POST /conversations/{id}/resume-agentconversations:writeReactiva la IA en ese chat

Filtros de GET /conversations: status, contact_id, limit y cursor.

Objeto conversación:

json
{
  "id": "…",
  "contact_id": "…",
  "channel": "whatsapp",
  "status": "active",
  "sale_stage": "interesado",
  "assigned_to": "…",
  "created_at": "…"
}

GET /conversations/{id}/messages: hasta 100 mensajes (limit, por defecto 50), en orden cronológico (del más viejo al más nuevo), cada uno con id, sender_type, content, message_type y created_at.

PATCH /conversations/{id}: campos opcionales status, sale_stage (una etapa como interesado, negociacion o vendido) y assigned_to (el id de una persona de tu equipo).

pause-agent y resume-agent son el equivalente a los botones Pausar IA / Activar IA del chat. Mira Relevo humano.

Mensajes#

POST /messages#

Permiso: messages:write. Envía un mensaje de WhatsApp, de texto o de plantilla.

CampoQué es
toTeléfono del destinatario con código de país (si no das conversation_id)
conversation_idLa conversación a la que se envía (alternativa a to)
textEl texto libre
templateLa plantilla: { "name": "…", "variables": { "1": "…" } } (o id en lugar de name)
channelwhatsapp (por defecto)

Envía text o template, no ambos. Manda siempre Idempotency-Key.

json
POST /messages
Idempotency-Key: pedido-1234-recordatorio
{
  "to": "+5215550001111",
  "template": { "name": "recordatorio_pago", "variables": { "1": "María", "2": "$1,500" } }
}

Respuesta:

json
{
  "sent": true,
  "conversation_id": "…",
  "contact_id": "…",
  "message_id": "…",
  "mode": "template",
  "content": "…"
}

Reglas:

  • Antes de enviar texto libre, Orkestal valida la ventana de 24 horas. Si está cerrada responde 409 con instrucciones, en vez de dejar que Meta lo rechace con el error 131047.
  • La cuenta debe estar al corriente: con una suspensión por pago, responde 402.
  • El mensaje queda registrado en la conversación del contacto.

GET /templates#

Permiso: templates:read. Lista tus plantillas con id, name, language, status, category, las variables que espera y el body. Úsala para saber qué plantillas puedes enviar con POST /messages.

WhatsApp Cloud API (producto WhatsApp API)#

Estas rutas están disponibles para quien usa el producto WhatsApp API. Reciben y devuelven el formato de la Cloud API de Meta.

Método y rutaPermisoQué hace
POST /whatsapp/messagesmessages:writeEnvía un mensaje (texto, plantilla, multimedia) o marca como leído
POST /whatsapp/mediamessages:writeSube un archivo (multipart, campo file)
GET /whatsapp/media/{id}messages:readDescarga un archivo recibido
GET /whatsapp/phone-numberCalidad, límite y estado de Coexistencia del número
GET /whatsapp/templatestemplates:readLista las plantillas de Meta con todos sus estados
POST /whatsapp/templatestemplates:writeCrea una plantilla y la manda a revisión
DELETE /whatsapp/templates?name=…templates:writeBorra una plantilla

Suscripciones a webhooks#

Todas requieren webhooks:write.

Método y rutaQué hace
GET /webhook-subscriptionsLista tus suscripciones
POST /webhook-subscriptionsCrea una (solo URL https://)
PATCH /webhook-subscriptions/{id}Edita
DELETE /webhook-subscriptions/{id}Elimina
POST /webhook-subscriptions/{id}/rotate-secretGenera un secreto nuevo
POST /webhook-subscriptions/{id}/testManda un evento test.ping firmado
GET /webhook-subscriptions/deliveriesBitácora de entregas
POST /webhook-subscriptions/deliveries/{id}/retryReintenta una entrega

Límites y verificación de firma en Webhooks.

Agente externo#

Método y rutaPermisoQué hace
POST /external-agent/events/{event_id}/replymessages:writeDevuelve la respuesta de tu agente para un evento
GET /external-agent/events/{event_id}Consulta el estado del envío

Mira Agente externo.

Lo que la API no hace#

  • No expone credenciales ni tokens de tus canales o integraciones.
  • Con estas rutas no se crean ni editan flujos, reglas de escalamiento, la base de conocimiento ni el perfil del agente. Eso se hace desde el panel.
  • No lee datos de otros negocios.