بناء وكيل على WhatsApp باستخدام Vercel AI SDK

كيف يستقبل route handler رسائل WhatsApp؟

بطريقتين على مسار واحد، يُضبط وجهةً لـ webhook الخاص بالرقم، مع سر عشوائي طويل في المسار.

تجيب GET على تحقق Meta. اقرأ hub.mode وhub.verify_token وhub.challenge من الاستعلام، وقارن رمز الوصول (token)، ثم أعد قيمة challenge نصًا عاديًا. إعادتها عبر دالة JSON هي الخطأ الكلاسيكي: يصل المحتوى وحوله علامات اقتباس، فلا تبدأ Meta بالتسليم أبدًا.

تستقبل POST الأحداث. أعد 200 بسرعة ونفّذ استدعاء النموذج بعد ذلك، لأن Meta تعيد المحاولة عند بطء الاستجابة، وقد يردّ التشغيل البارد الذي ينفّذ النموذج داخل الطلب على الرسالة نفسها مرتين. في المنصات التي تنهي الدالة عند إرسال الاستجابة، سلّم العمل إلى طابور أو إلى آلية المنصة لتنفيذ العمل بعد الاستجابة.

سر المسار هو المصادقة. توقّع Meta كل عملية تسليم بسر تطبيق Tech Provider، لذلك لا يمكن التحقق من ترويسة X-Hub-Signature-256 من جانبك.

كيف يحمّل AI SDK أدوات WhatsApp؟

باستخدام createMCPClient من @ai-sdk/mcp ونقل HTTP الذي توصي به وثائق AI SDK للإنتاج. يأخذ النقل عنوان URL الخاص بالخادم وauthProvider، وOAuth عبر authProvider هو طريقة تفويض خادم EasyCoexistence MCP: ينشر الخادم بيانات 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 على الرقم؟

هناك أمران ينبغي أن يعرفهما الكود. الأول أن شخصًا قد يكون موجودًا في المحادثة أصلًا. يواصل تطبيق WhatsApp Business العمل على الرقم، وكل رد يُكتب من الهاتف يصل إلى المسار بوصفه حدث echo. المعالج الذي يوقف النموذج لجهة اتصال بعد حدث echo يمنعه من الرد فوق كلام شخص.

الثاني أن الإرسال محدود بحد ثابت هو 20 رسالة في الثانية للرقم. الوكيل المحادثي لا يقترب منه أبدًا، أما حلقة بث مكتوبة بـ Promise.all على قائمة جهات اتصال فستبلغه، لذا قسّمها إلى دفعات.

كل ما عدا ذلك هو Cloud API العادية. خلال 24 ساعة من آخر رسالة للعميل يُسمح بالنص الحر. بعد ذلك لا يمر إلا قالب معتمد، ويعيد النص الحر الخطأ 131047 دون أن يرى العميل شيئًا.

الأخطاء الشائعة

• إعادة challenge عبر دالة استجابة JSON. علامات الاقتباس حولها تُفشل تحقق Meta.
• تشغيل generateText قبل الرد على Meta. عند التشغيل البارد تنتج إعادة المحاولة إجابة ثانية.
• نسيان إغلاق عميل MCP. كل طلب يترك اتصالًا مفتوحًا إلى أن تقتله المنصة.

الأسئلة الشائعة

تابع القراءة