בניית סוכן WhatsApp עם Vercel AI SDK

איך ה-route handler מקבל הודעות WhatsApp?

עם שתי מתודות על אותו route, שמוגדר כיעד ה-וובהוק של המספר, עם סוד אקראי וארוך בנתיב.

ה-GET עונה על האימות של Meta. קוראים מהשאילתה את hub.mode, hub.verify_token ו-hub.challenge, משווים את האסימון, ומחזירים את ה-challenge כטקסט רגיל. הטעות הקלאסית היא להחזיר אותו דרך פונקציית עזר של JSON: התוכן מגיע עם מרכאות, ו-Meta אף פעם לא מתחילה לשלוח.

ה-POST מקבל את האירועים. מחזירים 200 מהר ומפעילים את המודל אחר כך, כי Meta שולחת שוב כשהתגובה איטית, והפעלה קרה שמריצה את המודל באותו רגע עלולה לענות על אותה הודעה פעמיים. בפלטפורמות שמסיימות את הפונקציה ברגע שהתגובה נשלחת, מעבירים את העבודה לתור או למנגנון של הפלטפורמה לעבודה אחרי התגובה.

הסוד בנתיב הוא האימות. Meta חותמת כל משלוח עם סוד האפליקציה של ה-Tech Provider, ולכן אי אפשר לבדוק את הכותרת X-Hub-Signature-256 מהצד שלכם.

איך AI SDK טוען את כלי WhatsApp?

עם createMCPClient מהחבילה @ai-sdk/mcp ותעבורת HTTP, שהתיעוד של AI SDK ממליץ עליה לסביבת ייצור. התעבורה מקבלת את כתובת השרת ו-authProvider, והאישור מול שרת MCP של EasyCoexistence נעשה דרך OAuth: השרת מפרסם מטא-דאטה של OAuth, תומך ברישום דינמי של לקוחות וב-PKCE, ומנפיק אסימונים משלו אחרי כניסה. אין מפתח API להכניס לכותרת.

הכלים של הלקוח עוברים ישירות ל-generateText או ל-streamText. המודל רואה אז את list_numbers, send_message, send_template, get_number_health ועוד, עם תיאורים שמציינים את חלון 24 השעות. סוגרים את הלקוח בסיום הקריאה: ב-callback של onEnd כשזה סטרים, ובבלוק finally בשאר המקרים, כפי שהתיעוד של AI SDK מבקש.

כדאי להשתמש בזה כשהמודל צריך להחליט. כדי לענות להודעה שהרגע הגיעה, קריאה ישירה ל-Cloud API מתוך ה-handler קצרה יותר.

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?

שני דברים שהקוד צריך להכיר. הראשון: אדם יכול כבר להיות בשיחה. אפליקציית WhatsApp Business ממשיכה לעבוד על המספר, וכל תשובה שנכתבת בטלפון מגיעה ל-route כאירוע echo. handler שמשהה את המודל מול איש קשר אחרי echo מונע מהמודל לענות מעל אדם.

השני: השליחה מוגבלת לקצב קבוע של 20 הודעות בשנייה למספר. סוכן שיחה אף פעם לא מתקרב לזה, אבל לולאת שידור שנכתבה עם Promise.all על רשימת אנשי קשר כן תגיע לשם, ולכן שולחים במנות.

כל השאר הוא Cloud API רגיל. עד 24 שעות מההודעה האחרונה של הלקוח מותר טקסט חופשי. אחרי זה עוברת רק תבנית מאושרת, וטקסט חופשי מחזיר שגיאה 131047 בלי שהלקוח רואה משהו.

טעויות נפוצות

• להחזיר את ה-challenge דרך פונקציית עזר של JSON. המרכאות סביבו מכשילות את הבדיקה של Meta.
• להריץ את generateText לפני שעונים ל-Meta. בהפעלה קרה, השליחה החוזרת יוצרת תשובה שנייה.
• לשכוח לסגור את לקוח ה-MCP. כל בקשה משאירה חיבור פתוח עד שהפלטפורמה מסיימת אותו.

שאלות נפוצות

המשיכו לקרוא