WhatsApp

عامل Triggerfish خود را به واتس‌اپ متصل کنید تا بتوانید از تلفن خود با آن تعامل داشته باشید. آداپتور از WhatsApp Business Cloud API (API HTTP رسمی میزبانی‌شده توسط Meta) استفاده می‌کند و پیام‌ها را از طریق webhook دریافت و از طریق REST ارسال می‌کند.

طبقه‌بندی پیش‌فرض

واتس‌اپ به‌صورت پیش‌فرض طبقه‌بندی PUBLIC دارد. مخاطبان واتس‌اپ می‌توانند شامل هرکسی با شماره تلفن شما باشند، بنابراین PUBLIC پیش‌فرض امن است.

راه‌اندازی

مرحله ۱: ایجاد حساب Meta Business

۱. به پرتال Meta for Developers بروید ۲. اگر حساب توسعه‌دهنده ندارید ایجاد کنید ۳. برنامه جدید ایجاد کنید و Business را به‌عنوان نوع برنامه انتخاب کنید ۴. در داشبورد برنامه، محصول WhatsApp را اضافه کنید

مرحله ۲: دریافت بیانات اعتبار

از بخش WhatsApp داشبورد برنامه، این مقادیر را جمع‌آوری کنید:

• Access Token — یک توکن دسترسی دائمی (یا یک موقت برای آزمایش تولید کنید)
• Phone Number ID — شناسه شماره تلفن ثبت‌شده در WhatsApp Business
• Verify Token — رشته‌ای که خودتان انتخاب می‌کنید، برای تأیید ثبت webhook استفاده می‌شود

مرحله ۳: پیکربندی Webhook‌ها

۱. در تنظیمات محصول WhatsApp، به Webhooks بروید ۲. URL بازخوانی را به آدرس عمومی سرور خود تنظیم کنید (مثلاً https://your-server.com:8443/webhook) ۳. Verify Token را به همان مقداری که در پیکربندی Triggerfish استفاده خواهید کرد تنظیم کنید ۴. فیلد webhook messages را مشترک شوید

URL عمومی الزامی است Webhookهای واتس‌اپ به یک نقطه پایانی HTTPS با دسترسی عمومی نیاز دارند. اگر Triggerfish را به‌صورت محلی اجرا می‌کنید، به سرویس تونل (مثلاً ngrok، Cloudflare Tunnel) یا سروری با IP عمومی نیاز خواهید داشت. :::

مرحله ۴: پیکربندی Triggerfish

کانال واتس‌اپ را به triggerfish.yaml اضافه کنید:

channels:
  whatsapp:
    # accessToken در کلیدزنجیر سیستم‌عامل ذخیره شده
    phoneNumberId: "your-phone-number-id"
    # verifyToken در کلیدزنجیر سیستم‌عامل ذخیره شده
    ownerPhone: "15551234567"

گزینه	نوع	الزامی	توضیحات
accessToken	string	بله	توکن دسترسی WhatsApp Business API
phoneNumberId	string	بله	Phone Number ID از داشبورد Meta Business
verifyToken	string	بله	توکن برای تأیید webhook (خودتان انتخاب می‌کنید)
webhookPort	number	خیر	پورت گوش دادن برای webhookها (پیش‌فرض: 8443)
ownerPhone	string	توصیه‌شده	شماره تلفن شما برای تأیید مالک (مثلاً "15551234567")
classification	string	خیر	سطح طبقه‌بندی (پیش‌فرض: PUBLIC)

رمزها را ایمن ذخیره کنید هرگز توکن‌های دسترسی را در کنترل منبع ثبت نکنید. از متغیرهای محیطی یا کلیدزنجیر سیستم‌عامل استفاده کنید. :::

مرحله ۵: شروع Triggerfish

triggerfish stop && triggerfish start

از تلفن خود به شماره WhatsApp Business پیامی بفرستید تا اتصال را تأیید کنید.

هویت مالک

Triggerfish وضعیت مالک را با مقایسه شماره تلفن فرستنده با ownerPhone پیکربندی‌شده تعیین می‌کند. این بررسی در کد قبل از دیدن پیام توسط LLM رخ می‌دهد:

• مطابقت — پیام دستور مالک است
• عدم مطابقت — پیام ورودی خارجی با Taint PUBLIC است

اگر ownerPhone پیکربندی نشده باشد، تمام پیام‌ها به‌عنوان آمده از مالک برخورد می‌شوند.

همیشه شماره تلفن مالک را تنظیم کنید اگر دیگران ممکن است به شماره WhatsApp Business شما پیام بدهند، همیشه ownerPhone را پیکربندی کنید تا از اجرای دستورات غیرمجاز جلوگیری شود. :::

نحوه عملکرد Webhook

آداپتور یک سرور HTTP روی پورت پیکربندی‌شده (پیش‌فرض 8443) شروع می‌کند که دو نوع درخواست را مدیریت می‌کند:

۱. GET /webhook — Meta این را برای تأیید نقطه پایانی webhook شما می‌فرستد. Triggerfish اگر توکن تأیید مطابقت داشته باشد با توکن چالش پاسخ می‌دهد. ۲. POST /webhook — Meta پیام‌های ورودی را اینجا می‌فرستد. Triggerfish بار webhook Cloud API را تجزیه می‌کند، پیام‌های متنی را استخراج و به پردازشگر پیام ارسال می‌کند.

محدودیت‌های پیام

واتس‌اپ از پیام‌های تا ۴٬۰۹۶ کاراکتر پشتیبانی می‌کند. پیام‌هایی که از این محدودیت فراتر روند قبل از ارسال به چند پیام تقسیم می‌شوند.

نشانگرهای تایپ

Triggerfish نشانگرهای تایپ را در واتس‌اپ ارسال و دریافت می‌کند. وقتی عامل شما در حال پردازش درخواست است، چت نشانگر تایپ نمایش می‌دهد. رسیدهای خوانده‌شده نیز پشتیبانی می‌شوند.

تغییر طبقه‌بندی

channels:
  whatsapp:
    # accessToken در کلیدزنجیر سیستم‌عامل ذخیره شده
    phoneNumberId: "your-phone-number-id"
    # verifyToken در کلیدزنجیر سیستم‌عامل ذخیره شده
    classification: INTERNAL

سطوح معتبر: PUBLIC، INTERNAL، CONFIDENTIAL، RESTRICTED.