# API WhatsApp per agenti IA: server MCP, llms.txt

URL: https://wa.genuka.com/it/docs/guides/ai-agents
Language: Italian

> 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](https://modelcontextprotocol.io/docs/getting-started/intro) è 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?

1. ### Crea una chiave API

   Nella dashboard, apri la [pagina Chiavi API](https://wa.genuka.com/dashboard/settings) 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](https://wa.genuka.com/it/docs/authentication)).

   Ti serve Node.js 20 o successivo: il client avvia il server con `npx`.

2. ### Aggiungi il server al tuo client

   **Claude Code**

   ```bash
   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:

   ```json title=".mcp.json"
   {
     "mcpServers": {
       "genuka-wa": {
         "command": "npx",
         "args": ["-y", "@genuka/whatsapp-mcp"],
         "env": { "GENUKA_WA_API_KEY": "${GENUKA_WA_API_KEY}" }
       }
     }
   }
   ```

   **Claude Desktop**

   **Settings → Developer → Edit Config** apre `claude_desktop_config.json`
   (`~/Library/Application Support/Claude/` su macOS, `%APPDATA%\Claude\` su Windows). Aggiungi il
   server, salva, poi chiudi e riavvia Claude Desktop.

   ```json title="claude_desktop_config.json"
   {
     "mcpServers": {
       "genuka-wa": {
         "command": "npx",
         "args": ["-y", "@genuka/whatsapp-mcp"],
         "env": { "GENUKA_WA_API_KEY": "pk_live_xxx" }
       }
     }
   }
   ```

   **Cursor**

   In `~/.cursor/mcp.json` (tutti i progetti) o `.cursor/mcp.json` (questo progetto). `${env:…}`
   legge la chiave dal tuo ambiente:

   ```json title=".cursor/mcp.json"
   {
     "mcpServers": {
       "genuka-wa": {
         "command": "npx",
         "args": ["-y", "@genuka/whatsapp-mcp"],
         "env": { "GENUKA_WA_API_KEY": "${env:GENUKA_WA_API_KEY}" }
       }
     }
   }
   ```

   **VS Code**

   In `.vscode/mcp.json`, oppure con **MCP: Open User Configuration** per tutti i workspace. VS Code
   chiede la chiave una volta e non la salva nel file:

   ```json title=".vscode/mcp.json"
   {
     "inputs": [
       { "type": "promptString", "id": "genuka-wa-api-key", "description": "Genuka WA API key", "password": true }
     ],
     "servers": {
       "genuka-wa": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "@genuka/whatsapp-mcp"],
         "env": { "GENUKA_WA_API_KEY": "${input:genuka-wa-api-key}" }
       }
     }
   }
   ```

   **Windsurf**

   Windsurf si chiama Devin Desktop dal 2 giugno 2026. Nel pannello Cascade, apri il menu `…`, poi
   **Open MCP config file**:

   ```json title="mcp_config.json"
   {
     "mcpServers": {
       "genuka-wa": {
         "command": "npx",
         "args": ["-y", "@genuka/whatsapp-mcp"],
         "env": { "GENUKA_WA_API_KEY": "pk_live_xxx" }
       }
     }
   }
   ```

   `GENUKA_WA_BASE_URL` è facoltativo e vale per impostazione predefinita `https://wa.genuka.com`.

3. ### 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](https://wa.genuka.com/it/docs/guides/receive-messages-webhooks).

