WhatsApp API

Usa el número de WhatsApp Business de tu negocio desde tu propio sistema: recibe cada evento firmado en tu servidor y envía con el formato de la Cloud API.

Actualizado el 4 de noviembre de 20264 min de lectura

La WhatsApp API de Orkestal es para quien quiere usar su número de WhatsApp Business desde su propio sistema. Recibes cada evento de Meta en tu servidor y envías mensajes con el mismo formato de la Cloud API de Meta, sin dejar de usar la app de WhatsApp Business en el teléfono (Coexistencia).

Inicio rápido#

Conecta tu número en Canales → WhatsApp, escaneando el QR desde la app de WhatsApp Business (versión 2.24.17 o posterior). Mira WhatsApp. Agrega un método de pago en WhatsApp Manager: Meta cobra los mensajes directamente.
En Integraciones → WhatsApp API → Agregar webhook, pega la URL https:// de tu servidor y guarda el secreto de firma (se muestra una sola vez).
En Integraciones → n8n → API keys, crea una key con los permisos messages:write y messages:read (más templates:write y webhooks:write si los necesitas).
Envía tu primer mensaje (mira abajo).

La URL base es https://orkestal-backend-production.up.railway.app/api/public/v1 (también se muestra en el panel). La autenticación es Authorization: Bearer ork_live_....

Recibir: webhooks#

Cada cambio que Meta notifica llega a tu URL como un POST: mensajes entrantes, estados de entrega, mensajes que el negocio envía desde la app, historial, contactos y cambios de cuenta. El campo data tiene exactamente el formato de un webhook de Cloud API, con un cambio por entrega.

`field`	Qué es
`messages`	Mensajes entrantes (`value.messages`) y estados de lo que enviaste (`value.statuses`)
`smb_message_echoes`	Mensajes que el negocio escribió desde la app de WhatsApp Business
`history`	Historial de hasta 180 días que se sincroniza al conectar (en fases, una sola vez)
`smb_app_state_sync`	Altas, cambios y bajas de contactos en la app
`account_update`	Cambios de la cuenta, por ejemplo `PARTNER_REMOVED` si se desconecta
`message_template_status_update`	Una plantilla fue aprobada, rechazada o pausada

Reglas de entrega, reintentos y verificación de firma: mira Webhooks.

Solo reenviar: en este producto está siempre activo. Orkestal no guarda los mensajes en su bandeja ni responde con el agente de IA; solo los reenvía a tu servidor.

Enviar#

POST /whatsapp/messages, con el cuerpo de la Cloud API (Orkestal añade messaging_product). Manda siempre un Idempotency-Key único: cada mensaje se cobra, y un reintento sin clave lo duplica.

bash

curl -X POST $BASE/whatsapp/messages \
  -H "Authorization: Bearer ork_live_..." \
  -H "Idempotency-Key: 3b2c..." \
  -H "Content-Type: application/json" \
  -d '{"to":"5215598765432","type":"text","text":{"body":"Hola Ana"}}'

Fuera de la ventana de 24 horas, envía una plantilla:

json

{
  "to": "5215598765432",
  "type": "template",
  "template": {
    "name": "confirmacion_pedido",
    "language": { "code": "es_MX" },
    "components": [
      { "type": "body", "parameters": [{ "type": "text", "text": "#1234" }] }
    ]
  }
}

Para marcar un mensaje como leído: {"status":"read","message_id":"wamid.…"}.

La respuesta es la de Meta ({"messages":[{"id":"wamid…"}]}). Los errores de Meta (por ejemplo 131047, ventana cerrada) llegan tal cual con su código 4xx. Si Meta falla, Orkestal responde 502.

Multimedia#

Subir: POST /whatsapp/media (multipart, campo file). Devuelve {"id":"…"}, que usas en image.id, document.id, etc.
Descargar lo recibido: GET /whatsapp/media/{media_id} devuelve los bytes del archivo. El id llega en el webhook. Meta conserva la multimedia unos 30 días.

Plantillas#

GET /whatsapp/templates: la lista de Meta, con todos los estados.
POST /whatsapp/templates: crea una plantilla y la manda a revisión (cuerpo de Meta: name, language, category, components).
DELETE /whatsapp/templates?name=…: borra la plantilla.

Estado del número#

GET /whatsapp/phone-number devuelve la calidad, el límite y el estado de Coexistencia del número.

Gestionar webhooks por API#

Con el permiso webhooks:write: GET|POST /webhook-subscriptions, PATCH|DELETE /webhook-subscriptions/{id}, POST /webhook-subscriptions/{id}/rotate-secret, POST /webhook-subscriptions/{id}/test, GET /webhook-subscriptions/deliveries y POST /webhook-subscriptions/deliveries/{id}/retry. Hasta 3 suscripciones por negocio, solo https://.

Límites de la Coexistencia#

20 mensajes por segundo por número.
Por la API no hay grupos, mensajes temporales, «ver una vez», ubicación en vivo, llamadas, catálogo, estados ni canales. Las listas de difusión quedan en solo lectura.
Al conectar se desvinculan los dispositivos companion; WhatsApp para Windows y WearOS no se pueden volver a vincular.
Abre la app de WhatsApp Business al menos cada 14 días. Meta desconecta los números inactivos. Orkestal te avisa los días 10 y 13.
Para darte de baja: desconecta en Orkestal y también en la app (Herramientas para la empresa → Plataforma empresarial → Desconectar).

Seguridad#

El token de acceso de Meta nunca sale de Orkestal: tú usas tu API key y Orkestal añade el token en cada llamada. Mira Autenticación y permisos.