Genuka WA docs

Riferimento dell'API

Una sola API per gestire tutto in modo programmatico: numeri, modelli, messaggi, campagne e il tuo abbonamento.

Costruisci il tuo prodotto sopra di essa.

Specifica OpenAPI

L'intera API è descritta in OpenAPI 3.1 su https://wa.genuka.com/openapi.json: importala in Postman o Insomnia, oppure passala a un agente di programmazione AI. Per gli agenti, /llms.txt indicizza tutta la documentazione.

Autenticazione

Tutte le richieste usano una chiave API lato server. Generane una nella tua dashboard, in Chiavi API: ha la forma pk_live_… e viene mostrata una sola volta. Inviala come bearer token:

Header
Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Tieni le chiavi lato server

Una chiave può inviare messaggi da tutti i numeri che copre. Non esporla mai in un browser o in un'app mobile: chiama l'API solo dal tuo backend.

Ambito della chiave

Una chiave vale per tutto l'account oppure è legata a una sola azienda collegata. Scegli l'azienda quando generi la chiave in Chiavi API. Una chiave con ambito ristretto risolve solo quell'azienda: le liste restituiscono solo le sue righe, gli id che appartengono a un'altra rispondono 404 e GET /api/v1/subscription risponde 403; così puoi consegnarla a quell'azienda (o gestire la sua integrazione) senza esporre il resto del tuo account. Le chiavi a livello di account raggiungono tutti i numeri che hai collegato.

Convenzioni

URL di base https://wa.genuka.com/api/v1. Corpi e risposte sono in JSON. Gli endpoint di elenco restituiscono { "data": [...] }. Tutto è automaticamente limitato al tuo account. Gli errori usano i codici di stato HTTP con { "error": "code", "message": "…" }.

Chiama wa.genuka.com in https e senza slash finale: http:// restituisce un 301 verso https, /api/v1/messages/ un 308 verso la forma senza slash, e alcuni client HTTP scartano l'header Authorization quando seguono un reindirizzamento. Nessun altro hostname serve questa API.

Invia uno User-Agent

La nostra CDN rifiuta alcune firme di bot note prima che raggiungano l'API. Quella in cui i nostri integratori incappano più spesso è Python-urllib/3.x, l'header che urllib invia di default: risponde 403 con il corpo error code: 1010, che non proviene da noi e quindi non contiene JSON. Invia uno User-Agent che identifichi la tua integrazione, che è comunque ciò che ti permetterà di ritrovarti nei tuoi log:

request.add_header("User-Agent", "acme-crm/1.4 (+https://example.com)")

requests, curl, axios, node-fetch e i client Go e Java passano senza modifiche.

Aziende (attività collegate)

MetodoEndpointDescrizione
GET/api/v1/companiesElenca le aziende collegate con le loro connessioni
GET/api/v1/companies/{id}Una singola azienda + connessioni + conteggi
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 }
    }
  ]
}

Connessioni (numeri)

MetodoEndpointDescrizione
GET/api/v1/connectionsElenca le connessioni WhatsApp (facoltativi ?companyId=, ?externalRef=)

Una connessione è una WABA + un numero di telefono. Il suo id è ciò che passi quando crei modelli, campagne o invii messaggi.

Modelli

I modelli sono formati di messaggio pre-approvati. Ne serve uno per avviare una conversazione (cioè scrivere a un cliente fuori dalla finestra di 24 ore; vedi Messaggi). Crei un modello qui, Meta lo revisiona, e l'approvazione o il rifiuto arriva automaticamente su GET /templates/{id} (e sui tuoi webhook).

MetodoEndpointDescrizione
GET/api/v1/templatesElenca i modelli (facoltativo ?companyId=)
POST/api/v1/templatesCrea e invia un modello a Meta
GET/api/v1/templates/{id}Un modello + la cronologia dei suoi stati
POST/api/v1/templates/syncRilegge tutti gli stati da Meta
DELETE/api/v1/templates/{id}Elimina su Meta e in locale

Come funziona la creazione

Passi l'array components di Meta così com'è. Questo mantiene l'endpoint leggero e ti permette di costruire qualsiasi modello supportato da Meta: testo, intestazioni media, pulsanti, OTP, ecc. Gli unici campi obbligatori sono connectionId, name e components. category è uno tra MARKETING, UTILITY o AUTHENTICATION (default MARKETING); language è una locale di Meta come en_US o fr (default en).

