Crea un agente WhatsApp con il Vercel AI SDK

Come riceve il route handler i messaggi WhatsApp?

Con due metodi sulla stessa route, impostata come destinazione del webhook del numero con un segreto lungo e casuale nel percorso.

Il GET risponde alla verifica di Meta. Leggi hub.mode, hub.verify_token e hub.challenge dalla query, confronta il token e restituisci il challenge come testo semplice. Restituirlo con un helper JSON è l'errore classico: il corpo arriva tra virgolette e Meta non inizia mai a consegnare.

Il POST riceve gli eventi. Restituisci 200 subito ed esegui la chiamata al modello dopo, perché Meta ripete le consegne lente e un cold start che esegue il modello in linea può rispondere due volte allo stesso messaggio. Sulle piattaforme che terminano la funzione quando la risposta viene inviata, affida il lavoro a una coda o al meccanismo della piattaforma per il lavoro dopo la risposta.

Il segreto nel percorso è l'autenticazione. Meta firma ogni consegna con l'app secret del Tech Provider, quindi l'header X-Hub-Signature-256 non può essere verificato da te.

Come carica i tool WhatsApp l'AI SDK?

Con createMCPClient di @ai-sdk/mcp e il transport HTTP, che la documentazione dell'AI SDK consiglia per la produzione. Il transport richiede l'URL del server e un authProvider, e OAuth tramite un authProvider è il modo in cui si autorizza il server MCP di EasyCoexistence: pubblica i metadati OAuth, supporta la registrazione dinamica del client e PKCE, ed emette i propri token dopo l'accesso. Non c'è nessuna chiave API da mettere in un header.

I tool del client vanno direttamente in generateText o streamText. Il modello vede allora list_numbers, send_message, send_template, get_number_health e gli altri, con descrizioni che indicano la finestra di 24 ore. Chiudi il client a chiamata conclusa, nel callback onEnd per uno stream o in un blocco finally negli altri casi, come chiede la documentazione dell'AI SDK.

Usalo dove deve decidere il modello. Per rispondere al messaggio appena arrivato, una chiamata diretta alla Cloud API dal handler è più breve.

import { createMCPClient } from "@ai-sdk/mcp";

const mcp = await createMCPClient({
  transport: {
    type: "http",
    url: "https://easycoexistence.com/api/mcp",
    authProvider, // your OAuthClientProvider implementation
  },
});

try {
  const tools = await mcp.tools();
  // pass tools to generateText({ model, tools, prompt })
} finally {
  await mcp.close();
}

Cosa cambia perché il numero è su Coexistence?

Due cose che il codice deve conoscere. La prima: una persona può essere già nella conversazione. L'app WhatsApp Business continua a funzionare sul numero e ogni risposta scritta sul telefono arriva alla route come evento echo. Un handler che mette in pausa il modello per un contatto dopo un echo evita di rispondere sopra una persona.

La seconda: l'invio ha un limite fisso di 20 messaggi al secondo per il numero. Un agente conversazionale non ci arriva mai vicino, ma un ciclo di invio massivo scritto con Promise.all su una lista di contatti sì, quindi raggruppalo in lotti.

Tutto il resto è la normale Cloud API. Entro 24 ore dall'ultimo messaggio del cliente il testo libero è consentito. Dopo, passa solo un template approvato, e il testo libero restituisce l'errore 131047 senza che il cliente veda nulla.

Errori comuni

• Restituire il challenge con un helper di risposta JSON. Le virgolette attorno al valore fanno fallire la verifica di Meta.
• Eseguire generateText prima di rispondere a Meta. Con un cold start il nuovo tentativo produce una seconda risposta.
• Dimenticare di chiudere il client MCP. Ogni richiesta lascia una connessione aperta finché la piattaforma non la termina.

Domande frequenti

Continua a leggere