Webhooks

Händelsekatalog

Alla webhook-händelsetyper som ThunderPhone skickar.

Varje webhook-brödtext har ett type-fält vars värde är en av händelsetyperna på den här sidan. När du prenumererar på en slutpunkt måste arrayen events innehålla de händelsetyper du vill ha (eller vara tom för att prenumerera på allt — utom händelserna per tur telephony.turn / web.turn, som endast levereras till slutpunkter som uttryckligen anger dem).

Dessa händelser levereras på två sätt:

• Slutpunktsleveranser är alltid icke-blockerande notifieringar med omförsök: svara med valfri 2xx; kuvertet innehåller ett event_id för deduplicering.
• Blockerande utbyten körs endast på den äldre webhooken med en enda URL: begäran om konfiguration för telephony.incoming / web.incoming (nummer i webhook-läge och widgetnycklar, tidsgräns på 10 s) samt verktygsdirigering i webhook-läge. Ditt svar påverkar det pågående samtalet.

Exempelnyttolasterna nedan visar slutpunktskuvertet i dess överföringsordning (nycklar sorterade alfabetiskt: data, event_id, type); äldre leveranser innehåller samma data utan event_id.

Samtalshändelser#

telephony.incoming#

Skickas när ett inkommande samtal når ett av dina telefonnummer. Endpointleveranser är skicka-och-glöm-meddelanden som skickas för varje inkommande samtal, oavsett om numret är agentkonfigurerat eller webhookkonfigurerat. Nummer utan en tilldelad agent får dessutom den blockerande konfigurationsbegäran på den äldre webhooken — se telephony.incoming / web.incoming för det fullständiga schemat för begäran och svar.

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

telephony.complete#

Skickas när ett inkommande eller utgående telefonsamtal avslutas. Icke-blockerande. Innehåller transkriptionen, inspelnings-URL när den är tillgänglig och faktureringssammanfattning. Se telephony.complete / web.complete för schemat för nyttolasten.

telephony.tool#

Skickas efter att ett telefonsamtal anropar ett funktionsverktyg. Icke-blockerande granskningsmeddelande — verktyget har redan körts när händelsen levereras; det omfattar dina egna funktionsverktyg (inte inbyggda verktyg, verktyg för kunskapsbaser, appanslutningar eller MCP-verktyg).

{
  "data": {
    "arguments": { "date": "2026-04-21" },
    "call_id": 987654321,
    "from_number": "+14155550199",
    "response": {
      "response": { "available_slots": ["9:00 AM", "2:00 PM"] },
      "status": 200
    },
    "to_number": "+15551234567",
    "tool_name": "search_appointments"
  },
  "event_id": "1f0a7c3e-52d4-4a0e-8f4b-b1a6a1c0d9e2",
  "type": "telephony.tool"
}