Riferimento dei componenti

Un modello è una lista ordinata di componenti. Ognuno ha un type:

TipoFormaDescrizione
HEADERformat: TEXT | IMAGE | VIDEO | DOCUMENT | LOCATIONFacoltativo. Uno per modello. Le intestazioni media richiedono un handle di esempio.
BODYtext + exampleObbligatorio (tranne AUTHENTICATION). Contiene le variabili {{1}}… o {{name}}.
FOOTERtextPiè di pagina breve facoltativo. Nessuna variabile.
BUTTONSQUICK_REPLY | URL | PHONE_NUMBER | COPY_CODE | OTPFacoltativo. Fino a 10 pulsanti (le regole variano in base al tipo).

Gli esempi sono obbligatori

Ogni componente con variabili (o un'intestazione media) deve includere un example perché Meta possa revisionarlo: "example": { "body_text": [["Alice", "#1024"]] } per il corpo, "example": { "header_handle": ["<id>"] } per un'intestazione media.

Modello di utilità / marketing (intestazione + corpo + pulsanti)

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…" } }

L'example.header_handle dell'intestazione media è l'handle di caricamento ripristinabile restituito dal caricamento media di Meta; al momento dell'invio fornisci l'immagine reale tramite URL o media id (vedi Messaggi → modello).

Parametri con nome

Preferisci {{name}} al posizionale {{1}}? Imposta parameterFormat: "NAMED" e dai a ogni variabile un parameter_name nell'esempio.

POST /api/v1/templates (con nome)
{
  "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" }
      ] } }
  ]
}

Modello di autenticazione (OTP)

I modelli di autenticazione consegnano codici monouso. Il testo del corpo e del pulsante è fissato da WhatsApp: non scrivi tu il testo. Scegli solo il tipo di pulsante e alcune opzioni. Non sono ammessi intestazioni, media, URL né emoji.

TipoFormaDescrizione
COPY_CODEotp_type: COPY_CODEIl cliente tocca per copiare il codice. Il più semplice, funziona ovunque.
ONE_TAPotp_type: ONE_TAPCompilazione automatica su Android. Richiede package_name + signature_hash.
ZERO_TAPotp_type: ZERO_TAPCodice consegnato in modo silenzioso all'app. Richiede lo stesso collegamento con l'app.
POST /api/v1/templates (autenticazione)
{
  "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" }
    ] }
  ]
}

Per ONE_TAP / ZERO_TAP, aggiungi il collegamento con l'app al pulsante OTP: "autofill_text": "Autofill", "supported_apps": [{ "package_name": "com.example.app", "signature_hash": "K8a..." }].

Inviare il codice

Creare il modello non invia mai nulla. Per consegnare un codice invii un messaggio template con la scorciatoia otp: vedi Messaggi → modello di autenticazione.

Aggiornare gli stati

L'esito di una revisione ti arriva come webhook: è su questa via che devi costruire. Ma un webhook mai consegnato (un endpoint fuori servizio, un'integrazione aggiunta in un secondo momento) lascia il modello in pending qui molto tempo dopo che Meta lo ha approvato, e una campagna che si rifiuta di partire senza un motivo visibile. POST /api/v1/templates/sync rilegge la verità da Meta e la riscrive.

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" }'

Il corpo è facoltativo: senza alcun campo, l'aggiornamento copre tutti gli account WhatsApp che la tua chiave può raggiungere; companyId lo restringe a un cliente e connectionId alla WABA di un solo numero. La risposta nomina ogni account WhatsApp che ha toccato (così un account irraggiungibile viene segnalato invece di essere nascosto) e restituisce le righe appena scritte, il che ti risparmia un GET successivo.

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", "…": "…" }
    ]
  }
}

Un aggiornamento in cui tutti gli account hanno rifiutato risponde 502 meta_rejected con gli stessi results nel corpo; un fallimento parziale resta un 200 che sei tenuto a leggere. GET /api/v1/templates?sync=true esegue lo stesso aggiornamento in linea prima di elencare, e accetta gli stessi filtri companyId / connectionId.

È una via di riparazione, non un ciclo di polling

Ogni chiamata consuma una lettura Meta per account WhatsApp. Eseguila in modo pianificato se vuoi (ogni ora è più che sufficiente), ma mantieni il webhook come il modo normale in cui arrivano gli stati.