## 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages)).
  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](https://wa.genuka.com/it#pricing), [`/pricing.md`](https://wa.genuka.com/pricing.md)). Meta addebita un messaggio modello quando
  viene consegnato, e i messaggi non modello sono gratuiti
  ([Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)); 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`](https://wa.genuka.com/llms.txt)           | Indice di tutte le pagine (inglese, francese, spagnolo, italiano, SDK), una riga ciascuna, secondo la proposta [llms.txt](https://llmstxt.org/) | Il primo file da dare a un agente                                          |
| [`/llms-full.txt`](https://wa.genuka.com/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`](https://wa.genuka.com/it/docs/messages.mdx)                                                                 | Indicare esattamente la pagina che conta                                   |
| [`/openapi.json`](https://wa.genuka.com/openapi.json)   | Descrizione OpenAPI 3.1 di `/api/v1`                                                                                                            | Generare un client tipizzato, o far verificare all'agente i nomi dei campi |
| [`/pricing.md`](https://wa.genuka.com/pricing.md)       | Piani, prezzi e limiti in Markdown, generati dal catalogo di fatturazione                                                                       | Rispondere a "quanto mi costerà?"                                          |

```bash
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](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](https://wa.genuka.com/it/docs/guides/order-notifications)
(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](https://wa.genuka.com/it/docs/errors/132000)):

**curl**

```bash
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" }]
    }
  }'
```

**Node.js**

```ts title="lib/whatsapp.ts"
export async function notifyOrderShipped(phone: string, firstName: string, orderNumber: string, carrier: string) {
  const response = await fetch("https://wa.genuka.com/api/v1/messages", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.GENUKA_WA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      connectionId: process.env.GENUKA_WA_CONNECTION_ID,
      to: phone, // E.164: "+237690000001"
      template: {
        name: "order_shipped",
        language: "en",
        body: [firstName, orderNumber, carrier], // {{1}}, {{2}}, {{3}} in ordine
        buttons: [{ type: "url", text: orderNumber }], // completa il link di tracciamento
      },
    }),
  });
  const result = await response.json();
  if (!response.ok) throw new Error(`${result.error}: ${result.message ?? ""}`);
  return result.data.messageId as string; // accettato da Meta, non ancora consegnato
}
```

**Python**

```python title="whatsapp.py"
import os
import requests

def notify_order_shipped(phone: str, first_name: str, order_number: str, carrier: str) -> str:
    response = requests.post(
        "https://wa.genuka.com/api/v1/messages",
        headers={"Authorization": f"Bearer {os.environ['GENUKA_WA_API_KEY']}"},
        json={
            "connectionId": os.environ["GENUKA_WA_CONNECTION_ID"],
            "to": phone,  # E.164: "+237690000001"
            "template": {
                "name": "order_shipped",
                "language": "en",
                "body": [first_name, order_number, carrier],  # {{1}}, {{2}}, {{3}} in ordine
                "buttons": [{"type": "url", "text": order_number}],  # completa il link di tracciamento
            },
        },
        timeout=30,
    )
    result = response.json()
    if not response.ok:
        raise RuntimeError(f"{result['error']}: {result.get('message', '')}")
    return result["data"]["messageId"]  # accettato da Meta, non ancora consegnato
```

**PHP**

```php title="whatsapp.php"
<?php
function notifyOrderShipped(string $phone, string $firstName, string $orderNumber, string $carrier): string
{
    $ch = curl_init('https://wa.genuka.com/api/v1/messages');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('GENUKA_WA_API_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'connectionId' => getenv('GENUKA_WA_CONNECTION_ID'),
            'to' => $phone, // E.164: "+237690000001"
            'template' => [
                'name' => 'order_shipped',
                'language' => 'en',
                'body' => [$firstName, $orderNumber, $carrier], // {{1}}, {{2}}, {{3}} in ordine
                'buttons' => [['type' => 'url', 'text' => $orderNumber]], // completa il link di tracciamento
            ],
        ]),
    ]);
    $result = json_decode(curl_exec($ch), true);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    if ($status >= 400) {
        throw new RuntimeException($result['error'] . ': ' . ($result['message'] ?? ''));
    }
    return $result['data']['messageId']; // accettato da Meta, non ancora consegnato
}
```

Il percorso completo (modello, idempotenza, tracciamento della consegna) è in
[Notifiche d'ordine WhatsApp dal tuo backend](https://wa.genuka.com/it/docs/guides/order-notifications).

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

```md title="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](https://wa.genuka.com/it#pricing)). 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](https://wa.genuka.com/it/docs/authentication).

## Fonti

* [Meta — Send messages (customer service window)](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages)
* [Meta — Pricing on the WhatsApp Business Platform](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)
* [Model Context Protocol — What is MCP?](https://modelcontextprotocol.io/docs/getting-started/intro)
* [The /llms.txt proposal](https://llmstxt.org/)
* [Claude Code — Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp)
* [MCP — Connect to local MCP servers (Claude Desktop)](https://modelcontextprotocol.io/docs/develop/connect-local-servers)
* [Cursor — Model Context Protocol](https://cursor.com/docs/context/mcp)
* [VS Code — MCP configuration reference](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration)
* [Devin Desktop (formerly Windsurf) — MCP](https://docs.devin.ai/desktop/cascade/mcp)
* [Devin Desktop FAQ — Windsurf becomes Devin Desktop](https://docs.devin.ai/desktop/devin-desktop-faq)
