WhatsApp Template API

API توسعه‌دهندگان

قالب‌های تأییدشده واتس‌اپ را با یک فراخوانی API از سیستم‌های خودتان ارسال کنید؛ سپس گفتگو در MonoChat ادامه می‌یابد.

واتس‌اپ
REST API
فقط API

بررسی کلی

WhatsApp Template API به CRM، ERP، فروشگاه اینترنتی یا هر بک‌اندی اجازه می‌دهد از طریق MonoChat یک پیام قالب تأییدشدهٔ واتس‌اپ برای مشتری بفرستد. در یک درخواست، شمارهٔ واتس‌اپ فرستنده، شمارهٔ تلفن مشتری، قالب و متغیرهای آن مشخص می‌شود.

وقتی مشتری پاسخ می‌دهد، گفتگو مثل هر گفتگوی دیگری در صندوق ورودی MonoChat شما قرار می‌گیرد. این برنامه صفحهٔ اختصاصی ندارد: همه‌چیز از طریق سه اندپوینت API انجام می‌شود.

ویژگی‌های برجسته

یک فراخوانی API. قالب را با نام و زبان ارسال کنید و متغیرهای سرایند، متن، دکمه و کاروسل را از داده‌های خودتان پر کنید.
مستقیم به چت. هر ارسال، شناسهٔ گفتگو و پیوند مستقیم آن در MonoChat را برمی‌گرداند.
مشتریان جدید خوش‌آمدند. اگر شمارهٔ تلفن هنوز مشتری نباشد، مشتری با نامی که می‌فرستید ساخته می‌شود.

نصب و راه‌اندازی

شمارهٔ واتس‌اپ بیزینس خود را به MonoChat وصل کنید و مطمئن شوید تأیید شده است و قالب‌های تأییدشده توسط Meta دارد.
WhatsApp Template API را از تنظیمات › MonoStore › برنامه‌ها نصب کنید، یا لینک نصب app.monochat.ai/apps/K6u29LpbwCHBozZ8o را باز کنید. اگر حساب MonoChat ندارید، این لینک ابتدا شما را به ثبت‌نام می‌برد و سپس برنامه را برایتان نصب می‌کند.
در پروفایل › توکن‌های API یک توکن API بسازید. توکن فقط یک بار نمایش داده می‌شود، پس بلافاصله آن را کپی کنید.
template/list.js را فراخوانی کنید تا قالب‌های تأییدشده و متغیرهایشان را ببینید.
template/send.js را با شمارهٔ مشتری و مقادیر متغیرها فراخوانی کنید تا اولین قالب خود را بفرستید.

فهرست برنامه‌های MonoStore در تنظیمات MonoChat، همراه با WhatsApp Template API

جزئیات WhatsApp Template API در MonoStore همراه با دکمهٔ نصب

یادداشت

هزینهٔ هر پیام مانند هر پیام قالب دیگری که از MonoChat ارسال می‌شود محاسبه می‌شود.
نشانی رسانه‌ها باید تا زمانی که واتس‌اپ فایل را دریافت کند در دسترس بماند.
فقط برای مشتریانی بفرستید که موافقت کرده‌اند از شما پیام بگیرند: واتس‌اپ می‌تواند شماره‌هایی را که پیام‌هایشان مسدود یا گزارش می‌شود محدود کند.

قابلیت‌ها

فهرست‌کردن قالب‌ها

قالب‌های تأییدشدهٔ یک شمارهٔ واتس‌اپ، با زبان، دسته، وضعیت و متغیرهایشان، تا سیستم شما بداند چه چیزی می‌تواند بفرستد.

ارسال قالب

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

واگذاری به کارشناس

ایمیل یک کارشناس را بدهید تا گفتگو به نام او باز شود.

سرایند رسانه‌ای

اطلاعات احراز موقت برای آپلود بگیرید، تصویر، ویدیو یا سندی را در فضای ذخیره‌سازی MonoChat قرار دهید و نشانی آن را به‌عنوان سرایند قالب استفاده کنید.

پیوند گفتگو

هر ارسال، شناسهٔ نشست، شناسهٔ پیام و پیوندی را برمی‌گرداند که گفتگو را در MonoChat باز می‌کند.

خطاهای روشن

یک فراخوانی ناموفق می‌گوید چه چیزی اشتباه بوده است، برای مثال «Channel not found» یا «Variable missing».

پیش از شروع

