Créer un agent WhatsApp avec le Vercel AI SDK

Comment le route handler reçoit-il les messages WhatsApp ?

Avec deux méthodes sur une même route, définie comme destination du webhook du numéro, avec un long secret aléatoire dans le chemin.

Le GET répond à la vérification de Meta. Lisez hub.mode, hub.verify_token et hub.challenge dans la requête, comparez le token, puis renvoyez le challenge en texte brut. Le renvoyer via un helper JSON est l'erreur classique : le corps arrive entouré de guillemets et Meta ne commence jamais à livrer.

Le POST reçoit les événements. Renvoyez 200 rapidement et faites l'appel au modèle ensuite, car Meta relance les réponses lentes et un démarrage à froid qui exécute le modèle en ligne peut répondre deux fois au même message. Sur les plateformes qui terminent la fonction dès l'envoi de la réponse, confiez le travail à une file ou au mécanisme de la plateforme pour le traitement après la réponse.

Le secret du chemin fait office d'authentification. Meta signe chaque livraison avec l'app secret du Tech Provider, donc l'en-tête X-Hub-Signature-256 ne peut pas être vérifié de votre côté.

Comment l'AI SDK charge-t-il les outils WhatsApp ?

Avec createMCPClient de @ai-sdk/mcp et le transport HTTP, que la documentation de l'AI SDK recommande pour la production. Le transport prend l'URL du serveur et un authProvider, et OAuth via un authProvider est la façon dont le serveur MCP d'EasyCoexistence est autorisé : il publie ses métadonnées OAuth, prend en charge l'enregistrement dynamique de client et PKCE, et émet ses propres tokens après une connexion. Il n'y a aucune clé d'API à placer dans un en-tête.

Les outils du client vont directement dans generateText ou streamText. Le modèle voit alors list_numbers, send_message, send_template, get_number_health et les autres, avec des descriptions qui rappellent la fenêtre de 24 heures. Fermez le client quand l'appel est terminé, dans le callback onEnd pour un flux ou dans un bloc finally sinon, comme le demande la documentation de l'AI SDK.

Utilisez-le quand c'est au modèle de décider. Pour répondre au message qui vient d'arriver, un appel direct à la Cloud API depuis le handler est plus court.

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

Qu'est-ce qui change parce que le numéro est en Coexistence ?

Deux choses que le code doit connaître. D'abord, une personne peut déjà être dans la conversation. L'app WhatsApp Business continue de fonctionner sur le numéro, et chaque réponse saisie sur le téléphone arrive sur la route sous forme d'événement echo. Un handler qui met le modèle en pause pour un contact après un echo évite de répondre par-dessus un humain.

Ensuite, l'envoi est plafonné à 20 messages par seconde, un débit fixe pour le numéro. Un agent conversationnel n'en approche jamais, mais une boucle de diffusion écrite avec Promise.all sur une liste de contacts, si : traitez-la par lots.

Tout le reste relève de la Cloud API ordinaire. Dans les 24 heures qui suivent le dernier message du client, le texte libre est autorisé. Au-delà, seul un template approuvé passe, et le texte libre renvoie l'erreur 131047 sans que le client voie quoi que ce soit.

Erreurs courantes

• Renvoyer le challenge avec un helper de réponse JSON. Les guillemets autour font échouer la vérification de Meta.
• Exécuter generateText avant de répondre à Meta. Lors d'un démarrage à froid, la relance produit une seconde réponse.
• Oublier de fermer le client MCP. Chaque requête laisse une connexion ouverte jusqu'à ce que la plateforme la coupe.

Questions fréquemment posées

Poursuivre la lecture