Webhook’ai ir REST API

Conviro siūlo webhook’us pranešimams apie įvykius realiuoju laiku ir REST API programinei prieigai prie visų platformos funkcijų.

Webhook’ai

Kas yra webhook’ai?

Webhook’ai išsiunčia HTTP POST užklausą į jūsų serverį kaskart, kai Conviro sistemoje įvyksta tam tikras įvykis. Taip galite reaguoti realiuoju laiku ir jums nereikia nuolat siųsti užklausų (polling).

Galimi įvykiai

Įvykis	Kada suveikia
`message.new`	Išsiunčiama nauja žinutė (lankytojo arba boto)
`session.started`	Prasideda nauja pokalbio sesija
`session.closed`	Pokalbis uždaromas
`session.escalated`	Pokalbis perduodamas aukštesniam lygiui
`lead.captured`	Užfiksuojamas naujas potencialus klientas
`lead.created`	Sukuriamas potencialaus kliento įrašas
`lead_form.submitted`	Pateikiama potencialaus kliento forma
`handoff.requested`	Paprašoma perduoti pokalbį darbuotojui
`csat.submitted`	Pateikiamas CSAT įvertinimas
`csat.received`	Užfiksuojamas CSAT rezultatas
`ai.failed`	Dirbtinis intelektas nesugeba pateikti atsakymo
`ticket.created`	Atidaroma pagalbos užklausa
`ticket.resolved`	Pagalbos užklausa išsprendžiama
`contact.created`	Sukuriamas naujas kontaktas
`contact.updated`	Kontaktas atnaujinamas
`contact.merged`	Sujungiami du kontaktai
`contact.deleted`	Kontaktas ištrinamas

Webhook formoje taip pat yra Visi įvykiai — ji užprenumeruoja visus aukščiau išvardytus įvykius (saugoma kaip pakaitos simbolis *); vienas webhook taip pat priima kableliais atskirtų įvykių pavadinimų sąrašą.

Nustatymas

Eikite į Dashboard -> Kūrėjai -> Žiniatinklio kabliukai.
Spustelėkite Add Webhook.
Įveskite savo galinio taško URL (turi būti HTTPS).
Pasirinkite įvykius, kuriuos norite gauti.
Spustelėkite Save.

Sauga: pasirašymas HMAC-SHA256

Kiekvienas webhook’o duomenų paketas pasirašomas HMAC-SHA256 algoritmu naudojant jūsų webhook’o slaptąjį raktą. Kad įsitikintumėte autentiškumu, patikrinkite parašą savo serveryje:

X-Webhook-Signature: t=<unix_timestamp>,v1=<hex_digest>
X-Webhook-Event: <event_name>
X-Webhook-Retry: <attempt>          # only on a retried delivery

Santrauka skaičiuojama iš <unix_timestamp>.<neapdorotas_užklausos_turinys>, todėl tikrinant vien turinį niekada nesutaps. Padalykite antraštę pagal ,, nuskaitykite t= ir v1= reikšmes, iš naujo apskaičiuokite t + '.' + rawBody HMAC-SHA256 su savo webhook secret ir palyginkite abi santraukas pastoviu laiku. Atmeskite pristatymą, kurio laiko žyma senesnė nei kelios minutės, kad perimtas turinys negalėtų būti pakartotas. Pastaba: Siųsti testą į URL, kuris nėra išsaugotas webhook, pristatomas nepasirašytas — nėra paslapties, kuria būtų galima pasirašyti; testuokite patikrą su išsaugotu galiniu tašku.

Pakartojimo politika

Jei jūsų galinis taškas grąžina ne 2xx būsenos kodą, Conviro kartoja bandymus iki 3 kartų taikydama eksponentinę delsą (1 min., 5 min., 30 min.).

REST API

Autentifikavimas

Sugeneruokite API raktą čia: Dashboard -> Kūrėjai -> API raktai -> Sukurti API raktą.
Įtraukite jį į Authorization antraštę:

Authorization: Bearer sk_your_api_key_here

> Raktas parodomas tik vieną kartą. Kuriant raktą privaloma pasirinkti bent vieną apimtį (scope) — Sukurti lieka neaktyvus, kol jos nepasirinksite — o visa sk_ reikšmė parodoma vienintelį kartą dialogo lange, kuris sąmoningai neužsidaro nei Escape klavišu, nei spustelėjus foną. Vėliau įskaitomas lieka tik priešdėlis; likusi dalis yra bcrypt santrauka ir jos atkurti neįmanoma. Nukopijuokite raktą prieš uždarydami langą. Jei jį prarasite, sukurkite naują ir atšaukite senąjį.

Pagrindiniai galiniai taškai

Metodas	Galinis taškas	Aprašymas
GET	`/api/chatbots`	Pateikia visų chatbot’ų sąrašą
GET	`/api/chatbots/:id`	Grąžina chatbot’o informaciją
GET	`/api/sessions`	Pateikia sesijų sąrašą (su filtrais)
GET	`/api/sessions/:id/messages`	Grąžina sesijos žinutes
POST	`/api/sessions/:id/messages`	Išsiunčia žinutę į sesiją
GET	`/api/contacts`	Pateikia kontaktų sąrašą
POST	`/api/contacts`	Sukuria kontaktą
GET	`/api/leads`	Pateikia potencialių klientų sąrašą
POST	`/api/leads`	Sukuria potencialų klientą
GET	`/api/analytics/overview`	Grąžina analitikos suvestinę

Užklausų limitai

Free planas: 60 užklausų per minutę
Starter: 120 užklausų per minutę
Pro: 300 užklausų per minutę
Growth+: 600 užklausų per minutę

Užklausų limito antraštės įtraukiamos į kiekvieną atsakymą:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1672531200

Visa dokumentacija

Išsamų API žinyną su užklausų ir atsakymų pavyzdžiais rasite adresu /developers.