WhatsApp Template API

د پراختیا کوونکو API

له خپلو سیستمونو څخه په یو API کال سره تصویب شوي WhatsApp ټیمپلیټونه ولیږئ؛ بیا خبرې اترې په MonoChat کې دوام کوي.

• WhatsApp
• REST API
• یوازې API

له MonoStore څخه نصب کړئپه monochat.ai کې یې وګورئ

لنډه کتنه

WhatsApp Template API ستاسو CRM، ERP، د بریښنایي سوداګرۍ سایټ یا هر بیکینډ ته اجازه ورکوي چې د MonoChat له لارې پیرودونکي ته تصویب شوی WhatsApp ټیمپلیټ پیغام ولیږي. یوه غوښتنه دا ټاکي چې د کوم WhatsApp شمېرې څخه لیږل کیږي، د پیرودونکي د تلیفون شمېره، ټیمپلیټ او د هغه متغیرونه.

کله چې پیرودونکی ځواب ورکړي، خبرې اترې د نورو په څېر ستاسو MonoChat انباکس ته راځي. اپ خپل سکرینونه نلري: هر څه د درې API اینډپوینټونو له لارې کیږي.

مهمې ځانګړتیاوې

• یو API کال. ټیمپلیټ د نوم او ژبې په اساس ولیږئ، د سرلیک، متن، تڼۍ او کاروسل متغیرونه ستاسو له معلوماتو ډک شوي.
• مستقیم چټ ته. هر لیږل د خبرو اترو ID او په MonoChat کې ورته مستقیم لینک بیرته ورکوي.
• نوي پیرودونکي هرکلی. که د تلیفون شمېره لا پیرودونکی نه وي، پیرودونکی ستاسو د لیږل شوي نوم سره جوړیږي.

نصب او تنظیم

1. خپله WhatsApp Business شمېره MonoChat سره وصل کړئ او ډاډ ترلاسه کړئ چې تایید شوې ده او د Meta لخوا تصویب شوي ټیمپلیټونه لري.
2. WhatsApp Template API له تنظیمات › MonoStore › اپلیکېشنونه څخه نصب کړئ، یا د نصب لینک app.monochat.ai/apps/K6u29LpbwCHBozZ8o پرانیزئ. که د MonoChat حساب نلرئ، لینک تاسو ته اجازه درکوي لومړی نوملیکنه وکړئ او اپ ستاسو لپاره نصبوي.
3. د پروفایل › API ټوکنونه لاندې یو API ټوکن جوړ کړئ. ټوکن یوازې یو ځل ښودل کیږي، نو سمدلاسه یې کاپي کړئ.
4. خپل تصویب شوي ټیمپلیټونه او د هغوی متغیرونه لیدلو لپاره template/list.js کال کړئ.
5. خپل لومړی ټیمپلیټ لیږلو لپاره د پیرودونکي شمېرې او د متغیرونو ارزښتونو سره template/send.js کال کړئ.

یادښت

• هر پیغام د MonoChat څخه د لیږل شوي هر ټیمپلیټ پیغام په څېر بیل کیږي.
• د رسنۍ URLs باید تر هغه رسېدونکي پاتې شي چې WhatsApp فایل ترلاسه کړي.
• هغو پیرودونکو ته ولیږئ چې ستاسو څخه د پیغام اخیستو موافقه کړې ده: WhatsApp کولی شي هغه شمېرې محدودې کړي چې پیغامونه یې بلاک یا راپور شوي وي.

ځانګړتیاوې

ټیمپلېټونه لیست کړئ

د WhatsApp شمېرې تصویب شوي ټیمپلیټونه، د هغوی ژبه، کټګورۍ، حالت او متغیرونه، څو ستاسو سیستم پوه شي چې څه لیږلی شي.

ټیمپلېټ ولیږئ

د ټیمپلیټ نوم او ژبې له مخې، د سرلیک، متن، تڼۍ او کاروسل متغیرونو سره. ورکه شوی ارزښت لیږل ودروي، نو هیڅ نیمګړی ډک شوی شی پیرودونکي ته نه رسیږي.

اجنټ ته وسپارئ

د یو اجنټ ایمیل ورکړئ او خبرې اترې د هغه په نوم پرانیستل کیږي.

د رسنۍ سرلیکونه

لنډمهاله د پورته کولو اسناد ترلاسه کړئ، یو انځور، ویډیو یا سند د MonoChat په ذخیره کې کېږدئ او د هغه URL د ټیمپلیټ د سرلیک په توګه وکاروئ.

د خبرو اترو لینک

هر لیږل د ناستې ID، د پیغام ID او یو لینک بیرته ورکوي چې په MonoChat کې خبرې اترې پرانیزي.

روښانه تېروتنې

ناکامه کال وايي چې څه ناسم شول، د بیلګې په توګه “Channel not found” یا “Variable missing”.

مخکې له پیل

