مین مواد پر جائیں

WhatsApp Template API

WhatsApp Template API icon
ڈیولپر API

اپنے سسٹمز سے ایک API کال کے ذریعے منظور شدہ WhatsApp ٹیمپلیٹس بھیجیں؛ پھر گفتگو MonoChat میں جاری رہتی ہے۔

  • WhatsApp
  • REST API
  • صرف API

جائزہ​

WhatsApp Template API آپ کے CRM، ERP، ای کامرس سائٹ یا کسی بھی بیک اینڈ کو MonoChat کے ذریعے گاہک کو منظور شدہ WhatsApp ٹیمپلیٹ میسج بھیجنے دیتا ہے۔ ایک درخواست میں بتایا جاتا ہے کہ کس WhatsApp نمبر سے بھیجنا ہے، گاہک کا فون نمبر، ٹیمپلیٹ اور اس کے ویری ایبلز۔

جب گاہک جواب دیتا ہے تو گفتگو کسی بھی دوسری گفتگو کی طرح آپ کے MonoChat ان باکس میں آ جاتی ہے۔ ایپ کی اپنی کوئی اسکرین نہیں: سب کچھ تین API اینڈ پوائنٹس کے ذریعے ہوتا ہے۔

نمایاں خصوصیات​

  • ایک API کال۔ ٹیمپلیٹ کو نام اور زبان سے بھیجیں، ہیڈر، باڈی، بٹن اور کیروسل ویری ایبلز آپ کے ڈیٹا سے بھرے جاتے ہیں۔
  • سیدھا چیٹ میں۔ ہر بھیجنے پر گفتگو کی آئی ڈی اور 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 کی ترتیبات میں MonoStore ایپس کی فہرست، جس میں WhatsApp Template API شامل ہے
MonoStore میں WhatsApp Template API کی تفصیلات اور انسٹال کریں بٹن
نوٹ
  • ہر میسج کا بل MonoChat سے بھیجے گئے کسی بھی ٹیمپلیٹ میسج کی طرح بنتا ہے۔
  • میڈیا URLs اس وقت تک قابل رسائی رہنے چاہئیں جب تک WhatsApp فائل حاصل نہ کر لے۔
  • صرف ان گاہکوں کو بھیجیں جنہوں نے آپ سے پیغامات وصول کرنے پر رضامندی دی ہو: جن نمبروں کے پیغامات بلاک یا رپورٹ کیے جائیں ان پر WhatsApp پابندی لگا سکتا ہے۔

خصوصیات​

ٹیمپلیٹس کی فہرست​

کسی WhatsApp نمبر کے منظور شدہ ٹیمپلیٹس، ان کی زبان، زمرہ، اسٹیٹس اور ویری ایبلز کے ساتھ، تاکہ آپ کے سسٹم کو معلوم ہو کہ وہ کیا بھیج سکتا ہے۔

ٹیمپلیٹ بھیجیں​

ٹیمپلیٹ کے نام اور زبان سے، ہیڈر، باڈی، بٹن اور کیروسل ویری ایبلز کے ساتھ۔ کوئی قدر غائب ہو تو بھیجنا رک جاتا ہے، اس لیے ادھورا بھرا ہوا کچھ بھی گاہک تک نہیں پہنچتا۔

ایجنٹ کو تفویض کریں​

کسی ایجنٹ کا ای میل دیں اور گفتگو اس کے نام پر کھل جاتی ہے۔

میڈیا ہیڈرز​

مختصر مدت کی اپ لوڈ اسناد حاصل کریں، MonoChat کے اسٹوریج پر تصویر، ویڈیو یا دستاویز رکھیں اور اس کا URL ٹیمپلیٹ کے ہیڈر کے طور پر استعمال کریں۔

ہر بھیجنے پر سیشن آئی ڈی، میسج آئی ڈی اور ایک لنک ملتا ہے جو MonoChat میں گفتگو کھولتا ہے۔

واضح خرابی کے پیغامات​

ناکام کال بتاتی ہے کہ کیا غلط ہوا، مثلاً “Channel not found” یا “Variable missing”۔

