Start & Complete Interaction

Before You Start

If your telephony platform cannot make the API calls described in this document, a technical scoping meeting with Capacity will be required to discuss alternative integration options.

You will need:

Your Creovai instance name — the subdomain of your Conversation Intelligence (CI) environment (i.e. [INSTANCE NAME].audio.tethr.com)
API credentials — a bearer token issued by Creovai Support
A tool or platform capable of making server-side HTTP requests

The agent must be logged into the Agent Assist Desktop with a method configured to capture audio. See Agent Assist — Desktop Capture for supported methods. Without this, the session starts via the API but the agent receives no live guidance.

Prerequisites

API User — Request an API user in Conversation Intelligence via Creovai Support. You will need to request LiveCall and Processing roles.
CI ↔ Agent Assist Link — Creovai will configure the connection between your Conversation Intelligence and Agent Assist environments as part of onboarding.

Authentication

To request a bearer token, reference the Authorization Token article

How It Works

A Realtime Agent Assist session is bookended by two API calls:

Call	Purpose
Start Interaction	Sent when the interaction begins. Establishes the session and passes participant/metadata info.
Complete Interaction	Sent when the interaction ends. Marks the session as complete.

Start Interaction

Creates the interaction and sets its start time. Adds the initial set of participants and metadata.

Endpoint

POST https://[INSTANCE NAME].audio.tethr.com/callCapture/v1/live/interactionStarted

Required Fields

Field	Description
`sessionId`	Predefined by your platform, unique per interaction. See Session ID Behavior below.
`utcTimestamp`	Start time of the interaction, in UTC, ISO 8601 format.
`participants`	See Participants below.
`metadata.campaign`	Agent Assist campaign name/alias — must match exactly.
`metadata.username`	Agent Assist username — must match exactly, case-sensitive.

Participants

Every participant who may generate an utterance (audio or chat) needs an entry here — this is how incoming utterances get attributed to the right person.

Field	Required	Notes
`refType`	Yes, for every participant	`Agent` or `Customer`
`refId`	Yes, for Agent. Optional for Customer, but recommended for better identification	Identifier for the participant — typically an email or employee ID
`channel`	Yes, for every participant	Must match the channel used on that participant's utterances
`email` / `phone` / `firstName` / `lastName`	No	Provide if available
`sourceId` / `timestamp`	No	Each can be used on its own, or together. timestamp alone can mark the point at which a participant takes over a channel — any utterances after that time on that channel are assigned to them. sourceId distinguishes participants sharing a channel at the same time from different sources. Most integrations sending one agent + one customer on separate channels can omit both.

Requirements

Username must match the Agent Assist username exactly, case-sensitive.
Campaign must match a campaign name or configured alias in Agent Assist — see Awaken — Campaigns Module.

Session ID Behavior

sessionId must be predefined by your platform and is passed to Agent Assist as the reference number.

Reusing a sessionId loads the previous record rather than starting fresh. Generate a new, unique sessionId per interaction in most cases — though this can be used deliberately in outbound campaigns, where reusing the ID for repeat dials to the same customer surfaces prior notes and data.

Example 1

This covers the most common scenario: one agent and one customer, each on their own channel, with nothing else needed to tell participants apart.

{
    "sessionId": "UNIQUE-SESSION-ID",
    "utcTimestamp": "2026-07-27T13:19:00Z",
    "participants": [
        {
            "refType": "Agent",
            "refId": "agent@yourcompany.com",
            "channel": "0",
            "firstName": "Jane",
            "lastName": "Smith"
        },
        {
            "refType": "Customer",
            "channel": "1",
            "phone": "5555559876",
            "firstName": "John",
            "lastName": "Doe"
        }
    ],
    "metadata": {
        "campaign": "AGENT-ASSIST-CAMPAIGN-NAME",
        "username": "AGENT-ASSIST-USERNAME"
    }
}

Example 2

Use this API call if your platform can put more than one participant on the same channel over time — for example, a warm transfer where a second agent joins on the same channel later in the call.

{
    "sessionId": "UNIQUE-SESSION-ID",
    "utcTimestamp": "2026-07-27T13:19:00Z",
    "participants": [
        {
            "refType": "Agent",
            "refId": "jane.smith@yourcompany.com",
            "channel": "0",
            "sourceId": "agent-leg-1",
            "timestamp": "2026-07-27T13:19:00Z"
        },
        {
            "refType": "Customer",
            "channel": "1",
            "sourceId": "customer-leg-1",
            "timestamp": "2026-07-27T13:19:00Z"
        }
    ],
    "metadata": {
        "campaign": "AGENT-ASSIST-CAMPAIGN-NAME",
        "username": "AGENT-ASSIST-USERNAME"
    }
}

If a second agent joins the same channel partway through, add them via a subsequent call. A timestamp alone is enough to mark when they took over that channel — utterances after that point will be assigned to them. Add sourceId as well if more than one participant could be on the same channel at the same time.

Complete Interaction

Marks the interaction as completed at a given time. Additional data can still be sent after completion if needed.

Endpoint

POST https://[INSTANCE NAME].audio.tethr.com/callCapture/v1/live/interactionComplete

Request Body

{
    "sessionId": "UNIQUE-SESSION-ID",
    "utcTimestamp": "2026-07-27T13:24:00Z",
    "metadata": {}
}

Field	Required	Description
`sessionId`	Yes	Must match the `sessionId` used in the corresponding Start Interaction call.
`utcTimestamp`	Yes	End time of the interaction, in UTC, ISO 8601 format.
`metadata`	No	Any additional key-value data to pass through.

Was this article helpful?