اپنا ورک اسپیس چلائیں
اپنے کوڈ سے۔

§ 00REST API کیا ہے

EasyLiveChat /api/v1/* پر REST API فراہم کرتا ہے تاکہ بیرونی کوڈ — آپ کا اپنا بیک اینڈ، CRM انٹیگریشن، Zapier یا n8n فلو، مائیگریشن اسکرپٹ — کسی ایجنٹ کے لاگ ان ہوئے بغیر آپ کا ورک اسپیس پڑھ اور لکھ سکے۔ ہر کال ڈیش بورڈ میں بنی اور آپ کے ٹیننٹ تک محدود API کلید سے تصدیق ہوتی ہے۔

اگر آپ نے کبھی Stripe، Slack یا GitHub API کال کیا ہے تو یہ اسی طرح کام کرتا ہے: Authorization ہیڈر میں طویل-مدتی خفیہ ٹوکن، JSON درخواست اور جواب باڈی، اور پیش گو HTTP اسٹیٹس کوڈ۔

API کلید کبھی 2FA یا پاس ورڈ نہیں رکھتی — یہی پوری بات ہے۔ یہ ایک سند ہے جسے آپ کسی دوسرے سافٹ ویئر میں شامل کرتے ہیں تاکہ وہ آپ کے ٹیننٹ کی جانب سے صرف ان اسکوپس کے ساتھ کام کرے جو آپ نے دیے ہیں۔

§ 01پلان کی دستیابی

REST API ہر ادا شدہ پلان پر دستیاب ہے اور 14 دن کے ٹرائل کے دوران ان لاک ہے۔ فی-کال بلنگ نہیں ہے۔

ٹرائل ختم ہونے پر API صرف-پڑھنے کے موڈ پر چلا جاتا ہے — جب تک ورک اسپیس اپ گریڈ نہیں ہوتا، رائٹس 402 لوٹاتے ہیں۔ پڑھنا کام کرتا رہتا ہے تاکہ آپ کی تاریخی برآمدات کبھی نہ ٹوٹیں۔

§ 02تصدیق

ایک کلید بنائیں https://app.livechattools.com/settings/api-keys. وہی کم ترین اسکوپس منتخب کریں جن کی انٹیگریشن کو واقعی ضرورت ہو۔ آپ کسی بھی وقت اسی صفحے سے کلید منسوخ کر سکتے ہیں — یہ فوری کام بند کر دیتی ہے، آپ کے ایجنٹس کے ڈیش بورڈ یا موبائل لاگ اِن پر کوئی اثر نہیں۔

ہر درخواست پر کلید بھیجیں، Bearer ٹوکن کے طور پر یا x-api-key کے ذریعے:

Authorization: Bearer plk_<your-key>
# — or, equivalently —
x-api-key: plk_<your-key>

اسے کہیں بھی جوڑنے سے پہلے تصدیق کر لیں کہ کلید کام کرتی ہے — /me آپ کے اسکوپس اور ٹیننٹ کو لوٹاتا ہے:

curl https://api.livechattools.com/api/v1/me \
  -H "Authorization: Bearer plk_<your-key>"

خام کلید صرف بنانے کے وقت ایک بار دکھائی جاتی ہے۔ کھو گئی؟ اسے منسوخ کریں اور نئی بنائیں — اصل قیمت بحال کرنے کا کوئی طریقہ نہیں۔

§ 03اسکوپس

اسکوپس کی ہر درخواست پر جانچ ہوتی ہے۔ صرف :read اسکوپس والی کلید کبھی غلطی سے ڈیٹا تبدیل نہیں کر سکتی — صرف-پڑھنے والے ڈیش بورڈ، BI برآمدات، یا اینالٹکس پائپ لائنز کے لیے مفید۔

کم سے کم اختیار کا اصول — ہر انٹیگریشن کے لیے الگ کلید۔ آپ کی رپورٹنگ پائپ لائن پر لیک ہونے والی صرف-پڑھنے والی کلید، آپ کے پورے اسٹیک میں شیئر کی گئی ایک "سب-کچھ-کرنے" والی کلید سے بہت کم نقصان دہ ہے۔

§ 04اینڈ پوائنٹس

ہر راستہ /api/v1 سے شروع ہوتا ہے۔ جوابات JSON ہیں۔ اوقات ISO 8601 UTC میں ہیں۔

GET /api/v1/me

کلید کی شناخت اور ٹیننٹ لوٹاتا ہے۔ کوئی اسکوپ درکار نہیں — کنکشن ٹیسٹ کے لیے مفید۔

curl https://api.livechattools.com/api/v1/me \
  -H "Authorization: Bearer plk_<key>"

{
  "apiKeyId": "ck...",
  "scopes": ["conversations:read","messages:write"],
  "tenant": { "id": "...", "name": "Acme", "slug": "acme", "planTier": "GROWTH" }
}

GET /api/v1/conversations

گفتگو کو نئے سے پہلے فہرست کریں۔ تمام فلٹرز اختیاری ہیں۔

• ?status= OPEN · SNOOZED · CLOSED
• ?channel= WIDGET · WHATSAPP · TELEGRAM · MESSENGER · INSTAGRAM
• ?limit= 1–200، طے شدہ 50
• ?cursor= پچھلے صفحے کی آخری قطار کا id

curl "https://api.livechattools.com/api/v1/conversations?status=OPEN&limit=50" \
  -H "Authorization: Bearer plk_<key>"

{
  "data": [
    { "id":"...", "sourceChannel":"WHATSAPP", "status":"OPEN",
      "lastMessagePreview":"hi there", "lastMessageAt":"..." }
  ],
  "nextCursor": "..."
}

GET /api/v1/conversations/:id

ایک گفتگو اس کے رابطے کے ساتھ حاصل کریں۔

GET /api/v1/conversations/:id/messages

گفتگو کی پیجی نیشن شدہ پیغام کی تاریخ، نئے پہلے۔

curl "https://api.livechattools.com/api/v1/conversations/<id>/messages?limit=50" \
  -H "Authorization: Bearer plk_<key>"

POST /api/v1/conversations/:id/messages

گفتگو میں آؤٹ باؤنڈ پیغام بھیجیں۔ یہ مماثل چینل (ویجٹ، WhatsApp، Telegram، Messenger، Instagram) پر بالکل اسی طرح پہنچتا ہے جیسے انسانی ایجنٹ کا جواب۔

curl -X POST "https://api.livechattools.com/api/v1/conversations/<id>/messages" \
  -H "Authorization: Bearer plk_<key>" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Your order has shipped." }'

# → 201 Created
{ "message": { "id":"...", "senderType":"AGENT", "body":"Your order has shipped.", "createdAt":"..." } }

senderAgentId اختیاری ہے — اگر چھوڑ دیا جائے تو پیغام ورک اسپیس کے پہلے فعال OWNER یا ADMIN سے منسوب ہوتا ہے۔ جب آپ چاہتے ہیں کہ کوئی مخصوص بوٹ اکاؤنٹ گفتگو میں نظر آئے تو واضح id پاس کریں۔

PATCH /api/v1/conversations/:id

گفتگو کی حالت (OPEN · SNOOZED · CLOSED) یا اس کے سونپے گئے ایجنٹ کو اپ ڈیٹ کریں۔ اَن-تفویض کرنے کے لیے assignedAgentId: null پاس کریں۔

curl -X PATCH "https://api.livechattools.com/api/v1/conversations/<id>" \
  -H "Authorization: Bearer plk_<key>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "CLOSED" }'

GET /api/v1/contacts

ورک اسپیس میں رابطے فہرست کریں۔ ?q= نام، ای میل یا فون کے ساتھ ملاتا ہے۔

curl "https://api.livechattools.com/api/v1/contacts?q=acme" \
  -H "Authorization: Bearer plk_<key>"

§ 05پیجی نیشن

تمام لسٹ اینڈ پوائنٹس کرسر پیجی نیشن استعمال کرتے ہیں۔ جواب کی شکل:

{
  "data": [ /* up to ?limit= rows */ ],
  "nextCursor": "<id of last row>"   // or null when there are no more
}

