ThunderPhone v3 jau veikia.Viską atlikite savarankiškai – nuo 2 ct/min.Skaityti pranešimą

Webhooks

Webhook galiniai taškai

Valdykite kelis webhook URL su kiekvieno galinio taško slaptaisiais raktais ir įvykių filtrais.

Galinių taškų pagrindu veikianti žiniatinklio kabliukų sistema leidžia užregistruoti kelias paskirties vietas kiekvienai organizacijai, kiekvieną su atskira paslaptimi, atskira būsena ir atskira pasirinktų įvykių tipų prenumerata. Tai rekomenduojamas modelis visoms naujoms integracijoms.

Palyginkite su senąja vieno URL žiniatinklio kabliuko sistema, kuri išlaikoma siekiant atgalinio suderinamumo, tačiau palaiko tik vieną URL vienai organizacijai.

Galiniai taškai

MetodasKeliasReikalingas vaidmuoAprašymas
GET/v1/developer/webhook-endpointsadmin+Išvardyti galinius taškus
POST/v1/developer/webhook-endpointsadmin+Sukurti galinį tašką
PATCH/v1/developer/webhook-endpoints/{endpoint_id}admin+Atnaujinti etiketę / URL / įvykius / būseną
DELETE/v1/developer/webhook-endpoints/{endpoint_id}admin+Ištrinti galinį tašką
POST/v1/developer/webhook-endpoints/{endpoint_id}/rotate-secretadmin+Pakeisti pasirašymo slaptąjį raktą
POST/v1/developer/webhook-endpoints/{endpoint_id}/testadmin+Siųsti pasirašytą bandomąjį pristatymą
GET/v1/developer/webhook-deliveriesadmin+Peržiūrėti naujausius galinių taškų ir senųjų pristatymų rezultatus

Galinio taško objektas

{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "agent_id": 42,
  "agent_name": "Support Agent",
  "secret_hint": "a1b2…9f0e",
  "paused_at": null,
  "pause_last_error": "",
  "pause_undelivered_count": null,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}
LaukasTipasAprašas
idUUIDGalinio taško ID
labeleilutėRodomas pavadinimas, 1–120 simbolių
urleilutėHTTPS URL; http://localhost leidžiama kūrimui
eventseilučių masyvasPrenumeruojami įvykių tipai (žr. galiojančias reikšmes). Tuščias masyvas prenumeruoja visus įvykius, išskyrus tik aiškiai nurodomus įvykius (telephony.turn / web.turn / call.status_changed)
statuseilutėactive, disabled (pristabdyta rankiniu būdu) arba failing (nustatoma automatiškai, kai pristatant įvykį išnaudojamas 24 val. pakartotinių bandymų tvarkaraštis negavus nė vieno 2xx atsakymo)
agent_idsveikasis skaičius | nullAgentas, kuriam priskirtas šis galinis taškas; null reiškia visos organizacijos galinį tašką
agent_nameeilutė | nullPriskirto agento pavadinimas arba null, jei galinis taškas skirtas visai organizacijai
secret_hinteilutėPirmi 4 ir paskutiniai 4 pasirašymo paslapties simboliai su daugtaškiu (a1b2…9f0e) — pakanka susieti su vietoje išsaugota paslaptimi neatskleidžiant visos reikšmės
paused_atlaiko žyma | nullKada ThunderPhone nustatė galinio taško būseną į failing. null, kol būsena yra active arba disabled
pause_last_erroreilutėPaskutinė pristatymo klaida, kai galinis taškas buvo pristabdytas, pvz., HTTP 503: Service Unavailable. Tuščia, nebent būsena yra failing
pause_undelivered_countsveikasis skaičius | nullĮvykiai, nepristatyti nuo paskutinio sėkmingo galinio taško pristatymo, suskaičiuoti jį pristabdžius
created_at, updated_atlaiko žyma

Galiojantys įvykių tipai

events tikrinamas pagal šį tikslų sąrašą — už sąrašo ribų esančios reikšmės grąžina 400. Kiekvieno tipo naudingojo krūvio struktūrą žr. Įvykių kataloge.

  • telephony.incoming, telephony.complete, telephony.tool, telephony.turn
  • web.incoming, web.complete, web.tool, web.turn
  • sms.sent, sms.failed
  • sms.received (rezervuota; dar nesiunčiama)
  • scheduled.skipped, scheduled.failed
  • call.graded, call.data_extracted, call.transfer_completed, call.status_changed
  • campaign.completed
  • issue.reported, issue.escalated
  • test-call.completed
  • alert.triggered
  • phone_number.spam_risk_changed

issue.escalated ir phone_number.spam_risk_changed neturi agento konteksto ir yra siunčiami tik į visos organizacijos galinius taškus.

