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:
Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxTieni 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)
| Metodo | Endpoint | Descrizione |
|---|---|---|
GET | /api/v1/companies | Elenca le aziende collegate con le loro connessioni |
GET | /api/v1/companies/{id} | Una singola azienda + connessioni + conteggi |
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)
| Metodo | Endpoint | Descrizione |
|---|---|---|
GET | /api/v1/connections | Elenca 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).
| Metodo | Endpoint | Descrizione |
|---|---|---|
GET | /api/v1/templates | Elenca i modelli (facoltativo ?companyId=) |
POST | /api/v1/templates | Crea e invia un modello a Meta |
GET | /api/v1/templates/{id} | Un modello + la cronologia dei suoi stati |
POST | /api/v1/templates/sync | Rilegge 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:
| Tipo | Forma | Descrizione |
|---|---|---|
HEADER | format: TEXT | IMAGE | VIDEO | DOCUMENT | LOCATION | Facoltativo. Uno per modello. Le intestazioni media richiedono un handle di esempio. |
BODY | text + example | Obbligatorio (tranne AUTHENTICATION). Contiene le variabili {{1}}… o {{name}}. |
FOOTER | text | Piè di pagina breve facoltativo. Nessuna variabile. |
BUTTONS | QUICK_REPLY | URL | PHONE_NUMBER | COPY_CODE | OTP | Facoltativo. 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)
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.
{
"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.
| Tipo | Forma | Descrizione |
|---|---|---|
COPY_CODE | otp_type: COPY_CODE | Il cliente tocca per copiare il codice. Il più semplice, funziona ovunque. |
ONE_TAP | otp_type: ONE_TAP | Compilazione automatica su Android. Richiede package_name + signature_hash. |
ZERO_TAP | otp_type: ZERO_TAP | Codice consegnato in modo silenzioso all'app. Richiede lo stesso collegamento con l'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" }
] }
]
}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.
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.
{
"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
| Metodo | Endpoint | Descrizione |
|---|---|---|
GET | /api/v1/campaigns | Elenca le campagne (facoltativo ?companyId=) |
POST | /api/v1/campaigns | Crea una campagna con destinatari |
GET | /api/v1/campaigns/{id} | Una campagna con le statistiche di consegna |
GET | /api/v1/campaigns/{id}/recipients | Stato per destinatario (?status=, ?limit=) |
POST | /api/v1/campaigns/{id}/launch | Invia 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.
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
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.
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.
| Rotta | Descrizione |
|---|---|
POST /api/v1/media | Caricamento. Multipart: file (obbligatorio), companyId (obbligatorio con una chiave partner a livello globale), filename (facoltativo). |
GET /api/v1/media | Elenco. 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}/content | I byte, autenticati dalla tua chiave. |
DELETE /api/v1/media/{id} | Elimina subito, senza attendere la scadenza. |
POST /api/v1/media/header-handle | Genera 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.
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:
{
"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.
{
"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
| Metodo | Endpoint | Descrizione |
|---|---|---|
POST | /api/v1/messages | Invia 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.
| Campo | Finestra | Descrizione |
|---|---|---|
template | a pagamento | Modello pre-approvato. L'unico modo per avviare una conversazione fuori dalla finestra di 24 h. |
text | gratis* | { "text": "Hi" } oppure { "text": { "body": "…", "previewUrl": true } } |
image / video / audio / document / sticker | gratis* | { "image": { "assetId": "ast_1" } } (consigliato), { "link": "…" } oppure { "id": "<media-id>" }; caption/filename facoltativi |
location | gratis* | { "location": { "latitude": …, "longitude": …, "name": "…", "address": "…" } } |
contacts | gratis* | { "contacts": [ … oggetti contatto di Meta … ] } |
reaction | gratis* | { "reaction": { "messageId": "wamid…", "emoji": "👍" } } |
buttons / list / cta | gratis* | Pulsanti di risposta interattivi, un menu a lista o un pulsante URL di call-to-action. |
locationRequest | gratis* | { "locationRequest": { "body": "Where should we deliver?" } } — mostra un pulsante per inviare la posizione. |
callPermissionRequest | gratis* | { "callPermissionRequest": { "body": "Can we call you back?" } } — chiede al cliente il permesso di chiamarlo su WhatsApp (body facoltativo). Growth o superiore. |
voiceCall | gratis* | { "voiceCall": { "body": "Call us on WhatsApp", "displayText": "Call", "ttlMinutes": 120 } } — un pulsante che chiama questo numero su WhatsApp. Growth o superiore. |
raw | gratis* | 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.
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" }
]
}
}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).
{
"connectionId": "con_1",
"to": "+237690000001",
"template": { "name": "verification_code", "language": "en_US", "otp": "472913" }
}Messaggi di sessione liberi
{ "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": "👍" } }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.
| Metodo | Endpoint | Descrizione |
|---|---|---|
GET | /api/v1/numbers/{id}/calling | Impostazioni delle chiamate di un numero: status, callIconVisibility, callHours, callbackPermissionStatus, sipEnabled |
PATCH | /api/v1/numbers/{id}/calling | Le modifica. Un vero patch: il resto viene mantenuto. |
POST | /api/v1/calls | Un'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) |
{
"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… (la tua risposta SDP)" }{ "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 suconnect, risposta supre_accept/accept).connectrestituisce{ "data": { "action": "connect", "callId": "wacid…" } }.connectionIdpuò essere omesso quandocallIdindica una chiamata che Genuka WA ha già visto (il webhook di una chiamata in arrivo, o unconnecteffettuato qui).- Una chiamata in arrivo squilla per circa 30 secondi:
pre_acceptdeve partire entro quella finestra.
| Stato | error | Quando |
|---|---|---|
403 | plan_feature_unavailable | Il piano non include le chiamate (Starter). |
409 | calling_unavailable_coexistence | Il numero è condiviso con l'app WhatsApp Business: WhatsApp non consente chiamate tramite API su di esso. |
409 | calling_sip_configured | Il numero segnala le chiamate via SIP, configurato fuori da Genuka WA (solo PATCH). |
409 | number_offboarded | Il numero ha lasciato la piattaforma: ricollegalo. |
404 | call_not_found | callId senza connectionId, e nessuna chiamata nota con quell'id: passa il connectionId. |
400 | invalid_call_action / invalid_calling_settings | Tutti i problemi del corpo, in una volta sola, in issues. |
422 | meta_error | Meta 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
| Metodo | Endpoint | Descrizione |
|---|---|---|
GET | /api/v1/subscription | Piano attuale, limiti e utilizzo |
{
"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
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 erroreCiò 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:
{
"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.
Collegare un agente vocale alle chiamate WhatsApp
Ricevi ed effettua chiamate WhatsApp con il tuo agente vocale o il tuo stack WebRTC: attivare le chiamate, webhook call.*, azioni di chiamata con SDP, permessi.
Libreria TypeScript
@genuka/whatsapp — builder tipizzati, validazione e normalizzazione degli eventi.