Campagne

MetodoEndpointDescrizione
GET/api/v1/campaignsElenca le campagne (facoltativo ?companyId=)
POST/api/v1/campaignsCrea una campagna con destinatari
GET/api/v1/campaigns/{id}Una campagna con le statistiche di consegna
GET/api/v1/campaigns/{id}/recipientsStato per destinatario (?status=, ?limit=)
POST/api/v1/campaigns/{id}/launchInvia a tutti i destinatari in attesa

Creare una campagna

Ogni destinatario ha le proprie variables. La forma semplice è un array posizionale per i parametri del corpo {{1}}, {{2}}…. Per intestazioni media, pulsanti o codici OTP, passa invece un oggetto completo ({ "body": [...], "header": {...}, "buttons": [...] }), con la stessa forma accettata da Messaggi → modello. Il modello deve essere approved prima del lancio. Qui sotto, tpl_124 è un modello con solo corpo; tpl_123 (order_shipped sopra, con intestazione immagine e pulsante URL) richiederebbe la forma completa per ogni 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 } } }

Lancio

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 } }

Limiti

Non facciamo mai pagare un messaggio: Meta fattura direttamente la tua WABA. I destinatari però contano sulla quota di messaggi del tuo piano per il periodo, e l'intera lista viene verificata prima del primo invio, quindi un lancio che non rientrerebbe viene rifiutato subito con 402 plan_limit_messages invece di fermarsi a metà. Vengono consumati solo i destinatari che Meta ha effettivamente accettato. La V1 invia in modo sincrono: mantieni liste di dimensioni moderate; l'invio in coda per le liste grandi è nella roadmap.

Media

Carica un file una volta, invialo tutte le volte che serve. L'archiviazione è privata: niente di ciò che viene salvato qui è raggiungibile da un URL pubblico, e Meta non scarica mai il file; gli consegniamo i byte da server a server al momento dell'invio.

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 }

Due limiti, dichiarati subito

Conservazione: 30 giorni. Ogni file viene eliminato definitivamente 30 giorni dopo il caricamento, e expiresAt indica esattamente quando. È la finestra di Meta stessa: oltre quel termine, la loro copia sparisce comunque. Un invio che fa riferimento a un file scaduto risponde 404 media_not_found.

Archiviazione: in base al piano. 1 GB su Starter, 3 GB su Growth, 5 GB su Scale, su misura su Enterprise, sommando tutti i clienti. Il limite riguarda ciò che è conservato: eliminare un file libera subito lo spazio. Un caricamento che lo supererebbe risponde 402 plan_limit_media prima che venga salvato un solo byte. GET /api/v1/media restituisce il valore attuale in storage.

url è un endpoint di questa API, non un link di condivisione: richiede la tua chiave e rifiuta qualsiasi chiamata fuori dal suo ambito. Byte identici già salvati per questo cliente vengono restituiti così come sono con un 200 e deduplicated: true, invece di essere salvati due volte.

RottaDescrizione
POST /api/v1/mediaCaricamento. Multipart: file (obbligatorio), companyId (obbligatorio con una chiave partner a livello globale), filename (facoltativo).
GET /api/v1/mediaElenco. Filtri kind, companyId, paginazione a cursore, più il valore storage.
GET /api/v1/media/{id}I metadati di un file.
GET /api/v1/media/{id}/contentI byte, autenticati dalla tua chiave.
DELETE /api/v1/media/{id}Elimina subito, senza attendere la scadenza.
POST /api/v1/media/header-handleGenera l'header_handle per l'intestazione di un modello. Multipart: file (obbligatorio), connectionId o companyId (nessuno dei due, con una chiave cliente).

L'intestazione media di un modello: l'header_handle

Creare un modello la cui intestazione è IMAGE, VIDEO o DOCUMENT richiede un example.header_handle, che Meta emette solo tramite la sua Resumable Upload API. Non è la stessa cosa di un assetId: un handle viene consumato una sola volta, alla creazione del modello, e un invio lo rifiuta. Al contrario, un assetId non serve a nulla al momento della creazione.

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 il cliente come si aspetta ogni altra rotta /media (-F "companyId=cmp_1") oppure un numero specifico (-F "connectionId=con_1"); una chiave cliente non ha bisogno di nessuno dei due. L'handle è lo stesso in entrambi i casi: la sessione di caricamento appartiene all'app Meta, non a un numero.

