Bouw een WhatsApp-agent met de Vercel AI SDK

Hoe ontvangt de route handler WhatsApp-berichten?

Met twee methoden op één route, ingesteld als webhook-bestemming van het nummer, met een lang willekeurig geheim in het pad.

De GET beantwoordt de verificatie van Meta. Lees hub.mode, hub.verify_token en hub.challenge uit de query, vergelijk het token en geef de challenge terug als platte tekst. Die teruggeven via een JSON-helper is de klassieke fout: de body komt aan met aanhalingstekens eromheen en Meta begint nooit met bezorgen.

De POST ontvangt events. Geef snel 200 terug en doe de modelaanroep daarna, want Meta probeert trage antwoorden opnieuw en een cold start die het model inline draait, kan hetzelfde bericht twee keer beantwoorden. Op platforms die de functie beëindigen zodra het antwoord is verstuurd, geef je het werk door aan een queue of aan het mechanisme van het platform voor werk na het antwoord.

Het geheim in het pad is de authenticatie. Meta ondertekent elke bezorging met het app secret van de Tech Provider, dus de header X-Hub-Signature-256 kun je aan jouw kant niet controleren.

Hoe laadt de AI SDK de WhatsApp-tools?

Met createMCPClient uit @ai-sdk/mcp en het HTTP-transport, dat de documentatie van de AI SDK aanbeveelt voor productie. Het transport krijgt de server-URL en een authProvider, en OAuth via een authProvider is hoe de EasyCoexistence MCP-server wordt geautoriseerd: de server publiceert OAuth-metadata, ondersteunt dynamic client registration en PKCE en geeft na het inloggen eigen tokens uit. Er is geen API-sleutel om in een header te zetten.

De tools van de client gaan rechtstreeks in generateText of streamText. Het model ziet dan list_numbers, send_message, send_template, get_number_health en de rest, met beschrijvingen die het venster van 24 uur vermelden. Sluit de client als de aanroep klaar is: in de onEnd-callback bij een stream, anders in een finally-blok, zoals de documentatie van de AI SDK vraagt.

Gebruik het waar het model moet beslissen. Om te antwoorden op het bericht dat net binnenkwam, is een directe Cloud API-aanroep vanuit de handler korter.

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();
}

Wat verandert er doordat het nummer op Coexistence zit?

Twee dingen die de code moet weten. Ten eerste kan er al een mens in het gesprek zitten. De WhatsApp Business-app blijft werken op het nummer, en elk antwoord dat op de telefoon wordt getypt, komt als echo-event bij de route aan. Een handler die het model voor een contact pauzeert na een echo, voorkomt dat het over een persoon heen antwoordt.

Ten tweede is verzenden begrensd op vaste 20 berichten per seconde voor het nummer. Een conversationele agent komt daar nooit in de buurt, maar een broadcast-lus met Promise.all over een contactlijst wel, dus verwerk die in batches.

Alles andere is de gewone Cloud API. Binnen 24 uur na het laatste bericht van de klant is vrije tekst toegestaan. Daarna gaat alleen een goedgekeurd template door, en vrije tekst geeft foutcode 131047 terug zonder dat de klant iets ziet.

Veelgemaakte fouten

• De challenge teruggeven met een JSON-antwoordhelper. De aanhalingstekens eromheen laten de controle van Meta mislukken.
• generateText draaien voordat je Meta antwoordt. Bij een cold start levert de nieuwe poging een tweede antwoord op.
• Vergeten de MCP-client te sluiten. Elk verzoek laat een verbinding openstaan tot het platform die afbreekt.

Veelgestelde vragen

Lees verder