Genuka WA docs

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…UsaCosa ottiene
Agisca sul tuo account: inviare un messaggio, creare un modello, lanciare una campagna, controllare lo stato di un numeroIl server MCP @genuka/whatsapp-mcp17 strumenti, ognuno associato a un endpoint /api/v1
Scriva nel tuo repository codice che chiama Genuka WA/llms.txt, pagine .mdx, /openapi.json, /pricing.mdLa 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-mcp

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

.mcp.json
{
  "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?

StrumentoCosa faInvia o modifica qualcosa?
list_numbersNumeri collegati e il loro statoNo
get_number_healthValutazione di qualità in tempo reale, livello del limite di messaggi, throughput, avvisiNo
send_text_messageTesto libero, dentro la finestra di 24 oreInvia un messaggio
send_template_messageUn modello approvato: variabili, header, pulsanti, codice monousoInvia un messaggio
send_media_messageImmagine, video, audio, documento o stickerInvia un messaggio
list_templates / get_templateI modelli, il loro stato e l'esito della revisione di MetaNo
create_templateSottopone un modello alla revisione di MetaSì
list_webhooks / create_webhookEndpoint webhook; la creazione restituisce il segreto di firma una sola voltaLa creazione invia all'URL gli eventi del tuo account, messaggi dei clienti compresi
test_webhookEventi di esempio firmati inviati al tuo endpointChiama il tuo endpoint
list_campaigns / get_campaign / list_campaign_recipientsCampagne e consegna per destinatarioNo
create_campaignUna bozza: un modello, un numero, un elenco di destinatariSì, non invia nulla
launch_campaignInvia la campagna a tutti i destinatari in attesaInvia messaggi
get_subscriptionPiano, 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_webhook inoltra 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:

URLContenutoQuando usarlo
/llms.txtIndice di tutte le pagine (inglese, francese, spagnolo, italiano, SDK), una riga ciascuna, secondo la proposta llms.txtIl primo file da dare a un agente
/llms-full.txtIl Markdown di tutte le pagine in un solo fileCaricare tutta la documentazione nel contesto in una volta
Qualsiasi pagina + .mdxUna pagina in Markdown, ad es. /it/docs/messages.mdxIndicare esattamente la pagina che conta
/openapi.jsonDescrizione OpenAPI 3.1 di /api/v1Generare un client tipizzato, o far verificare all'agente i nomi dei campi
/pricing.mdPiani, prezzi e limiti in Markdown, generati dal catalogo di fatturazioneRispondere a "quanto mi costerà?"
curl https://wa.genuka.com/llms.txt
curl https://wa.genuka.com/it/docs/webhooks.mdx

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

AGENTS.md
## 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

In questa pagina