अपना वर्कस्पेस संचालित करें
अपने कोड से।

§ 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 तरफ कुछ होने पर पुश सूचनाओं के लिए — एक नया ग्राहक संदेश, एक बातचीत बंद होना, एक एजेंट का जुड़ना — सेटिंग्स → वेबहुक में आउटबाउंड वेबहुक कॉन्फ़िगर करें।

POST /api/v1/conversations/:id/messages के माध्यम से भेजे गए संदेश message.created वेबहुक भी फायर करते हैं, इसलिए यदि आपके पास संदेश भेजने वाला और सुनने वाला दोनों इंटीग्रेशन हैं, तो आप अपने स्वयं के लेखन को वेबहुक चैनल के माध्यम से वापस आते देखेंगे।

§ 08रेट लिमिट्स

प्रत्येक टेनेंट को प्रति पथ प्रति मिनट 240 अनुरोध तक मिलते हैं, उस टेनेंट की सभी कुंजियों में साझा। सीमा पर पहुँचना Retry-After हेडर के साथ 429 लौटाता है।

यदि आपके इंटीग्रेशन को वास्तव में उच्च सीमा की आवश्यकता है (बल्क इम्पोर्ट, मास-मैसेज-आउट), तो सपोर्ट को ईमेल करें — हम इसे आपके टेनेंट के लिए बढ़ा देंगे।