Openbare API en webhooks

De REST API laat uw CRM, de backend van uw website of uw eigen bot werken met leads en gesprekken van cenaly.com, net zoals het paneel dat doet: kaarten lezen, eigenschappen wijzigen, gebeurtenissen verzenden, antwoorden in gesprekken. Webhooks daarentegen melden uw server zelf nieuwe leads, gebeurtenissen en berichten.

Wat u nodig hebt om te starten#

Stap 1. Sleutel en rechten#

1. Open Integraties en klik op API en webhooks boven aan de pagina.
2. Klik op het tabblad Sleutels op Sleutel aanmaken en voer een naam in („CRM”, „Backend van de website”, „Telegram-bot”).
3. Kies een rechtenpakket of vink rechten afzonderlijk aan, en bij meerdere vestigingen — tot welke vestigingen de sleutel toegang heeft, en de looptijd.
4. Kopieer het geheim cnk_…. Het wordt één keer getoond: bij ons wordt alleen de vingerafdruk (SHA-256) bewaard.

Pakketten: CRM / backend (leads, eigenschappen, gebeurtenissen, gesprekken en segmenten lezen), Eigen bot (leest leads, antwoordt in gesprekken, schrijft naar leads), Alleen lezen, Alles.

• Rechten wijzigen de rechten en vestigingen van de sleutel direct — de integratie blijft werken.
• Opnieuw uitgeven geeft een nieuw geheim; het oude werkt onmiddellijk niet meer, rechten en logboek blijven behouden.
• Intrekken — onmiddellijk en voorgoed, het volgende verzoek krijgt 401.

De sleutel wordt doorgegeven via de header Authorization: Bearer cnk_… (of X-Api-Key: cnk_…). Bewaar hem alleen op de server — niet in de browser en niet in de mobiele app.

Stap 2. Eerste verzoeken#

KEY=cnk_uw_sleutel
API=https://api.cenaly.com/public-api/v1

# wat de sleutel kan: rechten, vestigingen, limiet
curl -H "Authorization: Bearer $KEY" "$API/me"

# leads, nieuwste bovenaan (20 per pagina)
curl -H "Authorization: Bearer $KEY" "$API/contacts?limit=20"

# zoeken op naam, e-mail of telefoon
curl -H "Authorization: Bearer $KEY" "$API/contacts?q=anna"

Het antwoord is altijd een envelop:

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

De volgende pagina is hetzelfde verzoek met cursor=<meta.nextCursor>; geen nextCursor — dan zijn er geen pagina's meer. Fout — {"meta": {...}, "error": {"code": "…"}}.

Vestiging. Als de sleutel toegang heeft tot één vestiging, hoeft u die niet op te geven. Bij meerdere — voeg location=<id van de vestiging> toe (lijst — GET /v1/locations), anders volgt het antwoord 400 location_required.

Eigenschappen en gebeurtenissen op uw user_id. U hoeft ons lead-id niet te bewaren: voeg ?by=user_id toe en uw gebruikersidentificatie wordt het adres. Bestaat er nog geen lead met dat user_id — dan maken we die aan.

# eigenschappen: bewerkingen 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"

# gebeurtenissen in een batch (tot 100), herhaling met hetzelfde id telt één keer
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"

# antwoord in het gesprek en statuswijziging
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"

Het schrijven gaat via dezelfde wachtrij als wijzigingen uit het paneel: wijzigingen worden binnen seconden toegepast, en het antwoord op een schrijfactie op user_id is 202 met pending. Op de leadkaart is de auteur van de wijziging te zien als „API: ”.

Methoden#

Velden, voorbeelden en foutcodes van elke methode staan in de naslag.

Stap 3. Webhooks#

Webhooks worden per vestiging ingesteld: Chat → Instellingen → Webhooks — adres https, gebeurtenissen en het ondertekeningsgeheim. Naast de gespreksgebeurtenissen (nieuw gesprek, nieuw bericht, status, beoordeling, labels) zijn er nu ook leadgebeurtenissen:

{
  "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 } }
}

Naam, e-mail en telefoon van de lead komen alleen in de body als bij de webhook het vakje „Contactgegevens van de gast doorgeven” is aangevinkt. Ondertekening controleren doet u met HMAC-SHA256 over de body met het webhookgeheim:

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

Antwoord met 2xx binnen 5 seconden — anders wordt de levering herhaald; na een lange reeks mislukkingen wordt de webhook uitgeschakeld, en dat is zichtbaar in de instellingen. Filter duplicaten op deliveryId.

Beperkingen#

• 60 verzoeken per minuut per sleutel; daarboven 429 met de header Retry-After. Het restant staat in X-RateLimit-*.
• Max. 200 records per pagina (standaard 50), max. 100 gebeurtenissen per batch, max. 250 bewerkingen op eigenschappen per verzoek, max. 30 tags per keer.
• Max. 20 actieve sleutels per account.
• Het aanroepenlogboek van een sleutel wordt 30 dagen bewaard: tijd, methode, padsjabloon (zonder id en body), responscode, duur.
• Gebeurtenissen die via de API worden verzonden, komen in de leadkaart terecht (feed, samenvatting, segmenten), maar niet in het ruwe logboek van de bezoekersanalyses.
• De lead schrijven kan alleen in een bestaand gesprek: geen gesprek — respons 409 no_conversation.

Problemen oplossen#

Elk verzoek is zichtbaar op het tabblad Aanroepenlogboek — met de responscode en de naam van de sleutel.

Veelgestelde vragen#

Kan ik de API vanuit de browser aanroepen? Nee: de sleutel geeft toegang tot alle leads van de vestiging. Roep de API aan vanaf uw eigen server.

Waarin verschilt user_id van het id van de lead? Het id van de lead is onze identificatie van de kaart. user_id is uw identificatie van de gebruiker (nummer in het CRM, id van het account op de site); met ?by=user_id kunt u de kaart daarmee aanspreken.

Wat gebeurt er bij het opnieuw verzenden van een gebeurtenis? Een gebeurtenis met hetzelfde id wordt één keer geteld — u kunt het verzoek bij een netwerkfout gerust herhalen.

Is er een aparte sleutel per vestiging nodig? Nee: één sleutel kan met meerdere vestigingen werken, de vestiging kiest u met de parameter location.

Gerelateerde secties#

• Chat met gasten — gesprekken, leads en webhookinstellingen
• Aanvragen — één gezamenlijke inkomende stroom
• API en MCP van uw eigen telefooncentrale — aparte telefonie-API
• Integraties