REST API · EasyLiveChat

§ 00REST API چییە

EasyLiveChat لە /api/v1/* دا REST API دەردەخات بۆ ئەوەی کۆدی دەرەکی — بەکێندی خۆت، یەکگرتنی CRM، فلۆوی Zapier یان n8n، سکریپتی گواستنەوە — بێ ئەوەی ئەجێنتێکی مرۆڤ چووبێتە ژوورەوە، شوێنی کارکردنت بخوێنێتەوە و بنووسێت. هەموو بانگکردنێک بە کلیلێکی API دروستکراو لە داشبۆرد و بەستراو بە بەکارهێنەرت ڕاستدەکرێتەوە.

ئەگەر هەرگیز بانگی API ی Stripe یان Slack یان GitHub ت کردووە، ئەمە بەهەمان شێوە کاردەکات: تۆکنی نهێنی درێژ-تەمەن لە سەرپەڕەی 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سنوور (scopes)

سنوورەکان لە هەموو داواکارییەکدا پشکنین دەکرێن. کلیلێک کە تەنها سنووری :read ی هەیە، هەرگیز ناتوانێت بە هەڵە داتا بگۆڕێت — سوودبەخشە بۆ داشبۆردی تەنها-خوێندنەوە، هەناردەی BI، یان پایپلاینی تەحلیلات.

سنوور	ڕێگەدەدات
conversations:read	گفتوگۆکان و پەیامەکانیان لیست بکە و بیخوێنەوە.
conversations:write	گفتوگۆکان دابخە، بیانکەرەوە، یان دیسان دایانبنێ.
messages:read	مێژووی پەیامەکانی گفتوگۆیەک بخوێنەوە.
messages:write	وەک ئەجێنت پەیامێکی نوێ بنێرە.
contacts:read	پەیوەندیەکان لیست بکە و بگەڕێ.

بنەمای کەمترین دەسەڵات — کلیلی جیاواز بۆ هەر یەکگرتنێک. کلیلێکی تەنها-خوێندنەوەی دزراو لەسەر پایپلاینی ڕاپۆرتەکانت زیانی زۆر کەمترە لە یەک کلیلی "هەموو-شت-کار" کە لە سەرانسەری ستاکەکەت پارچە کراوە.

§ 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`

پەیامێکی دەرەوە بنێرە لە گفتوگۆیەکدا. هەروەک وەڵامێکی ئەجێنتێکی مرۆڤ بۆ کەناڵی هاوتای (ویجێت، واتساپ، تێلێگرام، مێسێنجەر، ئینستاگرام) پەخش دەکرێت.

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پەڕە-بەندی

هەموو خاڵە کۆتاییەکانی لیست پەڕە-بەندی بە cursor بەکاردەهێنن. شێوەی وەڵامەکە:

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

بۆ هێنانی پەڕەی دواتر، nextCursor وەک ?cursor= بنێرە لە داواکاری دواتردا. کاتێک nextCursor null بێت، گەیشتوویتە کۆتایی.

§ 06هەڵەکان

هەڵەکان هەمیشە لاشەی JSON دەگەڕێننەوە بە کۆدی هەڵە و (لە کاتی سوودبەخشدا) پەیامێکی خوێندنەوەی مرۆڤی. دۆخی HTTP واتاکە دەردەخات:

دۆخ	کۆد	واتا
401	UNAUTHENTICATED	کلیلی ون، نادروست، یان ڕەتکراوە.
402	TRIAL_EXPIRED	تاقیکردنەوە تەواو بوو — نووسینەکان بلۆککراون، خوێندنەوەکان هێشتا کاردەکەن.
403	FORBIDDEN	کلیلەکە دروستە بەڵام سنووری پێویستی ئەم خاڵە کۆتاییە نییە.
404	NOT_FOUND	گفتوگۆ، پەیوەندی، یان سەرچاوەی تر لە بەکارهێنەرت بوونی نییە.
400	INVALID_BODY	لاشەی داواکاری خانە پێویستەکان نییە یان جۆرە هەڵەکانی هەیە.
429	RATE_LIMITED	زۆر داواکاری — کشانەوە بکە و دوای چەند چرکەیەک هەوڵبدەرەوە.

§ 07Webhooks (هاوبەش)

REST API زۆر باشە بۆ کێشان و پاڵدان بەپێی پلانەکەت. بۆ ئاگادارکردنەوەی پاڵدان کاتێک شتێک لە لایەنی EasyLiveChat ڕوودەدات — پەیامێکی نوێی کڕیار، داخستنی گفتوگۆیەک، ئەجێنتێکی نوێ — webhookە دەرچووەکان لە ڕێکخستن ← Webhooks ڕێکبخە.

ئەو پەیامانەی لە ڕێگەی POST /api/v1/conversations/:id/messages دەنێریت webhook ی message.created یش دەکوژێنن، بۆیە ئەگەر یەکگرتنێکت بۆ ناردن و یەکێکی دیکەت بۆ گوێگرتن هەبێت، نووسینەکانی خۆت لە ڕێگەی کەناڵی webhook ەوە دەبینیتەوە.

§ 08سنوورەکانی نرخ

هەر بەکارهێنەرێک تا 240 داواکاری لە خولەکدا بۆ هەر ڕێگەیەک دەستدەکەوێت، لە نێوان هەموو کلیلەکانی ئەو بەکارهێنەردا بەشدارە. گەیشتن بە سنوور 429 دەگەڕێنێتەوە لەگەڵ سەرپەڕەی Retry-After.

ئەگەر یەکگرتنەکەت بە ڕاستی پێویستی بە سنوورێکی بەرزتر هەیە (هاوردەی بەکۆمەڵ، ناردنی بەکۆمەڵ)، ئیمەیڵ بۆ پشتگیری بنێرە — بۆ بەکارهێنەرەکەت بەرزی دەکەینەوە.

گۆڕانکارییەک پێشنیار بکە