• ستاسو WhatsApp Business شمېره له MonoChat سره وصل او تایید شوې ده. چینلونه وګورئ.
• هغه ټیمپلیټونه چې غواړئ ولیږئ د Meta لخوا تصویب شوي دي. ټیمپلیټونه هغه لار ده چې تاسو یې په ذریعه لومړی لیکئ، یا پیرودونکي ته د 24 ساعتونو کړکۍ بهر رسیږئ. د ټیمپلېټ پیغامونه وګورئ.
• تاسو د پروفایل › 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	ستاسو د WhatsApp د یوې شمېرې ټیمپلیټونه د متغیرونو سره لیست کوي.
template/send.js	پیرودونکي ته ټیمپلیټ لیږي او د خبرو اترو لینک بیرته ورکوي.
upload/get-token.js	د سرلیک انځور، ویډیو یا سند لپاره لنډمهاله د پورته کولو اسناد ورکوي.

د تلیفون شمېرې تل د هیواد کوډ سره او پرته له + لیکل کیږي، د بیلګې په توګه 905334445566. بریالی کال 200 ځواب ورکوي او د اینډپوینټ معلومات د result لاندې وي.

1. ټیمپلېټونه لیست کړئ

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

د ورکړل شوې WhatsApp Business شمېرې هر ټیمپلیټ لیست کوي: نوم، د ژبې کوډ، کټګورۍ، برخې (سرلیک، متن، پښتۍ، تڼۍ)، د متغیرونو ډولونه او د تصویب حالت.