اگلا صفحہ حاصل کرنے کے لیے، اگلی درخواست پر nextCursor کو ?cursor= کے طور پر پاس کریں۔ جب nextCursor null ہو تو آپ آخر تک پہنچ گئے۔

§ 06غلطیاں

غلطیاں ہمیشہ ایک ایرر کوڈ اور (جہاں مددگار ہو) قابلِ پڑھ پیغام کے ساتھ JSON باڈی لوٹاتی ہیں۔ HTTP اسٹیٹس معنی کی عکاسی کرتا ہے:

§ 07ویب ہکس (ساتھی)

REST API آپ کے شیڈول پر کھینچنے اور دھکیلنے کے لیے بہترین ہے۔ EasyLiveChat کی طرف کچھ ہونے پر پش نوٹیفکیشن کے لیے — نیا کسٹمر پیغام، گفتگو بند ہونا، ایجنٹ کا شامل ہونا — سیٹنگز ← Webhooks میں آؤٹ باؤنڈ ویب ہکس کنفیگر کریں۔

POST /api/v1/conversations/:id/messages کے ذریعے بھیجے گئے پیغامات message.created ویب ہک کو بھی فائر کرتے ہیں، تو اگر آپ کے پاس پیغام بھیجنے والی اور سننے والی دونوں انٹیگریشن ہیں، تو آپ اپنی رائٹس کو ویب ہک چینل سے واپس آتے دیکھیں گے۔

§ 08ریٹ لمٹس

ہر ٹیننٹ کو فی راستہ فی منٹ 240 درخواستیں ملتی ہیں، جو اس ٹیننٹ کی تمام کلیدوں میں مشترک ہیں۔ حد سے ٹکرانے پر Retry-After ہیڈر کے ساتھ 429 لوٹتا ہے۔

اگر آپ کی انٹیگریشن کو حقیقی طور پر زیادہ حد چاہیے (بلک امپورٹ، ماس میسیج آؤٹ)، تو سپورٹ کو ای میل کریں — ہم آپ کے ٹیننٹ کے لیے بڑھا دیں گے۔