Riporta quell'handle nella definizione del modello:

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"]] } }
  ]
}

Formati accettati: image/jpeg, image/png, video/mp4, video/3gpp, application/pdf. Dimensione massima 4 MB; oltre, la risposta è 413 media_too_large. Non conserviamo nulla dal nostro lato: l'handle è monouso, quindi archiviarlo non servirebbe a niente.

Inviare un file archiviato

Passa assetId ovunque sia previsto un oggetto media, comprese le intestazioni dei modelli. Risolviamo il media_id di Meta per il numero di telefono giusto e lo rinnoviamo man mano che invecchia.

POST /api/v1/messages
{
  "connectionId": "con_1",
  "to": "+237600000000",
  "document": { "assetId": "ast_1", "filename": "briefing.pdf" }
}

id (un media_id di Meta che hai generato tu) e link (un URL pubblico che Meta scarica) sono ancora accettati. assetId è quello da preferire: è l'unico che non espone il file su nessun URL, e l'unico che non ti scade sotto il naso dopo 30 giorni.

Messaggi

MetodoEndpointDescrizione
POST/api/v1/messagesInvia un singolo messaggio di qualsiasi tipo

Un solo endpoint invia tutti i tipi di messaggio WhatsApp. Passa sempre connectionId e to, poi esattamente un campo di contenuto dalla tabella qui sotto. Aggiungi replyTo (il wamid di un messaggio ricevuto) per citare o rispondere a un messaggio.

CampoFinestraDescrizione
templatea pagamentoModello pre-approvato. L'unico modo per avviare una conversazione fuori dalla finestra di 24 h.
textgratis*{ "text": "Hi" } oppure { "text": { "body": "…", "previewUrl": true } }
image / video / audio / document / stickergratis*{ "image": { "assetId": "ast_1" } } (consigliato), { "link": "…" } oppure { "id": "<media-id>" }; caption/filename facoltativi
locationgratis*{ "location": { "latitude": …, "longitude": …, "name": "…", "address": "…" } }
contactsgratis*{ "contacts": [ … oggetti contatto di Meta … ] }
reactiongratis*{ "reaction": { "messageId": "wamid…", "emoji": "👍" } }
buttons / list / ctagratis*Pulsanti di risposta interattivi, un menu a lista o un pulsante URL di call-to-action.
locationRequestgratis*{ "locationRequest": { "body": "Where should we deliver?" } } — mostra un pulsante per inviare la posizione.
callPermissionRequestgratis*{ "callPermissionRequest": { "body": "Can we call you back?" } } — chiede al cliente il permesso di chiamarlo su WhatsApp (body facoltativo). Growth o superiore.
voiceCallgratis*{ "voiceCall": { "body": "Call us on WhatsApp", "displayText": "Call", "ttlMinutes": 120 } } — un pulsante che chiama questo numero su WhatsApp. Growth o superiore.
rawgratis*Via di fuga per tutto il resto (Flows, indirizzo, catalogo): un frammento completo di tipo della Cloud API.

La finestra di 24 ore

Solo gli invii template possono avviare una conversazione. Tutto ciò che è segnato free* è un messaggio di sessione libero: viene consegnato solo se il cliente ha scritto all'azienda nelle ultime 24 ore. Fuori da quella finestra, usa un template. Tutti gli invii restituiscono { "data": { "messageId": "wamid…" } }.

Un 200 significa che Meta ha accettato il messaggio, non che sia stato consegnato. Lo stato finale (sent → delivered → read, oppure failed) arriva in modo asincrono sui tuoi webhook. In to, includi sempre il + e il prefisso internazionale (per esempio +237690000001): ometterlo può instradare male il messaggio. I media passati tramite link vengono messi in cache da Meta per ~10 minuti, quindi riusa lo stesso URL per la stessa risorsa (o aggiungi una query string univoca per invalidare la cache).

Messaggio con modello

Il caso semplice è un modello le cui uniche variabili stanno nel corpo, come order_update qui sotto (nessuna intestazione media, nessun pulsante dinamico). variables è un array posizionale; puoi anche usare bodyNamed per i modelli con nome, header per un'intestazione media o di testo, e buttons per i parametri dei pulsanti dinamici. Un invio deve compilare tutti i parametri dichiarati dal modello: order_shipped, sopra, ha un'intestazione immagine e un pulsante URL dinamico, quindi richiede la seconda forma; con le sole variabili del corpo, Meta lo rifiuta.