voice.ready ir voice.failed negalima pasirinkti aiškiai. Norėdami juos gauti, sukurkite visos organizacijos galinį tašką su events: []. Tuščias įvykių sąrašas gauna kiekvieną palaikomą įvykį, išskyrus telephony.turn, web.turn ir call.status_changed, kuriuos būtina pasirinkti aiškiai.

Galinių taškų būsenos

  • active — pristatymai vyksta įprastai.
  • disabled — rankiniu būdu pristabdytas naudojant PATCH. Užklausos nesiunčiamos. Mes niekada nekeičiame disabled galinio taško būsenos; grąžinti ją į active visada sprendžiate jūs.
  • failing — nustatoma automatiškai, kai pristatymas į galinį tašką išnaudoja visą pakartotinių bandymų tvarkaraštį (8 bandymai per 24 valandas) nė karto negavęs 2xx atsakymo. Į nepavykstantį galinį tašką daugiau srauto nesiunčiama. Kai taip nutinka, el. paštu informuojame jūsų organizacijos savininkus ir administratorius, o valdymo skydelyje pristabdytas galinis taškas rodomas su mygtuku Reaktyvinti. Ištaisę galinį tašką, naudokite PATCH, kad grąžintumėte jo būseną į active; pristatymai, kurių pakartotinių bandymų tvarkaraštis dar nepasibaigė, tęsiami nuo vietos, kur buvo sustoję.

Galinių taškų sąrašas

cURL
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Grąžina galinių taškų objektų masyvą. Perduokite ?agent_id=42, kad būtų grąžinti tik tam agentui priskirti galiniai taškai.

Agentui priskirti galiniai taškai

Visos organizacijos galiniai taškai gauna kiekvieną atitinkantį įvykį. Galinis taškas su agent_id gauna tik atitinkančius skambučių, kuriuos tvarko tas agentas, įvykius; įvykiai be agento konteksto, pvz., alert.triggered, jo niekada nepasiekia. Šiuos galinius taškus taip pat galite kurti ir tvarkyti agento kūrimo priemonės skiltyje Žiniatinklio kabliai.


Sukurkite galinį tašką

cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call events",
    "url":    "https://example.com/thunderphone/hook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'
Python
result = requests.post(
    "https://api.thunderphone.com/v1/developer/webhook-endpoints",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "label":  "Production — Call events",
        "url":    "https://example.com/thunderphone/hook",
        "events": ["telephony.incoming", "telephony.complete"],
    },
).json()
secret = result["secret"]
endpoint_id = result["id"]

Užklausos laukai

LaukasTipasPrivalomasAprašas
labeleilutėtaip1–120 simbolių
urleilutėtaipHTTPS URL (http leidžiama naudoti tik su localhost / 127.0.0.1)
eventsmasyvasneTuščias arba nenurodytas masyvas užprenumeruoja visus įvykius, išskyrus telephony.turn / web.turn / call.status_changed, kuriems reikia aiškios prenumeratos. Būtina naudoti reikšmes, nurodytas skiltyje Galiojantys įvykių tipai; dublikatai pašalinami
agent_idsveikasis skaičius | nullneApriboja pristatymą šios organizacijos agentui; praleiskite arba naudokite null, jei galinis taškas taikomas visai organizacijai

Grąžina 201 Created su galinio taško objektu ir papildomu aukščiausio lygmens secret lauku, kuriame yra neapdorotas pasirašymo raktas – 48 simbolių šešioliktainė eilutė:

{
  "id": "c4d5e6f7-…",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "secret": "a1b2c37e08d94f5b16a2c8d90e7f3a4b5c6d7e8f90a19f0e"
}

Atnaujinkite galinį tašką

cURL
curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call + Grade events",
    "events": ["telephony.incoming", "telephony.complete", "call.graded"]
  }'
LaukasTipasAprašymas
labeleilutė
urleilutė
eventsmasyvas
statuseilutėactive arba disabled. Nustatykite active, kad iš naujo įjungtumėte galinį tašką, kurį serveris pažymėjo kaip failing
agent_idsveikasis skaičius | nullNustatykite agento ID, kad apribotumėte galinį tašką, arba null, kad jis būtų skirtas visai organizacijai

Grąžina 200 OK su atnaujintu galinio taško objektu.


Pasukite pasirašymo paslaptį

Pakeiskite galinio taško pasirašymo slaptąjį raktą, pavyzdžiui, jei jis buvo prarastas arba galėjo nutekėti. Taip pat galite naudoti valdymo skydelį: atidarykite galinį tašką skiltyje Integracijos → Žiniatinklio kabliukai (ten pateikiami tiek visos organizacijos, tiek agentų galiniai taškai) ir pasirinkite Keisti.

cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
LaukasTipasPrivalomaAprašymas
include_copiesloginė reikšmėneNumatytoji reikšmė true. Nauja paslaptis taip pat suteikiama kitiems jūsų organizacijos galiniams taškams, turintiems tą patį URL ir tą pačią dabartinę paslaptį, pavyzdžiui, šio galinio taško kopijoms kituose agentuose, kad vienas gavėjas toliau tikrintų naudodamas vieną paslaptį

