Agent WhatsApp z Vercel AI SDK

Jak route handler odbiera wiadomości WhatsApp?

Za pomocą dwóch metod na jednej trasie, ustawionej jako adres docelowy webhooka numeru, z długim losowym sekretem w ścieżce.

GET odpowiada na weryfikację od Meta. Odczytaj z zapytania hub.mode, hub.verify_token i hub.challenge, porównaj token i zwróć challenge jako zwykły tekst. Zwrócenie go przez pomocnik JSON to klasyczny błąd: treść przychodzi w cudzysłowie i Meta nigdy nie zaczyna dostarczać zdarzeń.

POST odbiera zdarzenia. Zwróć 200 szybko, a wywołanie modelu wykonaj później, bo Meta ponawia powolne odpowiedzi, a zimny start z modelem uruchamianym w trakcie żądania może odpowiedzieć na tę samą wiadomość dwa razy. Na platformach, które kończą funkcję po wysłaniu odpowiedzi, przekaż pracę do kolejki lub do mechanizmu platformy na pracę po odpowiedzi.

Sekret w ścieżce pełni rolę uwierzytelnienia. Meta podpisuje każde dostarczenie sekretem aplikacji Tech Provider, więc nagłówka X-Hub-Signature-256 nie sprawdzisz po swojej stronie.

Jak AI SDK ładuje narzędzia WhatsApp?

Przez createMCPClient z @ai-sdk/mcp i transport HTTP, który dokumentacja AI SDK zaleca na produkcji. Transport przyjmuje adres URL serwera oraz authProvider, a OAuth przez authProvider to sposób autoryzacji serwera MCP EasyCoexistence: publikuje on metadane OAuth, obsługuje dynamiczną rejestrację klienta i PKCE oraz po zalogowaniu wydaje własne tokeny. Nie ma klucza API do wstawienia w nagłówku.

Narzędzia klienta trafiają prosto do generateText lub streamText. Model widzi wtedy list_numbers, send_message, send_template, get_number_health i inne, z opisami wskazującymi 24-godzinne okno. Zamknij klienta po zakończeniu wywołania: w callbacku onEnd dla strumienia lub w bloku finally w pozostałych przypadkach, tak jak wymaga dokumentacja AI SDK.

Używaj go tam, gdzie decyzję ma podjąć model. Do odpowiedzi na wiadomość, która właśnie przyszła, krótsze jest bezpośrednie wywołanie Cloud API z handlera.

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

Co zmienia się, gdy numer działa w Coexistence?

Dwie rzeczy, o których kod powinien wiedzieć. Po pierwsze, w rozmowie może już uczestniczyć człowiek. Aplikacja WhatsApp Business nadal działa na numerze, a każda odpowiedź wpisana na telefonie trafia do trasy jako zdarzenie echo. Handler, który po echu wstrzymuje model dla danego kontaktu, nie pozwala mu odpowiadać ponad głową człowieka.

Po drugie, wysyłka jest ograniczona do stałych 20 wiadomości na sekundę dla numeru. Agent konwersacyjny nigdy się do tego nie zbliży, ale pętla rozsyłania napisana z Promise.all po liście kontaktów tak, więc dziel ją na partie.

Reszta to zwykłe Cloud API. W ciągu 24 godzin od ostatniej wiadomości klienta dozwolony jest dowolny tekst. Po tym czasie przechodzi tylko zatwierdzony szablon, a dowolny tekst zwraca błąd 131047, bez żadnego efektu widocznego dla klienta.

Typowe błędy

• Zwracanie challenge przez pomocnik odpowiedzi JSON. Cudzysłów wokół wartości psuje weryfikację Meta.
• Uruchamianie generateText przed odpowiedzią dla Meta. Przy zimnym starcie ponowienie powoduje drugą odpowiedź.
• Brak zamknięcia klienta MCP. Każde żądanie zostawia otwarte połączenie, dopóki platforma go nie zakończy.

Najczęściej zadawane pytania

Czytaj dalej