API WhatsApp per agenti IA: server MCP, llms.txt
Collega Claude, Cursor o VS Code all'API WhatsApp Business con il server MCP di Genuka WA, più llms.txt, documentazione in Markdown e una specifica OpenAPI.
Per far lavorare un agente IA con WhatsApp tramite Genuka WA, aggiungi il server MCP
@genuka/whatsapp-mcp al tuo client con una chiave API: Claude, Cursor o VS Code possono allora
elencare i tuoi numeri, inviare modelli e lanciare campagne. Se invece vuoi che un assistente scriva
il codice di integrazione, indicagli /llms.txt, le pagine .mdx e /openapi.json.
Ultimo aggiornamento: 8 ottobre 2026
Cosa può fare un agente IA con Genuka WA?
Genuka WA è un'API REST per la WhatsApp Business Platform ufficiale (la Cloud API di Meta). Genuka è un Meta Tech Provider: colleghi il tuo numero WhatsApp Business tramite l'Embedded Signup di Meta, poi invii notifiche, codici monouso e campagne via HTTP. Un agente può usarla in due modi, e la maggior parte dei team finisce per usarli entrambi:
| Vuoi che l'agente… | Usa | Cosa ottiene |
|---|---|---|
| Agisca sul tuo account: inviare un messaggio, creare un modello, lanciare una campagna, controllare lo stato di un numero | Il server MCP @genuka/whatsapp-mcp | 17 strumenti, ognuno associato a un endpoint /api/v1 |
| Scriva nel tuo repository codice che chiama Genuka WA | /llms.txt, pagine .mdx, /openapi.json, /pricing.md | La documentazione e il contratto dell'API, in formati che un modello legge senza browser |
MCP è lo standard aperto che le applicazioni IA usano per collegarsi a strumenti esterni; Claude, ChatGPT, VS Code e Cursor lo supportano tutti.
Come installo il server MCP di Genuka WA?
Crea una chiave API
Nella dashboard, apri la pagina Chiavi API e crea una
chiave (pk_live_…). Viene mostrata una sola volta. Se l'agente lavora solo per una delle tue
aziende, scegli quell'azienda quando crei la chiave: l'agente non potrà vedere né toccare le altre
(vedi Autenticazione).
Ti serve Node.js 20 o successivo: il client avvia il server con npx.
Aggiungi il server al tuo client
claude mcp add --env GENUKA_WA_API_KEY=pk_live_xxx --transport stdio genuka-wa -- npx -y @genuka/whatsapp-mcpPer condividerlo con il tuo team senza fare commit della chiave, metti questo .mcp.json nella
radice del repository; Claude Code espande ${GENUKA_WA_API_KEY} dall'ambiente di ogni
sviluppatore:
{
"mcpServers": {
"genuka-wa": {
"command": "npx",
"args": ["-y", "@genuka/whatsapp-mcp"],
"env": { "GENUKA_WA_API_KEY": "${GENUKA_WA_API_KEY}" }
}
}
}GENUKA_WA_BASE_URL è facoltativo e vale per impostazione predefinita https://wa.genuka.com.
Verifica la connessione
In Claude Code, claude mcp list o /mcp mostra il server come connesso. Poi chiedi all'agente
"Elenca i miei numeri WhatsApp": chiama list_numbers, che restituisce l'id di ogni numero (il
connectionId che serve a tutti gli altri strumenti), la sua azienda e la sua valutazione di
qualità. Se la chiave manca o è sbagliata, lo strumento risponde con il motivo invece di fallire in
silenzio.
Quali strumenti espone il server MCP?
| Strumento | Cosa fa | Invia o modifica qualcosa? |
|---|---|---|
list_numbers | Numeri collegati e il loro stato | No |
get_number_health | Valutazione di qualità in tempo reale, livello del limite di messaggi, throughput, avvisi | No |
send_text_message | Testo libero, dentro la finestra di 24 ore | Invia un messaggio |
send_template_message | Un modello approvato: variabili, header, pulsanti, codice monouso | Invia un messaggio |
send_media_message | Immagine, video, audio, documento o sticker | Invia un messaggio |
list_templates / get_template | I modelli, il loro stato e l'esito della revisione di Meta | No |
create_template | Sottopone un modello alla revisione di Meta | Sì |
list_webhooks / create_webhook | Endpoint webhook; la creazione restituisce il segreto di firma una sola volta | La creazione invia all'URL gli eventi del tuo account, messaggi dei clienti compresi |
test_webhook | Eventi di esempio firmati inviati al tuo endpoint | Chiama il tuo endpoint |
list_campaigns / get_campaign / list_campaign_recipients | Campagne e consegna per destinatario | No |
create_campaign | Una bozza: un modello, un numero, un elenco di destinatari | Sì, non invia nulla |
launch_campaign | Invia la campagna a tutti i destinatari in attesa | Invia messaggi |
get_subscription | Piano, utilizzo e limiti (solo chiave valida per tutto l'account) | No |
Ogni strumento dichiara gli hint MCP readOnlyHint, destructiveHint e idempotentHint, così il
tuo client può approvare le letture in automatico e chiederti conferma prima di qualunque invio. Gli
errori tornano all'agente con il codice dell'API (plan_limit_messages, connection_not_found,
meta_rejected…), il codice e il trace id di Meta quando ci sono, e cosa fare dopo.
Il server legge; non riceve. Le risposte dei clienti e gli stati di consegna arrivano sui tuoi webhook: vedi Ricevere risposte e stati WhatsApp via webhook.
Cosa devo controllare prima di lasciare che un agente invii messaggi?
- È un messaggio vero, a una persona vera. Un invio dall'agente parte dal tuo numero, come uno
dal tuo backend. Tieni attiva la richiesta di conferma del client per gli strumenti che inviano, e
fatti mostrare la campagna prima di
launch_campaign. - Un webhook è un'uscita di dati.
create_webhookinoltra al suo URL ogni evento a cui è iscritto, compresi i numeri di telefono e i messaggi dei tuoi clienti, finché l'endpoint resta attivo. Tieni attiva la richiesta di conferma anche per questo, e verifica che l'URL sia uno che hai dato tu all'agente, non uno che ha letto in una pagina web o in un file. Il server dice la stessa cosa all'agente. - La finestra di 24 ore. Quando un cliente ti scrive, si apre una finestra del servizio clienti
di 24 ore; una volta chiusa, si possono inviare solo modelli pre-approvati
(Meta).
Quando Genuka WA non può confermare che la finestra sia aperta, il risultato dell'invio contiene un
warning, e il server lo mette in cima a ciò che l'agente legge, così arriva fino a te. - Quanto costa. Ogni messaggio conta sulla quota del tuo piano per il periodo di fatturazione
(piani,
/pricing.md). Meta addebita un messaggio modello quando viene consegnato, e i messaggi non modello sono gratuiti (Meta); Meta fattura il tuo WhatsApp Business Account, senza ricarichi da parte di Genuka. - La chiave. Tienila fuori da git con le variabili
${…}mostrate sopra, dai all'agente una chiave limitata a un'azienda quando basta, e revocala dalla dashboard quando hai finito.
Come do al mio assistente di programmazione la documentazione di Genuka WA?
Quando il compito dell'agente è scrivere la tua integrazione, gli serve il contratto più degli strumenti. Tutto ciò che segue è pubblico, non richiede chiave API e resta sincronizzato con la documentazione pubblicata:
| URL | Contenuto | Quando usarlo |
|---|---|---|
/llms.txt | Indice di tutte le pagine (inglese, francese, spagnolo, italiano, SDK), una riga ciascuna, secondo la proposta llms.txt | Il primo file da dare a un agente |
/llms-full.txt | Il Markdown di tutte le pagine in un solo file | Caricare tutta la documentazione nel contesto in una volta |
Qualsiasi pagina + .mdx | Una pagina in Markdown, ad es. /it/docs/messages.mdx | Indicare esattamente la pagina che conta |
/openapi.json | Descrizione OpenAPI 3.1 di /api/v1 | Generare un client tipizzato, o far verificare all'agente i nomi dei campi |
/pricing.md | Piani, prezzi e limiti in Markdown, generati dal catalogo di fatturazione | Rispondere a "quanto mi costerà?" |
curl https://wa.genuka.com/llms.txt
curl https://wa.genuka.com/it/docs/webhooks.mdxQuale prompt devo dare all'assistente?
Indica il prodotto, il framework e l'evento, e lascia che legga la documentazione. Per esempio:
Aggiungi alla mia app Next.js le notifiche WhatsApp di ordine spedito con Genuka WA. Leggi prima https://wa.genuka.com/llms.txt.
Un buon risultato ha tre parti: un modello UTILITY come order_shipped, inviato una volta e
approvato da Meta; codice lato server che chiama POST /api/v1/messages quando l'ordine viene
spedito; e una route webhook che verifica X-Genuka-Signature prima di fidarsi di uno stato. Con il
modello order_shipped della guida alle notifiche d'ordine
(tre variabili nel corpo e un pulsante con link di tracciamento), la chiamata è questa. I valori
devono corrispondere uno a uno alle variabili del modello, altrimenti Meta rifiuta il messaggio
(errore 132000):
curl -X POST https://wa.genuka.com/api/v1/messages \
-H "Authorization: Bearer $GENUKA_WA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"connectionId": "con_1",
"to": "+237690000001",
"template": {
"name": "order_shipped",
"language": "en",
"body": ["Awa", "ORD-1042", "DHL"],
"buttons": [{ "type": "url", "text": "ORD-1042" }]
}
}'Il percorso completo (modello, idempotenza, tracciamento della consegna) è in Notifiche d'ordine WhatsApp dal tuo backend.
Cosa devo mettere in AGENTS.md?
AGENTS.md, CLAUDE.md o .cursor/rules vengono letti dall'assistente prima di ogni compito.
Queste righe gli evitano gli errori che vediamo più spesso nelle integrazioni WhatsApp. Sono in
inglese, la lingua che questi file condividono di solito all'interno di un team:
## WhatsApp (Genuka WA)
- WhatsApp goes through the Genuka WA REST API: base URL https://wa.genuka.com/api/v1,
header `Authorization: Bearer $GENUKA_WA_API_KEY`. Server-side only: never ship the key to a
browser or a mobile app. We do not call Meta's Graph API directly.
- Docs for agents: https://wa.genuka.com/llms.txt; append `.mdx` to any docs URL for Markdown;
API contract: https://wa.genuka.com/openapi.json.
- `connectionId` is the `id` returned by `GET /api/v1/connections`. It lives in config
(`GENUKA_WA_CONNECTION_ID`), never hard-coded.
- Phone numbers are E.164: `+237690000001`.
- Business-initiated messages (order updates, reminders, codes) are templates. Free-form `text`
is only delivered within 24 hours of the customer's last message.
- Templates are created once (`POST /api/v1/templates`) and reviewed by Meta; only `approved`
ones can be sent. Use the template's exact `language`.
- A 200 from `POST /api/v1/messages` means Meta accepted the message, not that it was delivered.
Delivery and replies arrive on webhooks; verify `X-Genuka-Signature` on the raw body first.
- Errors are `{ "error": "code", "message": "…" }`. Never retry `plan_limit_messages`; when the
body has `meta.retryable: false`, change the request instead of retrying it.FAQ
Il server MCP invia messaggi WhatsApp veri?
Sì. send_text_message, send_template_message, send_media_message e launch_campaign inviano
dal tuo numero collegato a destinatari reali, e contano sulla quota del tuo piano. Le letture
(list_*, get_*) non modificano nulla.
Il server MCP è gratuito?
Il pacchetto @genuka/whatsapp-mcp ha licenza MIT ed è gratuito. Usa il tuo account Genuka WA,
fatturato come abbonamento per numero WhatsApp (piani). Meta fattura i messaggi
modello consegnati al tuo WhatsApp Business Account, senza ricarichi da parte di Genuka.
Con quali client IA funziona?
Qualsiasi client MCP in grado di avviare un server locale (stdio): Claude Code, Claude Desktop, Cursor, VS Code e Windsurf sono trattati sopra. Il server richiede Node.js 20 o successivo.
L'agente può leggere le risposte dei miei clienti?
Non tramite il server MCP: non ha strumenti per i messaggi in arrivo. Le risposte e gli stati di
consegna vengono inviati al tuo endpoint webhook, che l'agente può creare con create_webhook (a un
URL che gli dai tu) e verificare con test_webhook.
Come limito ciò a cui l'agente può accedere?
Dagli una chiave limitata a un'azienda. Gli elenchi restituiscono allora solo le righe di
quell'azienda, qualsiasi altro id risponde 404 e get_subscription viene rifiutato: vedi
Autenticazione.
Fonti
- Meta — Send messages (customer service window)
- Meta — Pricing on the WhatsApp Business Platform
- Model Context Protocol — What is MCP?
- The /llms.txt proposal
- Claude Code — Connect Claude Code to tools via MCP
- MCP — Connect to local MCP servers (Claude Desktop)
- Cursor — Model Context Protocol
- VS Code — MCP configuration reference
- Devin Desktop (formerly Windsurf) — MCP
- Devin Desktop FAQ — Windsurf becomes Devin Desktop
Quanto costa un messaggio WhatsApp in Africa? (2026)
Quanto costa un messaggio WhatsApp Business in Africa nel 2026: le tariffe di Meta per paese e categoria, in USD, EUR e franchi CFA, con un esempio svolto.
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.