Referencia de la API
Una sola API para controlarlo todo de forma programática: números, plantillas, mensajes, campañas y tu suscripción.
Construye tu propio producto sobre ella.
Especificación OpenAPI
Toda la API está descrita en OpenAPI 3.1 en
https://wa.genuka.com/openapi.json: impórtala en
Postman o Insomnia, o dásela a un agente de programación con IA. Para los agentes,
/llms.txt indexa toda la documentación.
Autenticación
Todas las solicitudes usan una clave API del lado del servidor. Genera una en tu panel, en
Claves API: tiene la forma pk_live_… y se muestra una sola vez. Envíala como bearer token:
Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxMantén las claves del lado del servidor
Una clave puede enviar mensajes desde todos los números que cubre. Nunca la expongas en un navegador ni en una app móvil: llama a la API únicamente desde tu backend.
Alcance de la clave
Una clave abarca toda la cuenta o está vinculada a una sola empresa conectada. Elige la empresa al
generar la clave en Claves API. Una clave con alcance restringido solo resuelve esa empresa: las
listas devuelven únicamente sus filas, los ids que pertenecen a otra responden 404 y
GET /api/v1/subscription responde 403; así puedes entregársela a esa empresa (o ejecutar su
integración) sin exponer el resto de tu cuenta. Las claves de toda la cuenta llegan a todos los
números que conectaste.
Convenciones
URL base https://wa.genuka.com/api/v1. Los cuerpos y las respuestas son JSON. Los endpoints de
listado devuelven { "data": [...] }. Todo queda automáticamente limitado a tu cuenta. Los errores
usan códigos de estado HTTP con { "error": "code", "message": "…" }.
Llama a wa.genuka.com por https y sin barra final: http:// devuelve un 301 hacia https,
/api/v1/messages/ un 308 hacia la forma sin barra, y algunos clientes HTTP descartan el
encabezado Authorization al seguir una redirección. Ningún otro nombre de host sirve esta API.
Envía un User-Agent
Nuestra CDN rechaza algunas firmas de bots conocidas antes de que lleguen a la API. La que más
encuentran nuestros integradores es Python-urllib/3.x, el encabezado que urllib envía por
defecto: responde 403 con el cuerpo error code: 1010, que no proviene de nosotros y por lo
tanto no lleva JSON. Envía un User-Agent que identifique tu integración, que es además lo que te
permitirá encontrarte en tus propios registros:
request.add_header("User-Agent", "acme-crm/1.4 (+https://example.com)")requests, curl, axios, node-fetch y los clientes de Go y Java pasan sin ningún cambio.
Empresas (negocios conectados)
| Método | Endpoint | Descripción |
|---|---|---|
GET | /api/v1/companies | Lista las empresas conectadas con sus conexiones |
GET | /api/v1/companies/{id} | Una empresa + conexiones + conteos |
curl https://wa.genuka.com/api/v1/companies -H "Authorization: Bearer pk_live_xxx"
{
"data": [
{
"id": "cmp_123",
"name": "Acme Coffee",
"onboardedAt": "2026-06-01T10:12:00.000Z",
"connections": [
{ "id": "con_1", "wabaId": "1029…", "phoneNumberId": "1065…",
"displayPhoneNumber": "+237 6 90 …", "qualityRating": "GREEN", "status": "connected" }
],
"_count": { "templates": 4 }
}
]
}Conexiones (números)
| Método | Endpoint | Descripción |
|---|---|---|
GET | /api/v1/connections | Lista las conexiones de WhatsApp (opcional ?companyId=, ?externalRef=) |
Una conexión es una WABA + un número de teléfono. Su id es lo que pasas al crear plantillas,
campañas o al enviar mensajes.
Plantillas
Las plantillas son formatos de mensaje aprobados previamente. Necesitas una para iniciar una
conversación (es decir, escribirle a un cliente fuera de la ventana de 24 horas; consulta
Mensajes). Creas una plantilla aquí, Meta la revisa, y la aprobación o el rechazo
llega automáticamente a GET /templates/{id} (y a tus webhooks).
| Método | Endpoint | Descripción |
|---|---|---|
GET | /api/v1/templates | Lista las plantillas (opcional ?companyId=) |
POST | /api/v1/templates | Crea y envía una plantilla a Meta |
GET | /api/v1/templates/{id} | Una plantilla + su historial de estados |
POST | /api/v1/templates/sync | Vuelve a leer todos los estados desde Meta |
DELETE | /api/v1/templates/{id} | Elimina en Meta y localmente |
Cómo funciona la creación
Pasas el arreglo components de Meta tal cual. Eso mantiene este endpoint ligero y te permite
construir cualquier plantilla que Meta admita: texto, encabezados multimedia, botones, OTP, etc.
Los únicos campos obligatorios son connectionId, name y components. category es uno de
MARKETING, UTILITY o AUTHENTICATION (por defecto MARKETING); language es una configuración
regional de Meta como en_US o fr (por defecto en).
Referencia de componentes
Una plantilla es una lista ordenada de componentes. Cada uno tiene un type:
| Tipo | Forma | Descripción |
|---|---|---|
HEADER | format: TEXT | IMAGE | VIDEO | DOCUMENT | LOCATION | Opcional. Uno por plantilla. Los encabezados multimedia necesitan un handle de ejemplo. |
BODY | text + example | Obligatorio (excepto en AUTHENTICATION). Contiene las variables {{1}}… o {{name}}. |
FOOTER | text | Pie de página corto opcional. Sin variables. |
BUTTONS | QUICK_REPLY | URL | PHONE_NUMBER | COPY_CODE | OTP | Opcional. Hasta 10 botones (las reglas varían según el tipo). |
Los ejemplos son obligatorios
Todo componente con variables (o un encabezado multimedia) debe incluir un example para que Meta
pueda revisarlo: "example": { "body_text": [["Alice", "#1024"]] } para el cuerpo,
"example": { "header_handle": ["<id>"] } para un encabezado multimedia.
Plantilla de utilidad / marketing (encabezado + cuerpo + botones)
curl -X POST https://wa.genuka.com/api/v1/templates \
-H "Authorization: Bearer pk_live_xxx" -H "Content-Type: application/json" \
-d '{
"connectionId": "con_1",
"name": "order_shipped",
"language": "en_US",
"category": "UTILITY",
"components": [
{ "type": "HEADER", "format": "IMAGE",
"example": { "header_handle": ["4::aW1hZ2Uv..."] } },
{ "type": "BODY",
"text": "Hi {{1}}, order {{2}} just shipped. Track it any time.",
"example": { "body_text": [["Alice", "#1024"]] } },
{ "type": "FOOTER", "text": "Reply STOP to opt out" },
{ "type": "BUTTONS", "buttons": [
{ "type": "URL", "text": "Track order",
"url": "https://example.com/track/{{1}}", "example": ["https://example.com/track/1024"] },
{ "type": "QUICK_REPLY", "text": "Need help" }
] }
]
}'
{ "data": { "id": "tpl_123", "status": "pending", "providerId": "12534…" } }El example.header_handle del encabezado multimedia es el handle de carga reanudable que devuelve
la carga de multimedia de Meta; en el momento del envío proporcionas la imagen real por URL o por
media id (consulta Mensajes → plantilla).
Parámetros con nombre
¿Prefieres {{name}} en lugar del posicional {{1}}? Define parameterFormat: "NAMED" y asigna a
cada variable un parameter_name en el ejemplo.
{
"connectionId": "con_1",
"name": "appointment_reminder",
"language": "en_US",
"category": "UTILITY",
"parameterFormat": "NAMED",
"components": [
{ "type": "BODY",
"text": "Hi {{customer_name}}, your appointment is on {{date}}.",
"example": { "body_text_named_params": [
{ "param_name": "customer_name", "example": "Alice" },
{ "param_name": "date", "example": "June 20" }
] } }
]
}Plantilla de autenticación (OTP)
Las plantillas de autenticación entregan códigos de un solo uso. El texto del cuerpo y del botón los fija WhatsApp: tú no redactas el texto. Solo eliges el tipo de botón y algunas opciones. No se permiten encabezados, multimedia, URLs ni emojis.
| Tipo | Forma | Descripción |
|---|---|---|
COPY_CODE | otp_type: COPY_CODE | El cliente toca para copiar el código. Lo más simple, funciona en todas partes. |
ONE_TAP | otp_type: ONE_TAP | Autocompletado en Android. Requiere package_name + signature_hash. |
ZERO_TAP | otp_type: ZERO_TAP | El código se entrega de forma silenciosa a la app. Requiere el mismo vínculo con la app. |
{
"connectionId": "con_1",
"name": "verification_code",
"language": "en_US",
"category": "AUTHENTICATION",
"messageSendTtlSeconds": 600,
"components": [
{ "type": "BODY", "add_security_recommendation": true },
{ "type": "FOOTER", "code_expiration_minutes": 10 },
{ "type": "BUTTONS", "buttons": [
{ "type": "OTP", "otp_type": "COPY_CODE", "text": "Copy code" }
] }
]
}Para ONE_TAP / ZERO_TAP, agrega el vínculo con la app al botón OTP: "autofill_text": "Autofill",
"supported_apps": [{ "package_name": "com.example.app", "signature_hash": "K8a..." }].
Enviar el código
Crear la plantilla nunca envía nada. Para entregar un código, envías un mensaje template con el
atajo otp: consulta Mensajes → plantilla de autenticación.
Actualizar los estados
El resultado de una revisión te llega como webhook: esa es la vía sobre la que
debes construir. Pero un webhook que nunca se entregó (un endpoint caído, una integración agregada
después) deja la plantilla en pending aquí mucho después de que Meta la aprobó, y una campaña que
se niega a lanzarse sin motivo visible. POST /api/v1/templates/sync vuelve a leer la verdad desde
Meta y la escribe de nuevo.
curl -X POST https://wa.genuka.com/api/v1/templates/sync \
-H "Authorization: Bearer pk_live_xxx" -H "Content-Type: application/json" \
-d '{ "companyId": "cmp_1" }'El cuerpo es opcional: sin ningún campo, la actualización cubre todas las cuentas de WhatsApp a las
que llega tu clave; companyId la limita a un cliente y connectionId a la WABA de un solo número.
La respuesta nombra cada cuenta de WhatsApp que procesó (así, una cuenta inaccesible se informa en
lugar de ocultarse) y devuelve las filas recién escritas, lo que te ahorra un GET posterior.
{
"data": {
"wabas": [{ "wabaId": "1029…", "companyId": "cmp_1", "ok": true }],
"synced": 1,
"failed": 0,
"templates": [
{ "id": "tpl_1", "name": "order_shipped", "language": "fr", "status": "approved", "…": "…" }
]
}
}Una actualización en la que todas las cuentas se negaron responde 502 meta_rejected con los
mismos results en el cuerpo; un fallo parcial sigue siendo un 200 que debes leer.
GET /api/v1/templates?sync=true hace la misma actualización en línea antes de listar, y acepta los
mismos filtros companyId / connectionId.
Es una vía de reparación, no un bucle de sondeo
Cada llamada consume una lectura de Meta por cuenta de WhatsApp. Ejecútala de forma programada si quieres (cada hora es más que suficiente), pero conserva el webhook como la forma normal en que llegan los estados.
Campañas
| Método | Endpoint | Descripción |
|---|---|---|
GET | /api/v1/campaigns | Lista las campañas (opcional ?companyId=) |
POST | /api/v1/campaigns | Crea una campaña con destinatarios |
GET | /api/v1/campaigns/{id} | Una campaña con estadísticas de entrega |
GET | /api/v1/campaigns/{id}/recipients | Estado por destinatario (?status=, ?limit=) |
POST | /api/v1/campaigns/{id}/launch | Envía a todos los destinatarios pendientes |
Crear una campaña
Cada destinatario lleva sus propias variables. La forma simple es un arreglo posicional para los
parámetros del cuerpo {{1}}, {{2}}…. Para encabezados multimedia, botones o códigos OTP, pasa en
su lugar un objeto enriquecido ({ "body": [...], "header": {...}, "buttons": [...] }), con la misma
forma que acepta Mensajes → plantilla. La plantilla debe estar approved antes del
lanzamiento. A continuación, tpl_124 es una plantilla con solo cuerpo; tpl_123 (order_shipped
más arriba, con encabezado de imagen y botón URL) necesitaría la forma enriquecida para cada
destinatario.
curl -X POST https://wa.genuka.com/api/v1/campaigns \
-H "Authorization: Bearer pk_live_xxx" -H "Content-Type: application/json" \
-d '{
"connectionId": "con_1",
"templateId": "tpl_124",
"name": "June promo",
"recipients": [
{ "to": "+237690000001", "variables": ["Alice", "#1024"] },
{ "to": "+237690000002", "variables": ["Bob", "#1025"] }
]
}'
{ "data": { "id": "cmp_9", "name": "June promo", "status": "draft", "_count": { "recipients": 2 } } }Lanzar
curl -X POST https://wa.genuka.com/api/v1/campaigns/cmp_9/launch \
-H "Authorization: Bearer pk_live_xxx"
{ "data": { "sent": 2, "failed": 0, "skipped": 0 } }Límites
Nunca cobramos por mensaje: Meta factura directamente a tu WABA. Los destinatarios sí cuentan
contra la cuota de mensajes de tu plan para el período, y toda la lista se verifica antes del
primer envío, de modo que un lanzamiento que no cabría se rechaza de entrada con
402 plan_limit_messages en lugar de detenerse a la mitad. Solo se consumen los destinatarios que
Meta realmente aceptó. La V1 envía de forma síncrona: mantén listas moderadas; el envío en cola
para listas grandes está en la hoja de ruta.
Multimedia
Sube un archivo una vez y envíalo tantas veces como necesites. El almacenamiento es privado: nada de lo que se guarda aquí es accesible desde una URL pública, y Meta nunca descarga el archivo; le entregamos los bytes de servidor a servidor en el momento del envío.
curl -X POST https://wa.genuka.com/api/v1/media \
-H "Authorization: Bearer pk_live_xxx" \
-F "companyId=cmp_1" \
-F "[email protected]"
{ "data": {
"id": "ast_1",
"url": "https://wa.genuka.com/api/v1/media/ast_1/content",
"expiresAt": "2026-09-18T09:12:00.000Z",
"mimeType": "application/pdf",
"kind": "document",
"sizeBytes": 481203,
"filename": "briefing.pdf"
},
"deduplicated": false }Dos límites, anunciados de entrada
Retención: 30 días. Cada archivo se elimina de forma permanente 30 días después de su carga, y
expiresAt indica exactamente cuándo. Es la propia ventana de Meta: pasado ese plazo, su copia
desaparece de todos modos. Un envío que hace referencia a un archivo vencido responde
404 media_not_found.
Almacenamiento: según el plan. 1 GB en Starter, 3 GB en Growth, 5 GB en Scale, a medida en
Enterprise, sumando todos los clientes. El límite se aplica a lo que está guardado: eliminar un
archivo libera el espacio de inmediato. Una carga que lo superaría responde 402 plan_limit_media
antes de almacenar un solo byte. GET /api/v1/media devuelve la cifra actual en storage.
url es un endpoint de esta API, no un enlace para compartir: requiere tu clave y rechaza cualquier
llamada fuera de su alcance. Los bytes idénticos ya almacenados para este cliente se devuelven tal
cual con un 200 y deduplicated: true, en lugar de almacenarse dos veces.
| Ruta | Descripción |
|---|---|
POST /api/v1/media | Carga. Multipart: file (obligatorio), companyId (obligatorio con una clave de socio de alcance global), filename (opcional). |
GET /api/v1/media | Listado. Filtros kind, companyId, paginación por cursor, además de la cifra storage. |
GET /api/v1/media/{id} | Los metadatos de un archivo. |
GET /api/v1/media/{id}/content | Los bytes, autenticados con tu clave. |
DELETE /api/v1/media/{id} | Elimina ahora, sin esperar al vencimiento. |
POST /api/v1/media/header-handle | Genera el header_handle para el encabezado de una plantilla. Multipart: file (obligatorio), connectionId o companyId (ninguno de los dos con una clave de cliente). |
El encabezado multimedia de una plantilla: el header_handle
Crear una plantilla cuyo encabezado es IMAGE, VIDEO o DOCUMENT requiere un example.header_handle,
que Meta solo emite a través de su Resumable Upload API. No es lo mismo que un assetId: un
handle se consume una sola vez, al crear la plantilla, y un envío lo rechaza. A la inversa, un
assetId no sirve de nada al momento de la creación.
curl -X POST https://wa.genuka.com/api/v1/media/header-handle \
-H "Authorization: Bearer pk_live_xxx" \
-F "connectionId=con_1" \
-F "[email protected]"
{ "data": {
"handle": "4::YXBwbGljYXRpb24vcGRm…",
"filename": "catalogue.pdf",
"mimeType": "application/pdf",
"sizeBytes": 481203
} }Indica el cliente como lo espera cualquier otra ruta /media (-F "companyId=cmp_1") o un número
específico (-F "connectionId=con_1"); una clave de cliente no necesita ninguno de los dos. El
handle es el mismo en ambos casos: la sesión de carga pertenece a la app de Meta, no a un número.
Lleva ese handle a la definición de la plantilla:
{
"connectionId": "con_1",
"name": "morning_brief",
"language": "en_US",
"category": "UTILITY",
"components": [
{ "type": "HEADER", "format": "DOCUMENT",
"example": { "header_handle": ["4::YXBwbGljYXRpb24vcGRm…"] } },
{ "type": "BODY", "text": "Hi {{1}}, your brief for {{2}} is attached.",
"example": { "body_text": [["Ana", "March 12"]] } }
]
}Formatos aceptados: image/jpeg, image/png, video/mp4, video/3gpp, application/pdf. Tamaño
máximo de 4 MB; por encima, la respuesta es 413 media_too_large. No guardamos nada de nuestro
lado: el handle es de un solo uso, así que archivarlo no serviría de nada.
Enviar un archivo almacenado
Pasa assetId en cualquier lugar donde se espere un objeto multimedia, incluidos los encabezados de
plantilla. Resolvemos el media_id de Meta para el número de teléfono correcto y lo renovamos a
medida que envejece.
{
"connectionId": "con_1",
"to": "+237600000000",
"document": { "assetId": "ast_1", "filename": "briefing.pdf" }
}id (un media_id de Meta que generaste tú mismo) y link (una URL pública que Meta descarga)
siguen aceptándose. assetId es el preferible: es el único que no expone el archivo en ninguna URL
y el único que no vence a tus espaldas a los 30 días.
Mensajes
| Método | Endpoint | Descripción |
|---|---|---|
POST | /api/v1/messages | Envía un solo mensaje de cualquier tipo |
Un solo endpoint envía todos los tipos de mensaje de WhatsApp. Pasa siempre connectionId y to, y
luego exactamente un campo de contenido de la tabla siguiente. Agrega replyTo (el wamid de
un mensaje recibido) para citar o responder a un mensaje.
| Campo | Ventana | Descripción |
|---|---|---|
template | facturable | Plantilla aprobada previamente. La única forma de iniciar una conversación fuera de la ventana de 24 h. |
text | gratis* | { "text": "Hi" } o { "text": { "body": "…", "previewUrl": true } } |
image / video / audio / document / sticker | gratis* | { "image": { "assetId": "ast_1" } } (recomendado), { "link": "…" } o { "id": "<media-id>" }; caption/filename opcionales |
location | gratis* | { "location": { "latitude": …, "longitude": …, "name": "…", "address": "…" } } |
contacts | gratis* | { "contacts": [ … objetos de contacto de Meta … ] } |
reaction | gratis* | { "reaction": { "messageId": "wamid…", "emoji": "👍" } } |
buttons / list / cta | gratis* | Botones de respuesta interactivos, un menú de lista o un botón URL de llamada a la acción. |
locationRequest | gratis* | { "locationRequest": { "body": "Where should we deliver?" } } — muestra un botón para enviar la ubicación. |
callPermissionRequest | gratis* | { "callPermissionRequest": { "body": "Can we call you back?" } } — pide permiso al cliente para llamarlo por WhatsApp (body opcional). Growth o superior. |
voiceCall | gratis* | { "voiceCall": { "body": "Call us on WhatsApp", "displayText": "Call", "ttlMinutes": 120 } } — un botón que llama a este número por WhatsApp. Growth o superior. |
raw | gratis* | Vía de escape para todo lo demás (Flows, dirección, catálogo): un fragmento completo de tipo de la Cloud API. |
La ventana de 24 horas
Solo los envíos template pueden iniciar una conversación. Todo lo marcado como free* es un
mensaje de sesión libre: solo se entrega si el cliente le escribió a la empresa en las últimas
24 horas. Fuera de esa ventana, usa un template. Todos los envíos devuelven
{ "data": { "messageId": "wamid…" } }.
Un 200 significa que Meta aceptó el mensaje, no que se haya entregado. El estado final
(sent → delivered → read, o failed) llega de forma asíncrona a tus
webhooks. En to, incluye siempre el + y el código de país (por ejemplo,
+237690000001): omitirlo puede enrutar mal el mensaje. Meta guarda en caché durante ~10 minutos
la multimedia pasada por link, así que reutiliza la misma URL para el mismo recurso (o agrega una
query string única para invalidar la caché).
Mensaje de plantilla
El caso simple es una plantilla cuyas únicas variables están en el cuerpo, como order_update a
continuación (sin encabezado multimedia ni botón dinámico). variables es un arreglo posicional;
también puedes usar bodyNamed para plantillas con nombre, header para un encabezado multimedia o
de texto, y buttons para los parámetros de botones dinámicos. Un envío debe completar todos los
parámetros que declara la plantilla: order_shipped, más arriba, tiene un encabezado de imagen y un
botón URL dinámico, así que necesita la segunda forma; solo con las variables del cuerpo, Meta lo
rechaza.
curl -X POST https://wa.genuka.com/api/v1/messages \
-H "Authorization: Bearer pk_live_xxx" -H "Content-Type: application/json" \
-d '{
"connectionId": "con_1",
"to": "+237690000001",
"template": { "name": "order_update", "language": "en_US", "variables": ["Alice", "#1024"] }
}'
{ "data": { "messageId": "wamid.HBg…" } }{
"connectionId": "con_1",
"to": "+237690000001",
"template": {
"name": "order_shipped",
"language": "en_US",
"header": { "image": { "link": "https://example.com/orders/1024.png" } },
"variables": ["Alice", "#1024"],
"buttons": [
{ "type": "url", "text": "1024" }
]
}
}El buttons[].text completa la parte dinámica de un botón URL (el {{1}} de
https://example.com/track/{{1}}). Para una respuesta rápida usa
{ "type": "quick_reply", "payload": "…" }; para un código de cupón usa
{ "type": "copy_code", "code": "SAVE20" }. Parámetros de cuerpo con nombre:
"bodyNamed": { "customer_name": "Alice" }.
Plantilla de autenticación
Pasa el código una sola vez con el atajo otp: completamos por ti tanto el cuerpo como el botón OTP
(el formato que exige Meta).
{
"connectionId": "con_1",
"to": "+237690000001",
"template": { "name": "verification_code", "language": "en_US", "otp": "472913" }
}Mensajes de sesión libres
{ "connectionId": "con_1", "to": "+237690000001", "text": "Thanks, talk soon!" }{ "connectionId": "con_1", "to": "+237690000001",
"image": { "link": "https://example.com/promo.jpg", "caption": "New arrivals 🎉" } }{ "connectionId": "con_1", "to": "+237690000001",
"document": { "link": "https://example.com/invoice.pdf", "filename": "invoice-1024.pdf" } }{
"connectionId": "con_1",
"to": "+237690000001",
"buttons": {
"body": "Confirm your order?",
"footer": "Acme Coffee",
"buttons": [
{ "id": "yes", "title": "Confirm" },
{ "id": "no", "title": "Cancel" }
]
}
}{
"connectionId": "con_1",
"to": "+237690000001",
"list": {
"body": "Pick a delivery slot",
"button": "Choose",
"sections": [
{ "title": "Today", "rows": [
{ "id": "t1", "title": "12:00–14:00" },
{ "id": "t2", "title": "14:00–16:00", "description": "Most popular" }
] }
]
}
}{
"connectionId": "con_1",
"to": "+237690000001",
"cta": { "body": "Your receipt is ready.", "displayText": "View receipt", "url": "https://example.com/r/1024" }
}{ "connectionId": "con_1", "to": "+237690000001", "replyTo": "wamid.HBg…", "text": "On its way!" }
{ "connectionId": "con_1", "to": "+237690000001",
"reaction": { "messageId": "wamid.HBg…", "emoji": "👍" } }Llamadas de WhatsApp
Plan Growth o superior. Tu propio stack (un agente de voz, un softphone WebRTC) realiza y contesta
las llamadas; Genuka WA retransmite la señalización a Meta y te devuelve los webhooks call.*. El
audio nunca pasa por nosotros: el SDP describe una ruta entre Meta y tu stack. Consulta la guía
Conectar un agente de voz para ver los flujos de principio a fin.
| Método | Endpoint | Descripción |
|---|---|---|
GET | /api/v1/numbers/{id}/calling | Configuración de llamadas de un número: status, callIconVisibility, callHours, callbackPermissionStatus, sipEnabled |
PATCH | /api/v1/numbers/{id}/calling | La modifica. Un patch real: el resto se conserva. |
POST | /api/v1/calls | Una acción de llamada, retransmitida a Meta: connect, pre_accept, accept, reject, terminate |
GET | /api/v1/calls/permissions?waId=…&connectionId=… | Si puedes llamar a este usuario ahora (canCall) y si puedes pedírselo (canRequestPermission) |
{
"status": "ENABLED",
"callHours": {
"status": "ENABLED",
"timezoneId": "Africa/Douala",
"weeklyOperatingHours": [{ "dayOfWeek": "MONDAY", "openTime": "0800", "closeTime": "1800" }],
"holidaySchedule": []
}
}{ "action": "accept", "callId": "wacid.HBgL…", "sdp": "v=0\r\no=- 8236… (tu respuesta SDP)" }{ "connectionId": "con_1", "action": "connect", "to": "+237690000001", "sdp": "v=0\r\n… (tu oferta SDP)" }sdpes solo el SDP: su tipo se deduce de la acción (oferta enconnect, respuesta enpre_accept/accept).connectdevuelve{ "data": { "action": "connect", "callId": "wacid…" } }.connectionIdse puede omitir cuandocallIddesigna una llamada que Genuka WA ya vio (el webhook de una llamada entrante, o unconnecthecho aquí).- Una llamada entrante suena durante unos 30 segundos:
pre_accepttiene que salir dentro de ese plazo.
| Estado | error | Cuándo |
|---|---|---|
403 | plan_feature_unavailable | El plan no incluye llamadas (Starter). |
409 | calling_unavailable_coexistence | El número está compartido con la app WhatsApp Business: WhatsApp no permite llamadas por la API en él. |
409 | calling_sip_configured | El número señaliza sus llamadas por SIP, configurado fuera de Genuka WA (solo PATCH). |
409 | number_offboarded | El número salió de la plataforma: vuelve a conectarlo. |
404 | call_not_found | callId sin connectionId, y ninguna llamada conocida con ese id: pasa el connectionId. |
400 | invalid_call_action / invalid_calling_settings | Todos los problemas del cuerpo, de una vez, en issues. |
422 | meta_error | Meta lo rechazó: número no elegible, sin permiso de llamada, país excluido… con las palabras de Meta. |
Webhooks: call.connect (con data.session.sdp), call.status_changed, call.terminated y
call.permission_replied (consulta Webhooks).
Suscripción
| Método | Endpoint | Descripción |
|---|---|---|
GET | /api/v1/subscription | Plan actual, límites y uso |
{
"plan": { "code": "growth", "name": "Growth" },
"interval": "monthly",
"currency": "XAF",
"status": "active",
"currentPeriodEnd": "2026-07-18T00:00:00.000Z",
"billedNumbers": 9,
"usage": { "numbers": 9, "messages": 12480, "seats": 3 },
"limits": { "maxNumbers": 9, "monthlyMessages": 45000, "maxSeats": 5 }
}Errores
401 { "error": "missing_bearer_token" } // sin encabezado Authorization
401 { "error": "invalid_token" } // clave desconocida / revocada, o cuenta inactiva
403 { "error": "account_deactivated", "message": "Deactivated Account" }
// esa empresa está suspendida: su propia clave deja
// de funcionar, y toda solicitud que la nombre se
// rechaza, incluso con una clave de toda la cuenta
400 { "error": "missing_fields", "message": "…" }
400 { "error": "missing_content", "message": "…" } // ningún campo de contenido en un envío
400 { "error": "invalid_media", "message": "…" } // multimedia sin assetId, id ni link
402 { "error": "plan_limit_media", "message": "…" } // se alcanzó el límite de almacenamiento del plan
404 { "error": "media_not_found", "message": "…" } // assetId desconocido, o con más de 30 días
402 { "error": "plan_limit_numbers" } // todos los números que pagó el plan están en uso
402 { "error": "plan_limit_messages" } // se agotó la cuota de mensajes del período
402 { "error": "subscription_past_due" } // la prueba o el período pagado venció sin renovación
404 { "error": "connection_not_found" }
404 { "error": "template_not_found" }
409 { "error": "template_exists" }
413 { "error": "media_too_large", "message": "…" } // encabezado de plantilla de más de 4 MB
422 { "error": "meta_rejected", "message": "…", "meta": { … } }
// Meta leyó el payload y lo rechazó
502 { "error": "meta_rejected", "message": "…" } // Graph inaccesible o con fallasLo que Meta rechazó devuelve 422, no 502
Cuando Graph lee un payload y lo rechaza (una plantilla mal formada, una variable sin ejemplo, un
número no aprovisionado), la respuesta es un 422, y su cuerpo lleva un objeto meta con el
propio código de error de Meta, su traceId y su clase:
{
"error": "meta_rejected",
"message": "Invalid parameter",
"meta": {
"errorClass": "template",
"retryable": false,
"code": 100,
"details": "body_text example count does not match the number of variables",
"traceId": "AbC…"
}
}traceId es lo que pide el soporte de Meta: cítalo tal cual.
Un 502 queda reservado para lo que la palabra describe: Graph inaccesible, o Graph mismo con
fallas. Devolver un payload rechazado como 502 lo hacía imposible de diagnosticar: nuestra CDN
responde a los 5xx del origen con su propia página de error, que reemplaza ese cuerpo JSON por la
única línea error code: 502. El motivo del rechazo nunca te llegaba. Los cuerpos 4xx pasan sin
modificarse.
Registros de solicitudes
Cada respuesta lleva un encabezado x-request-id. El mismo id identifica la llamada en tu panel, en
Registros, donde cada solicitud se conserva con su estado, su duración, su cuerpo y, cuando falló,
la respuesta que devolvimos. Las entregas de webhooks aparecen al lado, con su payload firmado exacto
y un botón para reenviarlas.
Hasta dónde llega el registro depende de tu plan: 7 días en Starter, 30 en Growth, 90 en Scale.
Campos ocultados
Los cuerpos se almacenan para que un fallo sea reproducible, salvo todo lo que parezca una
credencial: los valores password, token, secret y api_key se reemplazan antes de escribir
la fila.
Conectar un agente de voz a las llamadas de WhatsApp
Recibe y realiza llamadas de WhatsApp con tu propio agente de voz o stack WebRTC: activar las llamadas, webhooks call.*, acciones de llamada con SDP, permisos.
Biblioteca TypeScript
@genuka/whatsapp — constructores tipados, validación y normalización de eventos.