ساحه	اړینه	توضیح
phoneNumber	هو	په MonoChat کې ستاسو WhatsApp Business شمېره، د هیواد کوډ سره، پرته له +.
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: د WhatsApp کټګورۍ (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	هو	هغه WhatsApp Business شمېره چې له هغې لیږل کیږي. باید له MonoChat سره وصل او تایید شوې وي.
templateMessageName	هو	د ټیمپلیټ name، دقیقاً لکه لیست چې بیرته ورکوي.
languageCode	هو	د ټیمپلیټ ژبه، لکه لیست چې بیرته ورکوي (د بیلګې په توګه tr-TR).
customerPhoneNumber	هو	د پیرودونکي WhatsApp شمېره.
variables	کله چې ټیمپلیټ یې لري	د ټیمپلیټ د متغیرونو ارزښتونه (لاندې وګورئ).
customerFirstName, customerLastName	نه	هغه وخت کارول کیږي چې پیرودونکی په MonoChat کې نوی وي.
agentEmailAddress	نه	خبرې اترې د دې ایمیل لرونکي اجنټ ته سپاري.

متغیرونه. د variables لړۍ هر توکی یو type او د parameters لیست لري، د ټیمپلیټ د ځای‌ساتونکو په ترتیب:

type	parameters
HEADER	د سرلیک د متن متغیر، یا د سرلیک انځور، ویډیو یا سند عمومي URL.
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: د خبرو اترو ID.
• messageId: په MonoChat کې د پیغام ID. د هغه د رسولو او لوستلو حالت د نورو پیغامونو په څېر په چټ کې ښکاري.

په ټیمپلیټونو کې رسنۍ. WhatsApp د سرلیک رسنۍ له هغه URL څخه ډاونلوډوي چې تاسو یې ورکوئ، نو URL باید معتبر او عامه رسېدونکی وي. هغه لینکونه چې ننوتلو ته اړتیا لري کار نه کوي. که تاسو فایل د upload/get-token.js له لارې پورته کړی وي، د هغه ځواب څخه جوړ شوی د فایل URL وکاروئ.

3. د سرلیک لپاره رسنۍ پورته کړئ

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

کله چې د ټیمپلیټ سرلیک انځور، ویډیو یا سند وي، فایل یوې عامې پتې ته اړتیا لري چې WhatsApp ترې ډاونلوډ کړي. دا اینډپوینټ تاسو ته لنډمهاله اجازه درکوي چې فایل د 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	د هغه یوې لارې لپاره یوازې د پورته کولو اسناد، 15 دقیقې معتبر.
baseUrl	د ذخیرې عامه پته. د فایل URL baseUrl + / + path دی.

فایل سمدلاسه د هر S3 کلاینټ سره د دې اسنادو په کارولو پورته کړئ، بیا کله چې ټیمپلیټ لیږئ د هغه URL د HEADER پارامېټر په توګه ورکړئ. ډیر لوی فایلونه یا هغه بڼې چې WhatsApp یې ملاتړ نه کوي (دا عام انځور، ویډیو او PDF بڼې مني) ناکامیږي.

بیلګه: د انځور سرلیک سره ټیمپلیټ

ووایئ چې تاسو یو تصویب شوی ټیمپلیټ new_product_announcement لرئ چې د انځور سرلیک او دوه د متن متغیره (د پیرودونکي نوم او د محصول نوم) لري، او غواړئ پیرودونکي ته یې ولیږئ.

1. ټیمپلیټونه لیست کړئ. خپلې WhatsApp شمېرې سره template/list.js کال کړئ او new_product_announcement ومومئ. د هغه برخې په سرلیک کې یو IMAGE متغیر او په متن کې دوه TEXT متغیره ښيي.
2. انځور پورته کړئ. upload/get-token.js د { "fileName": "urun.jpg" } سره کال کړئ، فایل د بیرته ورکړل شویو اسنادو سره پورته کړئ او د هغه URL له baseUrl او path څخه جوړ کړئ.
3. ټیمپلیټ ولیږئ. template/send.js د فایل URL سره د HEADER پارامېټر په توګه او ["Ayşe", "XYZ Telefon"] د BODY پارامېټرونو په توګه کال کړئ ({{1}} → Ayşe، {{2}} → XYZ Telefon). که ټیمپلیټ د تڼۍ متغیرونه درلودل، تاسو به یو BUTTONS توکی په همدې ډول اضافه کړئ.
4. چټ پرانیزئ. د ځواب url خبرې اترې پرانیزي؛ کله چې پیرودونکی ځواب ورکړي، دا ستاسو په MonoChat انباکس کې دوام کوي.

تېروتنې

ناکام کال د تېروتنې حالت او یو پیغام سره ځواب ورکوي چې وايي څه ناسم شول. دا پیغامونه په خپل سیستم کې ثبت کړئ او چېرته چې اړتیا وي خپلو کاروونکو ته یو معنادار پیغام وښیاست.

پیغام	لامل
phoneNumber field is required	template/list.js پرته له phoneNumber کال شوی.
phoneNumber, templateMessageName, customerPhoneNumber fields are required	د template/send.js یوه اړینه ساحه نشته.
Channel not found	phoneNumber ستاسو د کاري ځای WhatsApp شمېره نه ده.
Channel is not verified	WhatsApp شمېره وصل ده خو تایید شوې نه ده.
Template message not found	په شمېره کې د دې نوم او ژبې تصویب شوی ټیمپلیټ نشته. املا او languageCode وګورئ.
Template message is not approved	ټیمپلیټ شته خو د Meta لخوا تصویب شوی نه دی.
Variable missing: …	variables د ټیمپلیټ سره نه سمون خوري، د بیلګې په توګه ټیمپلیټ دوه د متن ارزښتونه غواړي او تاسو یو لیږلی.
Agent user not found	په agentEmailAddress کې د ایمیل اجنټ نشته.
Customer Channel not found	د پیرودونکي WhatsApp پیژندنه نه شوه جوړیدی یا موندل کېدی.

د 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 یا د WhatsApp چمتو کوونکي کې یو ناڅاپي ستونزه، یا د WhatsApp له لوري رد کول (شمېره په WhatsApp کې نشته، پیرودونکي بلاک کړی یاست، د کیفیت یا نرخ محدودیتونه). وروسته بیا هڅه وکړئ او که دوام وکړي د MonoChat ملاتړ سره اړیکه ونیسئ.

سکرین شاټونه

د MonoChat له لارې په یو API کال سره د CRM، ERP یا بریښنایي سوداګرۍ سیستم څخه یو تصویب شوی WhatsApp ټیمپلیټ لیږلد تصویب شوو WhatsApp ټیمپلیټونو لیست د هغوی د متغیرونو سرهنوې شمېرې ته د ټیمپلیټ لیږل پیرودونکی په اتومات ډول جوړويیو ټیمپلیټ په څو ژبو لیږل شوید انځور، ویډیو، سند او PDF سرلیکونو سره ټیمپلیټونه

پوښتنې او ځوابونه

ایا WhatsApp Template API یوزر انټرفېس لري؟

نه. دا یوازې د API اپ دی چې درې اینډپوینټونه لري: د ټیمپلیټونو لیست، یو ټیمپلیټ لیږل او د رسنۍ سرلیکونو لپاره د پورته کولو اسناد ترلاسه کول.

له کارولو مخکې څه ته اړتیا لرم؟

یوه WhatsApp Business شمېره چې له MonoChat سره وصل او تایید شوې وي، د Meta لخوا تصویب شوي ټیمپلیټونه، او د پروفایل › API ټوکنونه څخه یو API ټوکن.

کله چې پیرودونکی ځواب ورکړي څه کیږي؟

خبرې اترې د نورو په څېر ستاسو MonoChat انباکس ته راځي. هر لیږل د خبرو اترو مستقیم لینک هم بیرته ورکوي، او تاسو کولی شئ د ایمیل له لارې یې اجنټ ته وسپارئ.

ایا زه داسې شمېرې ته لیږلی شم چې لا پیرودونکی نه دی؟

هو. که د تلیفون شمېره لا پیرودونکی نه وي، پیرودونکی ستاسو د لیږل شوي نوم سره جوړیږي.

د ټیمپلېټ پیغامونو لګښت څومره دی؟

هر پیغام د MonoChat څخه د لیږل شوي هر ټیمپلیټ پیغام په څېر بیل کیږي. Meta ټیمپلیټونه د کټګورۍ او د ترلاسه کوونکي د هیواد له مخې بیه ټاکي؛ د یو لیږلو د لګښت اټکل لپاره د WhatsApp د ډله‌ییز پیغام لګښت حسابګر وکاروئ.

اړوند

• Session Link
• Bulk Template Message API
• د ټیمپلېټ پیغامونه
• د MonoStore اپونه