شروع کرنے سے پہلے​

  • آپ کا WhatsApp Business نمبر MonoChat سے جڑا ہوا اور تصدیق شدہ ہے۔ دیکھیں چینلز۔
  • جو ٹیمپلیٹس آپ بھیجنا چاہتے ہیں وہ Meta سے منظور شدہ ہیں۔ ٹیمپلیٹس کے ذریعے آپ پہلے لکھتے ہیں، یا 24 گھنٹے کی ونڈو کے باہر کسی گاہک تک پہنچتے ہیں۔ دیکھیں ٹیمپلیٹ میسجز۔
  • آپ کے پاس پروفائل › API ٹوکنز سے ایک API ٹوکن ہے۔ دیکھیں API ٹوکنز۔
  • آپ اپنا ٹیننٹ سلگ جانتے ہیں: آپ کے MonoChat ایڈریس میں /tenants/ کے بعد کا حصہ۔ https://app.monochat.ai/tenants/mybusiness میں سلگ mybusiness ہے۔

API ریفرنس​

ایپ کی اپنی کوئی اسکرین نہیں۔ سب کچھ تین اینڈ پوائنٹس کے ذریعے ہوتا ہے، ہر ایک JSON باڈی کے ساتھ ایک POST:

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: وہ حصے جن سے ٹیمپلیٹ بنا ہے۔
جزوموادتفصیل
HEADERIMAGE, VIDEO, DOCUMENT یا ٹیکسٹمیڈیا کے لیے format دیا جاتا ہے؛ ویری ایبلز variables کے تحت ہوتے ہیں۔
BODYویری ایبلز والا ٹیکسٹمیسج کی باڈی، جس میں {{1}}, {{2}} جیسے پلیس ہولڈرز ہوتے ہیں۔
FOOTERٹیکسٹعموماً اس میں ویری ایبلز نہیں ہوتے۔
BUTTONSURL، فوری جواب…بٹنوں کا ٹیکسٹ اور ان کے ویری ایبلز، اگر ہوں۔