response är det körda resultatet: {"status": <http status>, "response": <your endpoint's JSON>} vid lyckat resultat, eller {"status": <status>, "error": "<message>"} vid fel.

telephony.turn#

Skickas medan ett telefonsamtal pågår, en gång för varje talbärande tur när den inträffar — agentens talade svar och uppringarens transkriberade turer. Gör att du kan följa det direkta samtalet via vanliga webhooks i stället för att polla GET /v1/calls/{call_id}/transcript. Icke-blockerande.

{
  "data": {
    "call_id": 987654321,
    "entry_type": "completion",
    "from_number": "+14155550199",
    "position": 7,
    "role": "assistant",
    "start_ms": 15200,
    "text": "How many employees does your company have?",
    "to_number": "+15551234567"
  },
  "event_id": "8d3f5a2c-7b1e-4c9a-b6d0-2e4f6a8c0d1e",
  "type": "telephony.turn"
}

web.incoming#

Motsvarigheten i webbkanalen till telephony.incoming, som skickas när en webbwidget-session eller ett mikrofontestsamtal i byggaren startar. Endpointleveranser är skicka-och-glöm för varje webbsession. Publicerbara nycklar i mode="webhook" får dessutom den blockerande konfigurationsbegäran på den äldre webhooken — den blockerande begäran har ett annat format (origin_domain, publishable_key_prefix; inga telefonnummer). Se telephony.incoming / web.incoming.

{
  "data": {
    "call_id": 987654322,
    "from_number": "web",
    "origin_domain": "https://example.com",
    "publishable_key_prefix": "pk_live_a1b2",
    "to_number": "+15551234567"
  },
  "event_id": "9a2b4c6d-8e0f-4a1b-9c2d-3e4f5a6b7c8d",
  "type": "web.incoming"
}

from_number är alltid den bokstavliga strängen "web". För widgetsessioner i webhookläge är to_number tomt (sessionens agentnummer tilldelas efter konfiguration); för mikrofontestsamtal i byggaren är origin_domain och publishable_key_prefix tomma.

web.complete#

Motsvarigheten i webbkanalen till telephony.complete, som omfattar samtal via webbwidgeten (direction: "web") och mikrofontestsamtal i byggaren (direction: "test"). Icke-blockerande. Samma nyttolastformat som telephony.complete, plus origin_domain, med from_number inställt på "web".

web.tool#

Motsvarigheten i webbkanalen till telephony.tool. data innehåller origin_domain i stället för from_number / to_number.

web.turn#

Motsvarigheten i webbkanalen till telephony.turn, som omfattar samtal via webbwidgeten och mikrofontestsamtal i byggaren. Samma nyttolastformat, med origin_domain i stället för from_number / to_number. Precis som telephony.turn kräver den en explicit prenumeration — den levereras aldrig via en tom events-array.

Rösthändelser#

Skapandet av anpassade röster sker asynkront. Med dessa icke-blockerande händelser kan du reagera på ett slutgiltigt resultat i stället för att polla klondetaljslutpunkten.

voice.ready#

Skickas när en anpassad röst har bearbetats klart och kan tilldelas en agent.

{
  "data": {
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "ready",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "2d5f0a61-e9b5-4a3c-b684-29d7d9e4b214",
  "type": "voice.ready"
}

voice.failed#

Skickas när bearbetningen av en anpassad röst får ett permanent fel.

{
  "data": {
    "reason": "audio sample could not be processed",
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "audio sample could not be processed",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "failed",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "3493e985-1a75-4f77-a10a-e74af440cd31",
  "type": "voice.failed"
}

Kvalitetshändelser#

call.graded#

Skickas när en AI-graderingskörning slutförs för ett samtal. Icke-blockerande.

{
  "data": {
    "call_id": 987654321,
    "grade": {
      "call_outcome": "success",
      "created_at": "2026-04-20T18:25:11.002Z",
      "detected_issues": [],
      "graded_at": "2026-04-20T18:25:11.002Z",
      "grader_model": "heuristic-v1",
      "id": 5512,
      "score": 92,
      "status": "completed",
      "summary": "Caller asked about their policy and got a full answer…"
    }
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

issue.reported#

Skickas när en problemrapport skapas — antingen inskickad av en användare från instrumentpanelen (source: "user") eller automatiskt genom samtalsgradering (source: "system"). Icke-blockerande.

{
  "data": {
    "call_id": 987654321,
    "issue_report": {
      "created_at": "2026-04-20T18:25:11.002Z",
      "description": "Five-second silence before responding to the main question.",
      "id": 4321,
      "severity": "warning",
      "source": "system",
      "status": "open",
      "title": "Agent paused too long"
    }
  },
  "event_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "type": "issue.reported"
}

Händelser för testsamtal#

test-call.completed#

Skickas när en testsamtalskörning når en slutlig status — completed eller failed, inklusive körningar som misslyckades vid start och aldrig skapade ett samtal. Icke-blockerande. Användbart för att koppla batchkörningar i CI till dina chatt- och aviseringssystem.

{
  "data": {
    "test_call_run": {
      "call_id": 987654321,
      "completed_at": "2026-04-20T18:25:04.822Z",
      "error_message": "",
      "id": 7110,
      "status": "completed",
      "target_id": 12,
      "target_type": "agent"
    }
  },
  "event_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "type": "test-call.completed"
}

Varningshändelser#

alert.triggered#

Skickas när en varningsregel med kanalen Leverera till utvecklarwebhooks aktiverad passerar sitt tröskelvärde. Icke-blockerande. En regel utlöses en gång och respekterar sedan sin nedkylningstid, så en ihållande överträdelse genererar en händelse per nedkylningsfönster.

{
  "data": {
    "comparator": "lt",
    "event_id": "b8e6a1d4-2c3f-4a5b-9c8d-7e6f5a4b3c2d",
    "fired_at": "2026-04-20T18:00:00+00:00",
    "metric": "success_rate",
    "metric_value": 71.4,
    "rule_id": "d2c3b4a5-6f7e-4d8c-9b0a-1c2d3e4f5a6b",
    "rule_name": "Success rate below 80%",
    "threshold": 80.0,
    "window_hours": 24
  },
  "event_id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
  "type": "alert.triggered"
}

Se guiden för varningar för att skapa regler, mätvärden, nedkylningstider och e-post- / Slack-kanaler.

Relaterat#