عوامی API اور ویب ہکس

REST API آپ کے CRM، ویب سائٹ کے بیک اینڈ یا اپنے بوٹ کو cenaly.com کے لیڈز اور مکالموں کے ساتھ اسی طرح کام کرنے دیتا ہے جیسے پینل کرتا ہے: کارڈ پڑھنا، خصوصیات بدلنا، ایونٹس بھیجنا، مکالموں میں جواب دینا۔ ویب ہکس اس کے برعکس خود آپ کے سرور کو نئے لیڈز، ایونٹس اور پیغامات کی اطلاع دیتے ہیں۔

شروع کرنے کے لیے کیا درکار ہے#

مرحلہ 1۔ کلید اور اختیارات#

1. انٹیگریشنز کھولیں اور صفحے کے اوپر API اور ویب ہکس پر کلک کریں۔
2. کلیدیں ٹیب میں کلید بنائیں پر کلک کریں، نام درج کریں («CRM»، «ویب سائٹ کا بیک اینڈ»، «Telegram بوٹ»)۔
3. اختیارات کا سیٹ منتخب کریں یا ایک ایک کر کے اختیارات نشان زد کریں، کئی برانچوں کی صورت میں — کلید کن برانچوں تک محدود ہے، اور مدت۔
4. خفیہ کوڈ cnk_… کاپی کریں۔ یہ صرف ایک بار دکھایا جاتا ہے: ہمارے پاس صرف اس کا فنگر پرنٹ (SHA-256) محفوظ رہتا ہے۔

سیٹس: CRM / بیک اینڈ (لیڈز، خصوصیات، ایونٹس، مکالموں اور سیگمنٹس کی خواندگی)، اپنا بوٹ (لیڈز پڑھتا ہے، مکالموں میں جواب دیتا ہے، لیڈز کو لکھتا ہے)، صرف خواندگی، سب کچھ۔

• اختیارات کلید کے اختیارات اور برانچیں فوری طور پر بدلتے ہیں — انٹیگریشن کام کرتی رہتی ہے۔
• دوبارہ جاری کریں نیا خفیہ کوڈ دیتا ہے؛ پرانا فوراً کام کرنا بند کر دیتا ہے، اختیارات اور لاگ برقرار رہتے ہیں۔
• منسوخ کریں — فوراً اور ہمیشہ کے لیے، اگلی درخواست کو 401 ملے گا۔

کلید Authorization: Bearer cnk_… ہیڈر سے بھیجی جاتی ہے (یا X-Api-Key: cnk_…)۔ اسے صرف سرور پر رکھیں — نہ براؤزر میں اور نہ موبائل ایپ میں۔

مرحلہ 2۔ پہلی درخواستیں#

KEY=cnk_ваш_ключ
API=https://api.cenaly.com/public-api/v1

# что умеет ключ: права, точки, лимит
curl -H "Authorization: Bearer $KEY" "$API/me"

# лиды, свежие сверху (20 на страницу)
curl -H "Authorization: Bearer $KEY" "$API/contacts?limit=20"

# поиск по имени, почте или телефону
curl -H "Authorization: Bearer $KEY" "$API/contacts?q=anna"

جواب ہمیشہ ایک لفافے میں ہوتا ہے:

{
  "meta": { "status": 200, "requestId": "…", "nextCursor": "WyIyMDI2LTEwLTA0…" },
  "data": { "total": 128, "contacts": [ { "id": "…", "status": "lead", "name": "Анна", "updatedAt": "2026-10-04T09:12:00Z" } ] }
}

اگلا صفحہ — وہی درخواست cursor=<meta.nextCursor> کے ساتھ؛ nextCursor نہ ہو تو مزید صفحات نہیں۔ خرابی — {"meta": {...}, "error": {"code": "…"}}۔

برانچ۔ اگر کلید کو ایک ہی برانچ تک رسائی ہو تو اسے بتانے کی ضرورت نہیں۔ اگر کئی ہوں — location=<برانچ کی id> شامل کریں (فہرست — GET /v1/locations)، ورنہ جواب 400 location_required آئے گا۔

آپ کے user_id کے ذریعے خصوصیات اور ایونٹس۔ ہمارے لیڈ کی id محفوظ رکھنا لازمی نہیں: ?by=user_id شامل کریں، اور پتہ آپ کا صارف شناخت کنندہ بن جائے گا۔ اس user_id والا لیڈ ابھی نہ ہو تو ہم اسے بنا دیں گے۔

# свойства: операции update_or_create, set_once, add, delete, append, union, exclude
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"ops":[{"op":"update_or_create","key":"$email","value":"anna@example.com"},
              {"op":"add","key":"orders","value":1},
              {"op":"union","key":"interests","value":"yoga"}]}' \
  "$API/contacts/u-1001/props?by=user_id"

# события пачкой (до 100), повтор с тем же id засчитывается один раз
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"events":[{"id":"ord-5531","userId":"u-1001","name":"order_paid","props":{"sum":45,"currency":"GEL"}}]}' \
  "$API/events"

# ответ в диалоге и смена статуса
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"text":"Здравствуйте! Заказ передан курьеру."}' "$API/conversations/<id>/reply"
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"status":"resolved"}' "$API/conversations/<id>/status"

