Analyse a live call

This guide walks the full path: compose a configuration, attach it to a live call as a session, receive results as the call unfolds, and retrieve the durable conversation afterwards. Each step links back to the concept it builds on rather than re-explaining it.

The examples use the Conversation Intelligence base path https://api.simwood.com/intelligence/v1 and a Bearer API key. See Authentication for how keys and scopes work; the scopes used below are intelligence:write and intelligence:read.

You'll need an API key with intelligence:write and intelligence:read, and a live call already known to the platform (its call_id).

1. Choose your operators

An operator is one unit of analysis. The platform maintains a catalogue you can use as-is — list them to see what's available:

curl https://api.simwood.com/intelligence/v1/operators \
  -H "Authorization: Bearer sk_live_..."

This guide uses two platform operators: fraud-confidence (a score) and fraud-indicators (a multi_tag). If you need analysis the catalogue doesn't cover, create a custom operator — the rest of the flow is identical.

2. Create a configuration

A configuration names the operators to run, the granularity each runs at, and the actions that fire on their results. Here, both operators run every five turns, and a webhook action posts to your endpoint when fraud confidence crosses 80 with high confidence:

curl -X POST https://api.simwood.com/intelligence/v1/configurations \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "fraud-detection",
    "operators": [
      { "name": "fraud-confidence", "granularity": { "on": "turn", "every": 5 }, "include_prior_results": true },
      { "name": "fraud-indicators", "granularity": { "on": "turn", "every": 5 } }
    ],
    "actions": [
      {
        "type": "webhook",
        "webhook_url": "https://example.com/hooks/fraud",
        "once_per_session": true,
        "condition": {
          "operator": "fraud-confidence",
          "expression": "result.value > 80 AND confidence > 0.75"
        }
      }
    ]
  }'

The response includes the configuration's uuid — its stable identifier — and a sync_state. Wait until sync_state is live before starting a session, so the running pipeline reflects your new configuration.

To check a configuration before saving it, post the same body to POST /configurations/validate for a dry run that returns valid plus any errors without persisting anything.

3. Start a session on the live call

A session attaches the configuration to one live call and runs it in realtime. Pass the call_id and the configuration's uuid; the optional customer_metadata is echoed back, verbatim, on every webhook this session fires:

curl -X POST https://api.simwood.com/intelligence/v1/sessions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "call_id": "call-abc-123",
    "configuration_id": "5f1c…",
    "customer_metadata": { "your_ref": "ticket-9981" }
  }'

The response returns a session_id. Use it on every other session endpoint. The session then runs for the life of the call — it ends automatically when the call ends, so you don't tear it down yourself.

You don't have to start sessions yourself. Assign a configuration to a trunk in your trunk settings, and every call over that trunk is analysed automatically — the platform starts a session for each call and applies the configuration, with no call to POST /sessions. Starting a session explicitly, as above, is the per-call alternative: reach for it when you choose the configuration dynamically or attach per-call customer_metadata.

4. Receive results as the call unfolds

You have three ways to consume results, and they work together:

Webhooks fire automatically. The action you defined in step 2 posts to your endpoint whenever its condition is met. Your customer_metadata and a summary of the operators the condition tested arrive in the webhook envelope — no polling required.

Stream results live. Fetch a short-lived stream token, then open a Server-Sent Events connection to receive every operator result as it is produced. See Session events for the full list of event types and their payloads:

# 1. Get a stream token
curl https://api.simwood.com/intelligence/v1/sessions/<session_id>/stream-token \
  -H "Authorization: Bearer sk_live_..."

# 2. Connect to the event stream — authenticated by the token alone, no API key
curl -N "https://api.simwood.com/intelligence/v1/sessions/<session_id>/events?token=<token>"

Snapshot the latest results. When you only need the current state, fetch the latest result per operator without holding a stream open:

curl https://api.simwood.com/intelligence/v1/sessions/<session_id>/operator-results \
  -H "Authorization: Bearer sk_live_..."

To adapt the analysis mid-call, PATCH /sessions/<session_id> swaps the configuration in force from that point onward. To stop analysis before the call ends, DELETE /sessions/<session_id>.

5. Retrieve the conversation afterwards

When the call ends, the session ends on its own and any conversation_end operators run over the full transcript. The session was live and ephemeral; the conversation is the durable record. Find it by the call's transport_key, then read its operator results and transcript:

# Find the conversation for this call
curl "https://api.simwood.com/intelligence/v1/conversations?transport_key=call-abc-123" \
  -H "Authorization: Bearer sk_live_..."

# Read its operator results
curl https://api.simwood.com/intelligence/v1/conversations/<conversation_id>/operator-results \
  -H "Authorization: Bearer sk_live_..."

# Page through its transcript
curl https://api.simwood.com/intelligence/v1/conversations/<conversation_id>/transcript \
  -H "Authorization: Bearer sk_live_..."

From here you can list and query conversations across all of your calls — by call, end user, medium, status, or time range — rather than auditing a sample.

Next steps