شمارهٔ واتس‌اپ بیزینس شما به MonoChat وصل و تأیید شده است. کانال‌ها را ببینید.
قالب‌هایی که می‌خواهید بفرستید توسط Meta تأیید شده‌اند. قالب‌ها راهی هستند که با آن‌ها اول شما پیام می‌دهید، یا خارج از پنجرهٔ ۲۴ ساعته به مشتری می‌رسید. قالب‌های پیام را ببینید.
از پروفایل › توکن‌های API یک توکن API دارید. توکن‌های API را ببینید.
tenant slug خود را می‌دانید: بخشی از نشانی MonoChat شما که بعد از /tenants/ می‌آید. در https://app.monochat.ai/tenants/mybusiness مقدار slug برابر mybusiness است.

مرجع API

این برنامه صفحهٔ اختصاصی ندارد. همه‌چیز از طریق سه اندپوینت انجام می‌شود که هر کدام یک POST با بدنهٔ JSON است:

POST https://app.monochat.ai/api/<slug>/custom-functions/template-app/api/<endpoint>
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

اندپوینت	کار آن
`template/list.js`	قالب‌های یکی از شماره‌های واتس‌اپ شما را همراه با متغیرهایشان فهرست می‌کند.
`template/send.js`	یک قالب را برای مشتری می‌فرستد و پیوند گفتگو را برمی‌گرداند.
`upload/get-token.js`	اطلاعات احراز موقت آپلود را برای تصویر، ویدیو یا سند سرایند می‌دهد.

شماره‌های تلفن همیشه با کد کشور و بدون + نوشته می‌شوند، مثلاً 905334445566. یک فراخوانی موفق با 200 پاسخ می‌دهد و داده‌های اندپوینت را زیر result برمی‌گرداند.

1. فهرست‌کردن قالب‌ها

POST /api/<slug>/custom-functions/template-app/api/template/list.js

همهٔ قالب‌های شمارهٔ واتس‌اپ بیزینس داده‌شده را فهرست می‌کند: نام، کد زبان، دسته، اجزا (سرایند، متن، پاورقی، دکمه‌ها)، نوع متغیرها و وضعیت تأیید.

فیلد	الزامی	توضیحات
`phoneNumber`	بله	شمارهٔ واتس‌اپ بیزینس شما در MonoChat، با کد کشور و بدون `+`.
`options`	خیر	صفحه‌بندی و فیلترها، مثلاً `{ "pagination": { "currentPage": 1, "pageItems": 50 } }`.

POST /api/<slug>/custom-functions/template-app/api/template/list.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566"
}

پاسخ (کوتاه‌شده):

{
  "result": {
    "templateMessages": [
      {
        "name": "new_product_announcement",
        "languageCode": "tr-TR",
        "category": "MARKETING",
        "components": [
          {
            "type": "HEADER",
            "format": "IMAGE",
            "variables": [
              { "type": "IMAGE", "value": null, "exampleValue": "https://.../sample-image.png" }
            ]
          },
          {
            "type": "BODY",
            "text": "Merhaba {{1}}, yeni ürünümüz {{2}} çıktı!",
            "sampleText": "Merhaba [Ayşe], yeni ürünümüz [XYZ Telefon] çıktı.",
            "variables": [
              { "type": "TEXT", "value": null, "exampleValue": "[Ayşe]" },
              { "type": "TEXT", "value": null, "exampleValue": "[XYZ Telefon]" }
            ]
          },
          {
            "type": "FOOTER",
            "text": "Teşekkürler",
            "sampleText": "Teşekkürler"
          }
        ],
        "status": "APPROVED"
      }
    ],
    "options": {
      "pagination": { "totalCount": 12, "currentPage": 1, "pageItems": 12, "totalPages": 1 }
    }
  }
}

نحوهٔ خواندن آن:

name: نام سیستمی که قالب با آن ارسال می‌شود.
languageCode: زبانی که قالب به آن ارسال می‌شود.
category: دستهٔ واتس‌اپ (MARKETING، UTILITY، AUTHENTICATION).
components: بخش‌هایی که قالب از آن‌ها ساخته شده است.