Grąžina 200 OK:

{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}
LaukasTipasAprašymas
endpointobjektasGalinio taško objektas su nauju secret_hint
secreteilutėNauja pasirašymo paslaptis. Grąžinama tik šiame atsakyme
rotated_endpoint_idsUUID masyvasKiekvienas galinis taškas, dabar naudojantis naują paslaptį

Siųsti bandomąjį pristatymą

Išsiųskite sintetinį webhook.test įvykį į vieną galinį tašką naudodami įprastą pristatymo procesą, įskaitant kanoninį JSON serializavimą, abi parašo antraštes, pristatymo įrašymą ir pakartotinių bandymų apskaitą. Testas nukreipiamas į pasirinktą galinį tašką, neatsižvelgiant į jo events filtrą.

cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Galinis taškas gauna tokį apvalkalą:

{
  "data": {
    "message": "ThunderPhone webhook test",
    "sent_at": "2026-07-17T20:12:34.567890+00:00"
  },
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "type": "webhook.test"
}

API grąžina 200 OK po pirmojo bandymo, net jei paskirties vieta grąžina klaidą. Pristatymo rezultatą tikrinkite pagal success, status, response_code ir error:

{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}

webhook.test yra sintetinis ir jo negalima pridėti prie galinio taško events prenumeratos. Jei pirmasis bandymas nepavyksta, ThunderPhone maždaug po vienos minutės jį pakartoja vieną kartą ir tada sustoja; pristatymas tuomet rodo status: "failed" skiltyje Pristatymų derinimas. Bandomasis pristatymas niekada nepažymi galinio taško kaip failing.

Norėdami sukonfigūruoti aktyviklį pagal tikrą įvykio struktūrą, perduokite pasirenkamą event_type. Pristatymas vis tiek yra sintetinis ir jame yra "sample": true; su skambučiais susijusiuose pavyzdžiuose naudojami call_id: 0 ir agent_id: 0.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'

event_type priima bet kurią reikšmę iš Galiojančių įvykių tipų. Jo nenurodžius išlaikoma bendrinė webhook.test elgsena.

Skambučio užbaigimo (telephony.complete, web.complete) ir call.data_extracted pavyzdžiuose agento duomenų rinkimo laukai pateikiami skiltyje extracted_data.fields su vietos rezervavimo reikšmėmis, kaip ir tikruose jo skambučiuose. Agentui, kuris nerenka jokių duomenų, skambučio užbaigimo pavyzdys siunčia extracted_data: null, kaip ir tikri jo skambučiai, o call.data_extracted pavyzdyje fields yra tuščias (tikri skambučiai tokiam agentui šio įvykio niekada nesiunčia). Pavyzdžio summary yra null, kai agento skambučio suvestinė išjungta. Agento galiniame taške pavyzdys atitinka tą agentą; visos organizacijos galiniame taške perduokite pasirenkamą agent_id, kad jis būtų suformuotas pagal vieną agentą, arba jo nenurodykite, kad būtų naudojamas bendrasis pavyzdys.


Ištrinti galinį tašką

cURL
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Grąžina 204 No Content. Pristatymas į URL nedelsiant sustabdomas; vykdomų pakartotinių bandymų atsisakoma.


Pristatymų derinimas

Prieš nuspręsdami, kad webhook nebuvo išsiųstas, patikrinkite GET /v1/developer/webhook-deliveries. Čia rodomi naujausi bandymai iš abiejų webhook sistemų, įskaitant skambučio identifikatorių, URL kilmę, HTTP būseną, bandymų skaičių, leidžiamųjų sąraše esančią nesėkmės kategoriją ir kito pakartotinio bandymo laiką. Čia niekada negrąžinamas įvykio turinys, transkripcija, išsaugotas klaidos tekstas, atsakymo turinys ar URL kelias.

Tą pačią naujausią istoriją taip pat galite matyti skiltyje Agentai → pasirinkite agentą → Žiniatinklio kabliukai → Naujausi pristatymai. Eilutėse rodomos galinio taško etiketė ir URL kilmė, naudota paskutiniame bandyme. Tai yra veikimo būsena, o ne nekintamas audito žurnalas: ištrynus galinį tašką taip pat ištrinamos jo pristatymų eilutės.

Jei n8n grąžina 404, pirmiausia patvirtinkite, kad darbo eiga aktyvi, priima POST ir naudoja gamybinį webhook URL, o ne bandomąjį URL. 401 arba 403 nurodo autentifikavimo arba parašo tikrinimo problemą; laiko limitų viršijimas nurodo paskirties vietos delsą arba pasiekiamumą; TLS klaidos nurodo sertifikatų grandinę, pagrindinio kompiuterio pavadinimą arba galiojimo pabaigą.


Susiję