Vercel AI SDK で WhatsApp エージェントを作る

ルートハンドラーはどのように WhatsApp のメッセージを受信しますか？

1 つのルートに 2 つのメソッドを用意し、パスに長いランダムなシークレットを含めた URL を番号の Webhook 送信先に設定します。

GET は Meta の検証に応答します。クエリから hub.mode、hub.verify_token、hub.challenge を読み取り、トークンを照合して、challenge をプレーンテキストで返します。JSON 用のヘルパーで返してしまうのが典型的な失敗です。本文が引用符で囲まれた状態で届くため、Meta は配信を開始しません。

POST はイベントを受け取ります。まず 200 をすぐに返し、モデルの呼び出しはその後に行ってください。Meta は応答が遅いと再試行するため、コールドスタート中にモデルを同期的に実行すると、同じメッセージに 2 回回答してしまうことがあります。レスポンスの送信時に関数が終了するプラットフォームでは、処理をキューに渡すか、レスポンス後に処理を続けるためのプラットフォームの仕組みを使ってください。

パスのシークレットが認証の役割を果たします。Meta は各配信を Tech Provider のアプリシークレットで署名するため、X-Hub-Signature-256 ヘッダーをお客様側で検証することはできません。

AI SDK は WhatsApp のツールをどのように読み込みますか？

@ai-sdk/mcp の createMCPClient と HTTP トランスポートを使います。AI SDK のドキュメントでも、本番環境ではこの方法が推奨されています。トランスポートにはサーバーの URL と authProvider を渡します。EasyCoexistence の MCP サーバーは OAuth と authProvider の組み合わせで認可されます。サーバーは OAuth メタデータを公開し、動的クライアント登録と PKCE に対応しており、サインイン後に独自のトークンを発行します。ヘッダーに入れる API キーはありません。

クライアントのツールは、そのまま generateText や streamText に渡せます。モデルからは list_numbers、send_message、send_template、get_number_health などが見え、説明文には 24 時間ウィンドウの条件が明記されています。呼び出しが終わったらクライアントを閉じてください。ストリームでは onEnd コールバックで、それ以外では finally ブロックで閉じます。これは AI SDK のドキュメントにも記載されています。

モデルに判断させたい場面で使います。届いたばかりのメッセージに返信するだけなら、ハンドラーから Cloud API を直接呼ぶ方が簡潔です。

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

番号が Coexistence で動いていると、何が変わりますか？

コードで把握しておくべき点が 2 つあります。1 つ目は、すでに担当者が会話に加わっている可能性があることです。番号では WhatsApp Business アプリが引き続き使え、スマートフォンで入力した返信はすべてエコーイベントとしてルートに届きます。エコーを受け取った連絡先についてモデルを一時停止するハンドラーにすれば、担当者の返信に重ねて回答することを防げます。

2 つ目は、番号ごとの送信が毎秒 20 メッセージで固定されていることです。会話型のエージェントがこの上限に達することはありませんが、連絡先リストに Promise.all を使った一斉送信のループを書くと上限に達します。まとめて少しずつ送信してください。

それ以外は通常の Cloud API と同じです。お客様の最後のメッセージから 24 時間以内であれば、フリーテキストを送信できます。それを過ぎると承認済みのメッセージテンプレートしか送れず、フリーテキストはエラー 131047 を返し、お客様には何も表示されません。

よくある間違い

• challenge を JSON のレスポンスヘルパーで返してしまうこと。引用符が付くため、Meta の検証に失敗します。
• Meta に応答する前に generateText を実行すること。コールドスタート時は再試行により、2 回目の回答が送られます。
• MCP クライアントを閉じ忘れること。リクエストのたびに接続が開いたままになり、プラットフォームに強制終了されるまで残ります。

よくある質問

続きを読む