جزء	محتوا	توضیحات
`HEADER`	`IMAGE`، `VIDEO`، `DOCUMENT` یا متن	برای رسانه، `format` داده می‌شود؛ متغیرها زیر `variables` می‌آیند.
`BODY`	متن همراه با متغیرها	متن پیام، با جانشین‌هایی مانند `{{1}}` و `{{2}}`.
`FOOTER`	متن	معمولاً متغیر ندارد.
`BUTTONS`	URL، پاسخ سریع…	متن دکمه‌ها و متغیرهای آن‌ها، در صورت وجود.

قالب نمونهٔ بالا برای سرایند به یک تصویر و برای متن به دو متن (نام مشتری و نام محصول) نیاز دارد. پاورقی ثابت است («Teşekkürler») و دکمه‌ای وجود ندارد.

2. ارسال قالب

POST /api/<slug>/custom-functions/template-app/api/template/send.js

یک قالب تأییدشده را برای مشتری می‌فرستد. اگر شمارهٔ تلفن هنوز مشتری نباشد، مشتری ساخته می‌شود؛ گفتگو باز (یا دوباره استفاده) می‌شود و قالب در آن ارسال می‌شود.

فیلد	الزامی	توضیحات
`phoneNumber`	بله	شمارهٔ واتس‌اپ بیزینسی که از آن ارسال می‌شود. باید به MonoChat وصل و تأیید شده باشد.
`templateMessageName`	بله	`name` قالب، دقیقاً همان‌طور که فهرست برمی‌گرداند.
`languageCode`	بله	زبان قالب، همان‌طور که فهرست برمی‌گرداند (مثلاً `tr-TR`).
`customerPhoneNumber`	بله	شمارهٔ واتس‌اپ مشتری.
`variables`	اگر قالب متغیر دارد	مقادیر متغیرهای قالب (پایین را ببینید).
`customerFirstName`, `customerLastName`	خیر	وقتی مشتری برای MonoChat جدید است استفاده می‌شود.
`agentEmailAddress`	خیر	گفتگو را به کارشناسی با این ایمیل واگذار می‌کند.

متغیرها. هر مورد از آرایهٔ variables یک type و فهرستی از parameters دارد که به ترتیب جانشین‌های قالب داده می‌شوند:

`type`	`parameters`
`HEADER`	متغیر متن سرایند، یا نشانی عمومی تصویر، ویدیو یا سند سرایند.
`BODY`	مقادیر `{{1}}`، `{{2}}`، … متن، به ترتیب.
`BUTTONS`	یک مقدار برای هر دکمه‌ای که متغیر دارد (مثلاً بخش پویای یک دکمهٔ URL یا یک کد کوپن)، به ترتیب دکمه‌ها.
`CAROUSEL`	به‌جای `parameters`، آرایه‌ای به نام `cards` با یک مورد برای هر کارت کاروسل، که هر کدام `components` خودش را دارد.

{ "type": "CAROUSEL", "cards": [ { "components": [ { "type": "HEADER", "parameters": ["https://…/1.jpg"] }, { "type": "BODY", "parameters": ["…"] } ] } ] }

مقدار گم‌شده ارسال را با Variable missing متوقف می‌کند، پس هیچ پیام نیمه‌پر به مشتری نمی‌رسد. FOOTER به‌ندرت متغیر دارد.

POST /api/<slug>/custom-functions/template-app/api/template/send.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566",
  "templateMessageName": "new_product_announcement",
  "languageCode": "tr-TR",
  "customerPhoneNumber": "905306667788",
  "customerFirstName": "Ayşe",
  "agentEmailAddress": "sarah@yourcompany.com",
  "variables": [
    { "type": "HEADER", "parameters": ["https://…/product.jpg"] },
    { "type": "BODY", "parameters": ["Ayşe", "XYZ Phone"] }
  ]
}

پاسخ:

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "…",
    "messageId": "…"
  }
}

url: گفتگو را در MonoChat باز می‌کند، برای کسانی که وارد شده‌اند و اجازهٔ دیدن آن را دارند.
sessionId: شناسهٔ گفتگو.
messageId: شناسهٔ پیام در MonoChat. وضعیت تحویل و خوانده‌شدن آن مثل هر پیام دیگری در چت نمایش داده می‌شود.

رسانه در قالب‌ها. واتس‌اپ رسانهٔ سرایند را از نشانی‌ای که می‌دهید دانلود می‌کند، پس نشانی باید معتبر و به‌صورت عمومی در دسترس باشد. پیوندهایی که ورود به سیستم لازم دارند کار نمی‌کنند. اگر فایل را با upload/get-token.js آپلود کرده‌اید، از نشانی فایل که از آن پاسخ ساخته می‌شود استفاده کنید.

