Conversations

A conversation is the record of everything that happened during an agent call: who said what, when, the outcome of any data collection the agent performed, and metadata about the call itself. Every completed call produces a conversation record that can be retrieved and queried afterwards.

Two ways to have a conversation

Agents support two conversation modes: voice and text-only. Both produce the same conversation record on completion.

Voice

Voice is the primary mode. An agent with a SIP UAC configured registers to your telephony platform as a SIP user agent. Calls arrive over SIP — no API call is needed to start them. The agent answers, speaks with the caller, and ends the call when the conversation concludes. From the caller's perspective it is a normal phone call.

The agent can:

• Receive inbound calls routed to it by the PBX
• Initiate outbound calls to specified numbers
• Transfer calls to another extension or number — both cold (unattended) and warm (attended) transfers

Text-only

Text-only sessions are created via the API and are suited for chat-style integrations — a web widget, a mobile app, or a testing environment. Create a session to receive a token and connection URL for the real-time SDK:

curl -X POST https://api.simwood.com/convai/v1/agents/<agent-id>/conversations \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "dynamic_variables": {
        "customer_name": "Jane Smith"
      }
    }
  }'

The response includes:

{
  "id": "conv-uuid-...",
  "agent_id": "agent-uuid-...",
  "room_name": "room-...",
  "ws": {
    "url": "wss://...",
    "token": "eyJ...",
    "text_only": true
  }
}

Connect with the real-time SDK using ws.url and ws.token. The session ends when the SDK disconnects.

Conversation record

Once a conversation ends — whether voice or text-only — the record is available via the conversations API:

# List conversations for an agent
curl https://api.simwood.com/convai/v1/agents/<agent-id>/conversations \
  -H "Authorization: Bearer sk_live_..."

# Retrieve a specific conversation
curl https://api.simwood.com/convai/v1/agents/<agent-id>/conversations/<conversation-id> \
  -H "Authorization: Bearer sk_live_..."

Transcript

The transcript array is the turn-by-turn record of the conversation:

"transcript": [
  {
    "role": "agent",
    "message": "Hello, thanks for calling. How can I help you today?",
    "time_in_call_secs": 0.0
  },
  {
    "role": "user",
    "message": "I'd like to cancel my subscription.",
    "time_in_call_secs": 3.4
  }
]

Each turn has role (agent or user), message, time_in_call_secs, and — when applicable — tool_calls and tool_results from any tools the agent invoked.

Analysis

If the agent was configured with analysis.data_collection, the analysis field on the conversation record contains the extracted values:

"analysis": {
  "data_collection_results": {
    "customer_intent": "cancel subscription",
    "issue_resolved": true
  },
  "call_successful": "success",
  "transcript_summary": "Caller wanted to cancel their subscription. Agent confirmed cancellation."
}

Metadata

"metadata": {
  "start_time_unix_secs": 1719820800,
  "accepted_time_unix_secs": 1719820802,
  "call_duration_secs": 143
}

status reflects the outcome: done, failed, or in-progress for a call that is still active.

Deleting a conversation

curl -X DELETE https://api.simwood.com/convai/v1/agents/<agent-id>/conversations/<conversation-id> \
  -H "Authorization: Bearer sk_live_..."