POST/api/public/widget/message

وزیٹر کا پیغام چیٹ بوٹ کو بھیجتا ہے اور اس کا جواب واپس دیتا ہے – چیٹ ویجٹ کا مرکزی اینڈ پوائنٹ۔

`widget_code`، `message`، `visitor_id` اور – دوسرے پیغام سے – پچھلے جواب سے `session_id` بھیجیں۔ نئی گفتگو کی پہلی کال پر `session_id` خالی چھوڑیں یا اسے `null` سیٹ کریں۔ جواب میں آبجیکٹ `data` میں `session_id`، جواب کا متن `response` اور بوقتِ ضرورت بٹن (`buttons`)، پروڈکٹ تجاویز (`products`) اور گفتگو کی حالت (`state`) شامل ہوتے ہیں۔ ہیڈر `X-Widget-Token` ایمبیڈ ٹوکن اور `widget_code` کے ساتھ ضروری ہیں۔ اگر ٹوکن موجود نہ ہو، سرور 401 `WIDGET_TOKEN_MISSING` کے ساتھ جواب دیتا ہے، اگر غلط ہو تو 401 `WIDGET_TOKEN_INVALID`؛ غیر منظور شدہ ڈومینز سے کالز کو 403 `WIDGET_ORIGIN_DENIED` اور غیر فعال ویجٹ کو 404 `WIDGET_DISABLED` ملتا ہے۔ اگر `visitor_id` موجود نہ ہو تو سرور 400 `VISITOR_ID_REQUIRED` کے ساتھ جواب دیتا ہے۔ یہ کال idempotent نہیں ہے: ہر بھیجنے سے ایک اور وزیٹر پیغام اور ایک اور جواب بنتا ہے۔ جب تک درخواست جاری ہو ان پٹ کو لاک کریں اور اسے خودکار طور پر دہرائیں نہیں۔

جائزہ

کال: POST /api/public/widget/message۔ یہ اینڈپوائنٹ Zentor App کی API کے گروپ “چیٹ ویجٹ” سے تعلق رکھتا ہے۔ اس کے لیے ایک درست ویجیٹ ایمبیڈ ٹوکن درکار ہے۔ یہ کال idempotent نہیں ہے: ہر کامیاب کال عمل کو دوبارہ متحرک کرتی ہے۔ لازمی پیرامیٹرز: widget_code (باڈی), message (باڈی), visitor_id (باڈی)۔ اختیاری پیرامیٹرز: session_id (باڈی)۔ دستاویزی ایرر کیسز: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED۔ نیچے دیا گیا نمونہ جواب JSON فارمیٹ میں کامیاب جواب کی ساخت دکھاتا ہے۔

تصدیقِ شناخت اور تحفظ

ویجیٹ ایمبیڈ ٹوکن (ہیڈر X-Widget-Token) + Origin کی منظوری کی فہرست

Idempotent (دہرانے پر یکساں اثر): نہیں

پیرامیٹرز

widget_code(body, string، ضروری)— آپ کے ایمبیڈ کوڈ سے ویجٹ کوڈ
message(body, string، ضروری)— وزیٹر کے پیغام کا متن
visitor_id(body, string، ضروری)— وزیٹر آئی ڈی جو ویجٹ تیار کرتا ہے اور براؤزر میں محفوظ کرتا ہے
session_id(body, string)— پچھلے جواب سے سیشن آئی ڈی؛ نئی گفتگو کی پہلی کال پر خالی یا `null`

مثالی Request

{"widget_code":"...","message":"سلام، Zentor App کیا کر سکتی ہے؟","visitor_id":"<UUID یا کلائنٹ کی تیار کردہ ID>"}

مثالی Response

{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}

خرابی کے کوڈز

401 WIDGET_TOKEN_MISSING — ہیڈر `X-Widget-Token` موجود نہیں ہے۔
401 WIDGET_TOKEN_INVALID — ایمبیڈ ٹوکن ویجٹ کوڈ سے میل نہیں کھاتا۔
400 VISITOR_ID_REQUIRED — فیلڈ `visitor_id` موجود نہیں ہے۔

تصدیق شدہ طرزِ عمل

ایک درست پیغام چیٹ بوٹ کے جواب کے ساتھ 200 واپس دیتا ہے؛ غائب یا غلط ٹوکن اور غائب `visitor_id` دستاویزی خرابی کوڈز دیتے ہیں۔

چیٹ ویجٹ

GET /api/public/widget/healthویجٹ سروس کی سادہ دستیابی چیک۔GET /api/public/widget/config/:widget_codeبراؤزر میں ابتدائی کاری کے لیے ویجٹ کی عوامی کنفیگریشن (ڈسپلے نام، خوش آمدید پیغام، ڈیزائن، زبان، صوتی سہولت) واپس کرتا ہے۔GET /api/public/widget/historyویجٹ گفتگو کی سابقہ پیغام تاریخ لوڈ کرتا ہے، مثلاً صفحے کو دوبارہ لوڈ کرنے کے بعد۔POST /api/public/widget/pollایک وقت کے بعد موصول ہونے والے پیغامات بازیافت کرتا ہے – مثلاً کسی ملازم کا جواب جس نے گفتگو سنبھالی ہو۔POST /api/public/widget/ratingکسی گفتگو کے بارے میں وزیٹر کی ریٹنگ محفوظ کرتا ہے (مفید یا غیر مفید)۔POST /api/public/widget/trackویجٹ کا ایک گمنام استعمال واقعہ ریکارڈ کرتا ہے (مثلاً "ویجٹ کھلا") ڈیش بورڈ تجزیات کے لیے۔POST /api/public/widget/voice-transcribeوزیٹر کی صوتی ریکارڈنگ کو متن میں تبدیل کرتا ہے (صوتی ان پٹ)، بشرطیکہ آواز کی سہولت ویجٹ کے لیے فعال ہو۔POST /api/public/widget/voice-speakمتن کو بولے گئے الفاظ میں تبدیل کرتا ہے (ویجٹ میں آواز کی آؤٹ پٹ)، بشرطیکہ آواز کی سہولت فعال ہو۔

متعلقہ مضامین

← چیٹ ویجٹ