اوپر کی مثال والے ٹیمپلیٹ کو ہیڈر کے لیے ایک تصویر اور باڈی کے لیے دو ٹیکسٹ (گاہک کا نام اور پروڈکٹ کا نام) درکار ہیں۔ فوٹر مقررہ ہے ("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 کی فہرست ہوتی ہے، جو ٹیمپلیٹ کے پلیس ہولڈرز کی ترتیب سے دی جاتی ہے:

typeparameters
HEADERہیڈر کا ٹیکسٹ ویری ایبل، یا ہیڈر کی تصویر، ویڈیو یا دستاویز کا عوامی URL۔
BODYباڈی کے {{1}}, {{2}}, … ترتیب سے۔
BUTTONSہر اس بٹن کے لیے ایک قدر جس میں ویری ایبل ہو (مثلاً URL بٹن کا ڈائنامک حصہ یا کوپن کوڈ)، بٹنوں کی ترتیب سے۔
CAROUSELparameters کے بجائے 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 میں میسج کی آئی ڈی۔ اس کی ڈیلیوری اور پڑھے جانے کی حالت چیٹ میں کسی بھی دوسرے میسج کی طرح نظر آتی ہے۔

ٹیمپلیٹس میں میڈیا۔ 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. تصویر اپ لوڈ کریں۔ { "fileName": "urun.jpg" } کے ساتھ upload/get-token.js کال کریں، واپس ملنے والی اسناد سے فائل اپ لوڈ کریں اور baseUrl اور path سے اس کا URL بنائیں۔
  3. ٹیمپلیٹ بھیجیں۔ فائل کے URL کو HEADER پیرامیٹر کے طور پر اور ["Ayşe", "XYZ Telefon"] کو BODY پیرامیٹرز کے طور پر دے کر template/send.js کال کریں ({{1}} ← Ayşe، {{2}} ← XYZ Telefon)۔ اگر ٹیمپلیٹ میں بٹن ویری ایبلز ہوتے تو آپ اسی طرح ایک BUTTONS آئٹم شامل کرتے۔
  4. چیٹ کھولیں۔ جواب کا url گفتگو کھولتا ہے؛ جب گاہک جواب دیتا ہے تو وہ آپ کے MonoChat ان باکس میں جاری رہتی ہے۔

خرابیاں​

ناکام کال خرابی کے اسٹیٹس اور ایک پیغام کے ساتھ جواب دیتی ہے جو بتاتا ہے کہ کیا غلط ہوا۔ ان پیغامات کو اپنے سسٹم میں لاگ کریں اور جہاں ضرورت ہو اپنے صارفین کو بامعنی پیغام دکھائیں۔

پیغاموجہ
phoneNumber field is requiredtemplate/list.js کو phoneNumber کے بغیر کال کیا گیا۔
phoneNumber, templateMessageName, customerPhoneNumber fields are requiredtemplate/send.js کا کوئی لازمی فیلڈ غائب ہے۔
Channel not foundphoneNumber آپ کے ورک اسپیس کا WhatsApp نمبر نہیں ہے۔
Channel is not verifiedWhatsApp نمبر جڑا ہوا ہے مگر تصدیق شدہ نہیں۔
Template message not foundنمبر پر اس نام اور زبان کا کوئی منظور شدہ ٹیمپلیٹ نہیں ہے۔ ہجے اور languageCode چیک کریں۔
Template message is not approvedٹیمپلیٹ موجود ہے مگر Meta سے منظور شدہ نہیں۔
Variable missing: …variables ٹیمپلیٹ سے مطابقت نہیں رکھتے، مثلاً ٹیمپلیٹ کو باڈی کی دو قدریں چاہییں اور آپ نے ایک بھیجی۔
Agent user not foundagentEmailAddress میں دی گئی ای میل کا کوئی ایجنٹ نہیں ہے۔
Customer Channel not foundگاہک کی WhatsApp شناخت بنائی یا تلاش نہیں کی جا سکی۔

HTTP اسٹیٹس کوڈز جو آپ کو نظر آ سکتے ہیں:

  • 401 Unauthorized: Authorization: Bearer <API_TOKEN> ہیڈر غائب ہے، یا ٹوکن غلط یا میعاد ختم شدہ ہے۔ اپنے اکاؤنٹ کا درست ٹوکن استعمال کریں۔
  • 403 Forbidden: ٹوکن کو اس ورک اسپیس یا ایپ تک رسائی نہیں ہے، مثلاً ٹیننٹ سلگ غلط ہے۔
  • 404 Not Found: اینڈ پوائنٹ کا ایڈریس غلط ہے۔ مکمل پاتھ /api/<slug>/custom-functions/template-app/api/... چیک کریں۔
  • 500 Internal Server Error: MonoChat یا WhatsApp فراہم کنندہ کی طرف کوئی غیر متوقع مسئلہ، یا WhatsApp کی طرف سے انکار (نمبر WhatsApp پر نہیں ہے، گاہک نے آپ کو بلاک کیا ہے، کوالٹی یا ریٹ کی حدیں)۔ بعد میں دوبارہ کوشش کریں اور اگر مسئلہ برقرار رہے تو MonoChat سپورٹ سے رابطہ کریں۔

اسکرین شاٹس​

اکثر پوچھے جانے والے سوالات​

کیا WhatsApp Template API کا یوزر انٹرفیس ہے؟​

نہیں۔ یہ صرف API پر مبنی ایپ ہے جس کے تین اینڈ پوائنٹس ہیں: ٹیمپلیٹس کی فہرست، ٹیمپلیٹ بھیجنا اور میڈیا ہیڈرز کے لیے اپ لوڈ اسناد حاصل کرنا۔

اسے استعمال کرنے سے پہلے مجھے کیا چاہیے؟​

MonoChat سے جڑا ہوا اور تصدیق شدہ WhatsApp Business نمبر، Meta سے منظور شدہ ٹیمپلیٹس، اور پروفائل › API ٹوکنز سے ایک API ٹوکن۔

جب گاہک جواب دیتا ہے تو کیا ہوتا ہے؟​

گفتگو کسی بھی دوسری گفتگو کی طرح آپ کے MonoChat ان باکس میں آ جاتی ہے۔ ہر بھیجنے پر گفتگو کا براہ راست لنک بھی ملتا ہے، اور آپ ای میل کے ذریعے اسے کسی ایجنٹ کو تفویض کر سکتے ہیں۔

کیا میں ایسے نمبر پر بھیج سکتا ہوں جو ابھی گاہک نہیں ہے؟​

جی ہاں۔ اگر فون نمبر ابھی گاہک نہیں ہے تو آپ کے بھیجے ہوئے نام سے گاہک بنا دیا جاتا ہے۔

ٹیمپلیٹ میسجز کی لاگت کیا ہے؟​

ہر میسج کا بل MonoChat سے بھیجے گئے کسی بھی ٹیمپلیٹ میسج کی طرح بنتا ہے۔ Meta ٹیمپلیٹس کی قیمت زمرے اور وصول کنندہ کے ملک کے مطابق طے کرتا ہے؛ کسی ارسال کی لاگت کا اندازہ لگانے کے لیے WhatsApp بلک میسجنگ کاسٹ کیلکولیٹر استعمال کریں۔