Genuka WA docs

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:

Encabezado
Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Manté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étodoEndpointDescripción
GET/api/v1/companiesLista las empresas conectadas con sus conexiones
GET/api/v1/companies/{id}Una empresa + conexiones + conteos
GET /api/v1/companies
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étodoEndpointDescripción
GET/api/v1/connectionsLista 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étodoEndpointDescripción
GET/api/v1/templatesLista las plantillas (opcional ?companyId=)
POST/api/v1/templatesCrea y envía una plantilla a Meta
GET/api/v1/templates/{id}Una plantilla + su historial de estados
POST/api/v1/templates/syncVuelve 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:

TipoFormaDescripción
HEADERformat: TEXT | IMAGE | VIDEO | DOCUMENT | LOCATIONOpcional. Uno por plantilla. Los encabezados multimedia necesitan un handle de ejemplo.
BODYtext + exampleObligatorio (excepto en AUTHENTICATION). Contiene las variables {{1}}… o {{name}}.
FOOTERtextPie de página corto opcional. Sin variables.
BUTTONSQUICK_REPLY | URL | PHONE_NUMBER | COPY_CODE | OTPOpcional. 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)

POST /api/v1/templates
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.

POST /api/v1/templates (con nombre)
{
  "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.

TipoFormaDescripción
COPY_CODEotp_type: COPY_CODEEl cliente toca para copiar el código. Lo más simple, funciona en todas partes.
ONE_TAPotp_type: ONE_TAPAutocompletado en Android. Requiere package_name + signature_hash.
ZERO_TAPotp_type: ZERO_TAPEl código se entrega de forma silenciosa a la app. Requiere el mismo vínculo con la app.
POST /api/v1/templates (autenticación)
{
  "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.

POST /api/v1/templates/sync
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.

200 OK
{
  "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étodoEndpointDescripción
GET/api/v1/campaignsLista las campañas (opcional ?companyId=)
POST/api/v1/campaignsCrea una campaña con destinatarios
GET/api/v1/campaigns/{id}Una campaña con estadísticas de entrega
GET/api/v1/campaigns/{id}/recipientsEstado por destinatario (?status=, ?limit=)
POST/api/v1/campaigns/{id}/launchEnví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.

POST /api/v1/campaigns
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

POST /api/v1/campaigns/{id}/launch
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.

POST /api/v1/media (multipart)
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.

RutaDescripción
POST /api/v1/mediaCarga. Multipart: file (obligatorio), companyId (obligatorio con una clave de socio de alcance global), filename (opcional).
GET /api/v1/mediaListado. 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}/contentLos bytes, autenticados con tu clave.
DELETE /api/v1/media/{id}Elimina ahora, sin esperar al vencimiento.
POST /api/v1/media/header-handleGenera 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.

POST /api/v1/media/header-handle (multipart)
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:

POST /api/v1/templates
{
  "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.

POST /api/v1/messages
{
  "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étodoEndpointDescripción
POST/api/v1/messagesEnví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.

CampoVentanaDescripción
templatefacturablePlantilla aprobada previamente. La única forma de iniciar una conversación fuera de la ventana de 24 h.
textgratis*{ "text": "Hi" } o { "text": { "body": "…", "previewUrl": true } }
image / video / audio / document / stickergratis*{ "image": { "assetId": "ast_1" } } (recomendado), { "link": "…" } o { "id": "<media-id>" }; caption/filename opcionales
locationgratis*{ "location": { "latitude": …, "longitude": …, "name": "…", "address": "…" } }
contactsgratis*{ "contacts": [ … objetos de contacto de Meta … ] }
reactiongratis*{ "reaction": { "messageId": "wamid…", "emoji": "👍" } }
buttons / list / ctagratis*Botones de respuesta interactivos, un menú de lista o un botón URL de llamada a la acción.
locationRequestgratis*{ "locationRequest": { "body": "Where should we deliver?" } } — muestra un botón para enviar la ubicación.
callPermissionRequestgratis*{ "callPermissionRequest": { "body": "Can we call you back?" } } — pide permiso al cliente para llamarlo por WhatsApp (body opcional). Growth o superior.
voiceCallgratis*{ "voiceCall": { "body": "Call us on WhatsApp", "displayText": "Call", "ttlMinutes": 120 } } — un botón que llama a este número por WhatsApp. Growth o superior.
rawgratis*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.

POST /api/v1/messages (plantilla, simple)
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…" } }
POST /api/v1/messages (plantilla, encabezado + cuerpo + botón)
{
  "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).

POST /api/v1/messages (autenticación)
{
  "connectionId": "con_1",
  "to": "+237690000001",
  "template": { "name": "verification_code", "language": "en_US", "otp": "472913" }
}

Mensajes de sesión libres

texto
{ "connectionId": "con_1", "to": "+237690000001", "text": "Thanks, talk soon!" }
imagen (con pie de foto)
{ "connectionId": "con_1", "to": "+237690000001",
  "image": { "link": "https://example.com/promo.jpg", "caption": "New arrivals 🎉" } }
documento
{ "connectionId": "con_1", "to": "+237690000001",
  "document": { "link": "https://example.com/invoice.pdf", "filename": "invoice-1024.pdf" } }
botones de respuesta interactivos
{
  "connectionId": "con_1",
  "to": "+237690000001",
  "buttons": {
    "body": "Confirm your order?",
    "footer": "Acme Coffee",
    "buttons": [
      { "id": "yes", "title": "Confirm" },
      { "id": "no",  "title": "Cancel" }
    ]
  }
}
lista interactiva
{
  "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" }
      ] }
    ]
  }
}
botón URL de llamada a la acción
{
  "connectionId": "con_1",
  "to": "+237690000001",
  "cta": { "body": "Your receipt is ready.", "displayText": "View receipt", "url": "https://example.com/r/1024" }
}
respuesta en el hilo + reacción
{ "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étodoEndpointDescripción
GET/api/v1/numbers/{id}/callingConfiguración de llamadas de un número: status, callIconVisibility, callHours, callbackPermissionStatus, sipEnabled
PATCH/api/v1/numbers/{id}/callingLa modifica. Un patch real: el resto se conserva.
POST/api/v1/callsUna 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)
PATCH /api/v1/numbers/con_1/calling — activar las llamadas, en horario de oficina
{
  "status": "ENABLED",
  "callHours": {
    "status": "ENABLED",
    "timezoneId": "Africa/Douala",
    "weeklyOperatingHours": [{ "dayOfWeek": "MONDAY", "openTime": "0800", "closeTime": "1800" }],
    "holidaySchedule": []
  }
}
POST /api/v1/calls — contestar una llamada entrante
{ "action": "accept", "callId": "wacid.HBgL…", "sdp": "v=0\r\no=- 8236… (tu respuesta SDP)" }
POST /api/v1/calls — llamar a un cliente que dio su permiso
{ "connectionId": "con_1", "action": "connect", "to": "+237690000001", "sdp": "v=0\r\n… (tu oferta SDP)" }
  • sdp es solo el SDP: su tipo se deduce de la acción (oferta en connect, respuesta en pre_accept / accept). connect devuelve { "data": { "action": "connect", "callId": "wacid…" } }.
  • connectionId se puede omitir cuando callId designa una llamada que Genuka WA ya vio (el webhook de una llamada entrante, o un connect hecho aquí).
  • Una llamada entrante suena durante unos 30 segundos: pre_accept tiene que salir dentro de ese plazo.
EstadoerrorCuándo
403plan_feature_unavailableEl plan no incluye llamadas (Starter).
409calling_unavailable_coexistenceEl número está compartido con la app WhatsApp Business: WhatsApp no permite llamadas por la API en él.
409calling_sip_configuredEl número señaliza sus llamadas por SIP, configurado fuera de Genuka WA (solo PATCH).
409number_offboardedEl número salió de la plataforma: vuelve a conectarlo.
404call_not_foundcallId sin connectionId, y ninguna llamada conocida con ese id: pasa el connectionId.
400invalid_call_action / invalid_calling_settingsTodos los problemas del cuerpo, de una vez, en issues.
422meta_errorMeta 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étodoEndpointDescripción
GET/api/v1/subscriptionPlan actual, límites y uso
GET /api/v1/subscription
{
  "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

Ejemplos
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 fallas

Lo 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:

422 — rechazado por Meta
{
  "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.

En esta página