Live events

Live events are the machine-readable stream of everything Speechlytics notices during a live call: keyword detections, alerts, sentiment and intent changes, entities, summaries, coaching suggestions, detected languages and translations.

The Events API must be enabled for the account, along with the individual live features that produce events.

Two ways to read events

Transport	Use it when
GET /api/v1/calls/{id}/live-events?afterId=<cursor>&limit=<n>	You want simple, recoverable polling.
wss://api.example.com/ws/live-events?callId=<id>	You want events pushed with minimal latency.

Both return the same events. The REST endpoint is easier to recover after a network interruption; the socket does not replay events you missed while disconnected, so combine it with one REST catch-up call after reconnecting.

Polling with a cursor

curl "https://api.example.com/api/v1/calls/4821/live-events?afterId=0&limit=200" \
  --header "Authorization: Bearer $SPEECHLYTICS_TOKEN"

• afterId is a cursor. Start with 0, then send the largest id you have received.
• limit defaults to 200 and is capped at 1,000.
• Poll about once a second per call, or slower. Polling is subject to the rate limits; for many concurrent calls, prefer the WebSocket.
• The response is an array, oldest first. An empty array means nothing new.

WebSocket

Connect with the JWT in the Authorization header. The socket is read-only. Each text frame looks like:

{ "type": "AlertTriggered", "message": "{\"id\":981,\"callId\":4821,\"type\":\"AlertTriggered\",...}" }

Parse message as a JSON document with the event shape below. If the token is invalid, the call belongs to another account or the Events API is off, the socket stays silent.

Event shape

{
  "id": 981,
  "callId": 4821,
  "type": "AlertTriggered",
  "severity": "Warning",
  "channel": "Right",
  "start": 73.4,
  "title": "Cancellation risk",
  "detail": "Keyword 'cancel my contract' detected"
}

Field	Meaning
id	Monotonic event id. Use it as the polling cursor.
callId	The live call.
type	Event type (below).
severity	Info, Warning or Critical.
channel	Left (agent), Right (customer) or Both.
start	Seconds from the start of the call.
title, detail	Human-readable headline and detail.

Enum values in live events are sent as strings.

Event types

type	Produced by	Notes
KeywordDetected	Keyword Detection	A configured keyword or phrase was spoken.
AlertTriggered	Alerts & Rules	A live alert rule fired. Each rule fires at most once per call.
SentimentChanged	Sentiment & Intent	The customer's sentiment or frustration level changed.
IntentChanged	Sentiment & Intent	The detected call intent changed, for example to Cancellation or Billing.
EntityDetected	Conversation State	A new name, product, issue or other entity was recognized.
SummaryUpdated	Summary	The running summary or the customer's current request changed.
CoachingSuggestion	Agent Coaching	A suggested response, next best action, warning or compliance reminder.
LanguageDetected	Live Language Detection	A speaker's language was detected or changed.
TranslationReceived	Live translation	A segment was translated. Recorded only with the Events API on.
SpeakerChanged	Stereo calls	The active speaker switched. Recorded only with the Events API on.

Coaching events are agent-facing. Do not show them to customers or other public viewers.

Errors

Response	Cause
403	The Events API is not enabled for the account.
404	The call does not exist or belongs to another account.