3. آپلود رسانه برای سرایند

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js

وقتی سرایند یک قالب تصویر، ویدیو یا سند است، فایل به نشانی عمومی‌ای نیاز دارد که واتس‌اپ بتواند از آن دانلودش کند. این اندپوینت به شما اجازهٔ موقت می‌دهد فایل را در فضای ذخیره‌سازی MonoChat قرار دهید.

فیلد	الزامی	توضیحات
`fileName`	بله	نام فایل همراه با پسوند، مثلاً `product.jpg` یا `promo.pdf`.

فایل‌ها همیشه در پوشهٔ chat-assets فضای کاری شما ذخیره می‌شوند؛ نمونه‌های قدیمی‌تر که فیلد key می‌فرستند همچنان کار می‌کنند، این مقدار لازم نیست.

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "fileName": "product.jpg"
}

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

فیلد	توضیحات
`bucket`, `region`, `path`	محل قرار گرفتن فایل.
`temporaryCredentials`	اطلاعات احراز فقط برای آپلود در همان یک مسیر، با اعتبار ۱۵ دقیقه.
`baseUrl`	نشانی عمومی فضای ذخیره‌سازی. نشانی فایل برابر است با `baseUrl` + `/` + `path`.

فایل را بلافاصله با هر کلاینت S3 و با این اطلاعات احراز آپلود کنید، سپس هنگام ارسال قالب، نشانی آن را به‌عنوان پارامتر HEADER بدهید. فایل‌های بسیار بزرگ یا قالب‌هایی که واتس‌اپ پشتیبانی نمی‌کند (قالب‌های رایج تصویر، ویدیو و PDF را می‌پذیرد) ناموفق می‌شوند.

نمونه: قالبی با سرایند تصویر

فرض کنید قالب تأییدشدهٔ new_product_announcement را دارید که سرایند تصویری و دو متغیر متن (نام مشتری و نام محصول) دارد و می‌خواهید آن را برای یک مشتری بفرستید.

قالب‌ها را فهرست کنید. template/list.js را با شمارهٔ واتس‌اپ خود فراخوانی کنید و new_product_announcement را پیدا کنید. اجزای آن یک متغیر IMAGE در سرایند و دو متغیر TEXT در متن را نشان می‌دهند.
تصویر را آپلود کنید. upload/get-token.js را با { "fileName": "urun.jpg" } فراخوانی کنید، فایل را با اطلاعات احراز برگشتی آپلود کنید و نشانی آن را از baseUrl و path بسازید.
قالب را بفرستید. template/send.js را با نشانی فایل به‌عنوان پارامتر HEADER و ["Ayşe", "XYZ Telefon"] به‌عنوان پارامترهای BODY فراخوانی کنید ({{1}} ← Ayşe، {{2}} ← XYZ Telefon). اگر قالب متغیر دکمه داشت، یک مورد BUTTONS را به همان روش اضافه می‌کردید.
چت را باز کنید. url پاسخ گفتگو را باز می‌کند؛ وقتی مشتری پاسخ می‌دهد، گفتگو در صندوق ورودی MonoChat شما ادامه می‌یابد.

خطاها

یک فراخوانی ناموفق با یک وضعیت خطا و پیامی که می‌گوید چه چیزی اشتباه بوده پاسخ می‌دهد. این پیام‌ها را در سیستم خود ثبت کنید و در صورت لزوم پیامی معنادار به کاربران خود نشان دهید.

پیام	علت
`phoneNumber field is required`	`template/list.js` بدون `phoneNumber` فراخوانی شده است.
`phoneNumber, templateMessageName, customerPhoneNumber fields are required`	یکی از فیلدهای الزامی `template/send.js` وجود ندارد.
`Channel not found`	`phoneNumber` یکی از شماره‌های واتس‌اپ فضای کاری شما نیست.
`Channel is not verified`	شمارهٔ واتس‌اپ وصل شده اما تأیید نشده است.
`Template message not found`	قالب تأییدشده‌ای با آن نام و زبان روی این شماره وجود ندارد. املا و `languageCode` را بررسی کنید.
`Template message is not approved`	قالب وجود دارد اما توسط Meta تأیید نشده است.
`Variable missing: …`	`variables` با قالب مطابقت ندارد، مثلاً قالب دو مقدار برای متن می‌خواهد و شما یکی فرستاده‌اید.
`Agent user not found`	کارشناسی با ایمیل `agentEmailAddress` وجود ندارد.
`Customer Channel not found`	هویت واتس‌اپ مشتری ساخته یا پیدا نشد.