POST /api/v1/messages (modello, semplice)
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 (modello, intestazione + corpo + pulsante)
{
  "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" }
    ]
  }
}

Il buttons[].text compila la parte dinamica di un pulsante URL (il {{1}} in https://example.com/track/{{1}}). Per una risposta rapida usa { "type": "quick_reply", "payload": "…" }; per un codice coupon usa { "type": "copy_code", "code": "SAVE20" }. Parametri del corpo con nome: "bodyNamed": { "customer_name": "Alice" }.

Modello di autenticazione

Passa il codice una sola volta con la scorciatoia otp: compiliamo noi sia il corpo sia il pulsante OTP (il formato richiesto da Meta).

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

Messaggi di sessione liberi

testo
{ "connectionId": "con_1", "to": "+237690000001", "text": "Thanks, talk soon!" }
immagine (con didascalia)
{ "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" } }
pulsanti di risposta interattivi
{
  "connectionId": "con_1",
  "to": "+237690000001",
  "buttons": {
    "body": "Confirm your order?",
    "footer": "Acme Coffee",
    "buttons": [
      { "id": "yes", "title": "Confirm" },
      { "id": "no",  "title": "Cancel" }
    ]
  }
}
lista interattiva
{
  "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" }
      ] }
    ]
  }
}
pulsante URL di call-to-action
{
  "connectionId": "con_1",
  "to": "+237690000001",
  "cta": { "body": "Your receipt is ready.", "displayText": "View receipt", "url": "https://example.com/r/1024" }
}
risposta nel thread + reazione
{ "connectionId": "con_1", "to": "+237690000001", "replyTo": "wamid.HBg…", "text": "On its way!" }

{ "connectionId": "con_1", "to": "+237690000001",
  "reaction": { "messageId": "wamid.HBg…", "emoji": "👍" } }

Chiamate WhatsApp

Piano Growth o superiore. Il tuo stack (un agente vocale, un softphone WebRTC) effettua e risponde alle chiamate; Genuka WA inoltra la segnalazione a Meta e ti restituisce i webhook call.*. L'audio non passa mai da noi: l'SDP descrive un percorso tra Meta e il tuo stack. Vedi la guida Collegare un agente vocale per i flussi dall'inizio alla fine.

MetodoEndpointDescrizione
GET/api/v1/numbers/{id}/callingImpostazioni delle chiamate di un numero: status, callIconVisibility, callHours, callbackPermissionStatus, sipEnabled
PATCH/api/v1/numbers/{id}/callingLe modifica. Un vero patch: il resto viene mantenuto.
POST/api/v1/callsUn'azione di chiamata, inoltrata a Meta: connect, pre_accept, accept, reject, terminate
GET/api/v1/calls/permissions?waId=…&connectionId=…Se puoi chiamare questo utente adesso (canCall) e se puoi chiederglielo (canRequestPermission)
PATCH /api/v1/numbers/con_1/calling — attivare le chiamate, in orario d'ufficio
{
  "status": "ENABLED",
  "callHours": {
    "status": "ENABLED",
    "timezoneId": "Africa/Douala",
    "weeklyOperatingHours": [{ "dayOfWeek": "MONDAY", "openTime": "0800", "closeTime": "1800" }],
    "holidaySchedule": []
  }
}
POST /api/v1/calls — rispondere a una chiamata in arrivo
{ "action": "accept", "callId": "wacid.HBgL…", "sdp": "v=0\r\no=- 8236… (la tua risposta SDP)" }
POST /api/v1/calls — chiamare un cliente che ha dato il permesso
{ "connectionId": "con_1", "action": "connect", "to": "+237690000001", "sdp": "v=0\r\n… (la tua offerta SDP)" }
  • sdp è solo l'SDP: il suo tipo deriva dall'azione (offerta su connect, risposta su pre_accept / accept). connect restituisce { "data": { "action": "connect", "callId": "wacid…" } }.
  • connectionId può essere omesso quando callId indica una chiamata che Genuka WA ha già visto (il webhook di una chiamata in arrivo, o un connect effettuato qui).
  • Una chiamata in arrivo squilla per circa 30 secondi: pre_accept deve partire entro quella finestra.
