सार्वजनिक 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 अनुरोध प्रति मिनट; इससे ज़्यादा पर — Retry-After हेडर के साथ 429। शेष — 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
• एकीकरण