کدهای وضعیت HTTP که ممکن است ببینید:

401 Unauthorized: سرآیند Authorization: Bearer <API_TOKEN> وجود ندارد، یا توکن اشتباه یا منقضی است. از یک توکن معتبر حساب خود استفاده کنید.
403 Forbidden: توکن به این فضای کاری یا برنامه دسترسی ندارد، مثلاً tenant slug اشتباه است.
404 Not Found: نشانی اندپوینت اشتباه است. مسیر کامل /api/<slug>/custom-functions/template-app/api/... را بررسی کنید.
500 Internal Server Error: مشکلی پیش‌بینی‌نشده در MonoChat یا نزد ارائه‌دهندهٔ واتس‌اپ، یا رد درخواست از سمت واتس‌اپ (شماره در واتس‌اپ نیست، مشتری شما را مسدود کرده، محدودیت‌های کیفیت یا نرخ). بعداً دوباره تلاش کنید و اگر ادامه داشت با پشتیبانی MonoChat تماس بگیرید.

تصاویر محیط برنامه

ارسال یک قالب تأییدشدهٔ واتس‌اپ از CRM، ERP یا سیستم فروشگاه اینترنتی با یک فراخوانی API از طریق MonoChat

فهرست قالب‌های تأییدشدهٔ واتس‌اپ همراه با متغیرهایشان

ارسال قالب به یک شمارهٔ جدید، مشتری را خودکار می‌سازد

یک قالب که به چند زبان ارسال شده است

قالب‌هایی با سرایند تصویر، ویدیو، سند و PDF

سؤالات متداول

آیا WhatsApp Template API رابط کاربری دارد؟

خیر. این برنامه فقط API است و سه اندپوینت دارد: فهرست قالب‌ها، ارسال قالب و دریافت اطلاعات احراز آپلود برای سرایندهای رسانه‌ای.

پیش از استفاده به چه چیزی نیاز دارم؟

یک شمارهٔ واتس‌اپ بیزینس که به MonoChat وصل و تأیید شده باشد، قالب‌های تأییدشده توسط Meta و یک توکن API از پروفایل › توکن‌های API.

وقتی مشتری پاسخ می‌دهد چه می‌شود؟

گفتگو مثل هر گفتگوی دیگری در صندوق ورودی MonoChat شما قرار می‌گیرد. هر ارسال یک پیوند مستقیم به گفتگو هم برمی‌گرداند و می‌توانید آن را با ایمیل به یک کارشناس واگذار کنید.

آیا می‌توانم به شماره‌ای که هنوز مشتری نیست ارسال کنم؟

بله. اگر شمارهٔ تلفن هنوز مشتری نباشد، مشتری با نامی که می‌فرستید ساخته می‌شود.

هزینهٔ پیام‌های قالب چقدر است؟

هزینهٔ هر پیام مانند هر پیام قالب دیگری که از MonoChat ارسال می‌شود محاسبه می‌شود. Meta قیمت قالب‌ها را بر اساس دسته و کشور گیرنده تعیین می‌کند؛ برای برآورد یک ارسال از ماشین‌حساب هزینهٔ ارسال گروهی واتس‌اپ استفاده کنید.

بررسی کلی​

ویژگی‌های برجسته​

نصب و راه‌اندازی​

قابلیت‌ها​

فهرست‌کردن قالب‌ها​

ارسال قالب​

واگذاری به کارشناس​

سرایند رسانه‌ای​

پیوند گفتگو​

خطاهای روشن​

پیش از شروع​

مرجع API​

1. فهرست‌کردن قالب‌ها​

2. ارسال قالب​

3. آپلود رسانه برای سرایند​

نمونه: قالبی با سرایند تصویر​

خطاها​

تصاویر محیط برنامه​

سؤالات متداول​

آیا WhatsApp Template API رابط کاربری دارد؟​

پیش از استفاده به چه چیزی نیاز دارم؟​

وقتی مشتری پاسخ می‌دهد چه می‌شود؟​

آیا می‌توانم به شماره‌ای که هنوز مشتری نیست ارسال کنم؟​

هزینهٔ پیام‌های قالب چقدر است؟​

مطالب مرتبط​