StatoerrorQuando
403plan_feature_unavailableIl piano non include le chiamate (Starter).
409calling_unavailable_coexistenceIl numero è condiviso con l'app WhatsApp Business: WhatsApp non consente chiamate tramite API su di esso.
409calling_sip_configuredIl numero segnala le chiamate via SIP, configurato fuori da Genuka WA (solo PATCH).
409number_offboardedIl numero ha lasciato la piattaforma: ricollegalo.
404call_not_foundcallId senza connectionId, e nessuna chiamata nota con quell'id: passa il connectionId.
400invalid_call_action / invalid_calling_settingsTutti i problemi del corpo, in una volta sola, in issues.
422meta_errorMeta ha rifiutato: numero non idoneo, nessun permesso di chiamata, paese escluso… con le parole di Meta.

Webhook: call.connect (con data.session.sdp), call.status_changed, call.terminated e call.permission_replied (vedi Webhook).

Abbonamento

MetodoEndpointDescrizione
GET/api/v1/subscriptionPiano attuale, limiti e utilizzo
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 }
}

Errori

Esempi
401 { "error": "missing_bearer_token" }      // nessun header Authorization
401 { "error": "invalid_token" }             // chiave sconosciuta / revocata, o account inattivo
403 { "error": "account_deactivated", "message": "Deactivated Account" }
                                             // quell'azienda è sospesa: la sua chiave smette
                                             // di funzionare, e ogni richiesta che la nomina
                                             // viene rifiutata, anche con una chiave di account
400 { "error": "missing_fields", "message": "…" }
400 { "error": "missing_content", "message": "…" }  // nessun campo di contenuto in un invio
400 { "error": "invalid_media", "message": "…" }    // media senza assetId, id né link
402 { "error": "plan_limit_media", "message": "…" } // raggiunto il limite di archiviazione del piano
404 { "error": "media_not_found", "message": "…" }  // assetId sconosciuto, o oltre i 30 giorni
402 { "error": "plan_limit_numbers" }        // tutti i numeri pagati dal piano sono in uso
402 { "error": "plan_limit_messages" }       // la quota di messaggi del periodo è esaurita
402 { "error": "subscription_past_due" }     // prova o periodo pagato scaduto senza rinnovo
404 { "error": "connection_not_found" }
404 { "error": "template_not_found" }
409 { "error": "template_exists" }
413 { "error": "media_too_large", "message": "…" } // intestazione del modello oltre 4 MB
422 { "error": "meta_rejected", "message": "…", "meta": { … } }
                                             // Meta ha letto il payload e l'ha rifiutato
502 { "error": "meta_rejected", "message": "…" }   // Graph irraggiungibile o in errore

Ciò che Meta ha rifiutato restituisce 422, non 502

Quando Graph legge un payload e lo rifiuta (un modello malformato, una variabile senza esempio, un numero non predisposto), la risposta è un 422, e il suo corpo contiene un oggetto meta con il codice di errore di Meta, il suo traceId e la sua classe:

422 — rifiutato da 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 è ciò che chiede il supporto di Meta: citalo testualmente.

Un 502 è riservato a ciò che la parola descrive: Graph irraggiungibile, o Graph stesso in errore. Restituire un payload rifiutato come 502 lo rendeva impossibile da diagnosticare: la nostra CDN risponde ai 5xx dell'origine con la propria pagina di errore, sostituendo quel corpo JSON con l'unica riga error code: 502. Il motivo del rifiuto non ti arrivava mai. I corpi 4xx passano senza modifiche.

Log delle richieste

Ogni risposta contiene un header x-request-id. Lo stesso id identifica la chiamata nella tua dashboard, in Log, dove ogni richiesta è conservata con il suo stato, la sua durata, il suo corpo e, quando è fallita, la risposta che abbiamo restituito. Le consegne dei webhook sono elencate accanto, con il loro payload firmato esatto e un pulsante per reinviarle.

Quanto indietro arriva il log dipende dal tuo piano: 7 giorni su Starter, 30 su Growth, 90 su Scale.

Campi oscurati

I corpi vengono conservati per rendere riproducibile un errore, tranne tutto ciò che somiglia a una credenziale: i valori password, token, secret e api_key vengono sostituiti prima che la riga venga scritta.

In questa pagina