تحریر اسی قطار سے گزرتی ہے جس سے پینل کی تبدیلیاں: تبدیلیاں سیکنڈوں میں لاگو ہوتی ہیں، اور user_id کے ذریعے تحریر کا جواب 202 ہوتا ہے pending کے ساتھ۔ لیڈ کے کارڈ میں تحریر کرنے والا «API: <کلید کا نام>» کے طور پر نظر آتا ہے۔

طریقے#

ہر طریقے کے فیلڈز، مثالیں اور ایرر کوڈز حوالہ جات میں موجود ہیں۔

مرحلہ 3۔ ویب ہکس#

ویب ہکس برانچ کی سطح پر ترتیب دیے جاتے ہیں: چیٹ → ترتیبات → ویب ہکس — https پتہ، واقعات اور دستخط کا خفیہ کوڈ۔ گفتگو کے واقعات (نئی گفتگو، نیا پیغام، حیثیت، درجہ بندی، لیبل) کے ساتھ لیڈ کے واقعات بھی شامل ہو گئے ہیں:

{
  "event": "lead.event_tracked",
  "deliveryId": "WD…",
  "at": "2026-10-04T09:12:03Z",
  "webhookId": "…",
  "locationId": "…",
  "contact": { "id": "…", "status": "user", "userId": "u-1001", "props": { "orders": 3 }, "tags": ["vip"] },
  "leadEvent": { "name": "order_paid", "at": "2026-10-04T09:12:00Z", "props": { "sum": 45 } }
}

لیڈ کا نام، ای میل اور فون نمبر صرف اسی صورت میں باڈی میں شامل ہوتے ہیں جب ویب ہک میں «مہمان کے روابط بھیجیں» کا چیک باکس فعال ہو۔ دستخط کی تصدیق — ویب ہک کے خفیہ کوڈ سے باڈی کا HMAC-SHA256:

# заголовок X-Meni-Signature: sha256=<hex>
echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET"

5 سیکنڈ کے اندر 2xx جواب دیں — ورنہ ترسیل دہرائی جائے گی؛ ناکامیوں کی طویل سیریز کے بعد ویب ہک بند ہو جاتا ہے، اور یہ ترتیبات میں نظر آتا ہے۔ نقل کو deliveryId سے چھانٹیں۔

پابندیاں#

• فی کلید 60 درخواستیں فی منٹ؛ اس سے زیادہ پر 429 اور Retry-After ہیڈر۔ باقی مقدار X-RateLimit-* میں۔
• فی صفحہ زیادہ سے زیادہ 200 ریکارڈز (بطور ڈیفالٹ 50)، ایک بیچ میں زیادہ سے زیادہ 100 واقعات، فی درخواست زیادہ سے زیادہ 250 خصوصیات کے آپریشنز، ایک بار میں زیادہ سے زیادہ 30 ٹیگز۔
• فی اکاؤنٹ زیادہ سے زیادہ 20 فعال کلیدیں۔
• کلید کی کالز کا جرنل 30 دن محفوظ رہتا ہے: وقت، طریقہ، پاتھ ٹیمپلیٹ (بغیر id اور باڈی)، جواب کا کوڈ، دورانیہ۔
• API کے ذریعے بھیجے گئے واقعات لیڈ کے کارڈ میں (فیڈ، خلاصہ، سیگمنٹس) شامل ہوتے ہیں، مگر وزٹ کے تجزیات کے خام جرنل میں نہیں۔
• لیڈ کو صرف موجودہ گفتگو میں پیغام بھیجا جا سکتا ہے: گفتگو نہ ہو تو جواب 409 no_conversation۔

مسائل کا حل#

ہر درخواست کالز کا جرنل ٹیب میں نظر آتی ہے — جواب کے کوڈ اور کلید کے نام کے ساتھ۔

عام سوالات#

کیا API براؤزر سے کال کی جا سکتی ہے؟ نہیں: کلید برانچ کے تمام لیڈز تک رسائی دیتی ہے۔ API اپنے سرور سے کال کریں۔

user_id لیڈ کے id سے کیسے مختلف ہے؟ لیڈ کا id ہمارا کارڈ شناخت کنندہ ہے۔ user_id آپ کا صارف شناخت کنندہ ہے (CRM میں نمبر، سائٹ پر اکاؤنٹ کا id)؛ ?by=user_id کے ساتھ کارڈ کو اسی سے مخاطب کیا جا سکتا ہے۔

واقعہ دوبارہ بھیجنے پر کیا ہوگا؟ ایک ہی id والا واقعہ صرف ایک بار شمار ہوتا ہے — نیٹ ورک کی خرابی پر درخواست بے دھڑک دہرائی جا سکتی ہے۔

کیا ہر برانچ کے لیے الگ کلید درکار ہے؟ نہیں: ایک کلید کئی برانچوں کے ساتھ کام کر سکتی ہے، برانچ location پیرامیٹر سے منتخب ہوتی ہے۔

متعلقہ حصے#

• مہمانوں کے ساتھ چیٹ — گفتگو، لیڈز اور ویب ہک کی ترتیبات
• درخواستیں — واحد آنے والا بہاؤ
• اپنی PBX کا API اور MCP — ٹیلی فونی کی الگ API
• انٹیگریشنز