Conversation Sessions

View and manage conversation sessions for assistant graphs

Conversation sessions track multi-assistant conversations as they flow through a graph. Each session maintains context, transition history, and the current state of the conversation.

List Graph Sessions

graph_id · integer · required

The unique identifier of the graph.

skip · integer · default: "0"

Number of items to skip for pagination.

limit · integer · default: "100"

Maximum number of items to return (1-1000).

active_only · boolean · default: "false"

When true, only returns active (ongoing) sessions.

Response

Returns an array of conversation session objects.

[] · array

Array of conversation sessions.

Show Session properties

id · integer

Session ID

call_sid · string

Unique call identifier

graph_id · integer

Associated graph ID

current_node_id · integer

Current node in the graph

context · object

Shared conversation context

started_at · string

Session start timestamp

ended_at · string

Session end timestamp (null if active)

is_active · boolean

Whether session is ongoing

current_assistant_name · string

Name of current assistant

graph_name · string

Name of the graph

List Sessions

curl "https://api.burki.dev/api/v1/assistant-graphs/1/sessions?limit=10&active_only=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

List Sessions Response

[
  {
    "id": 501,
    "call_sid": "CA1234567890abcdef",
    "graph_id": 1,
    "current_node_id": 102,
    "context": {
      "customer_name": "John",
      "inquiry_type": "sales",
      "product_interest": "enterprise plan"
    },
    "started_at": "2025-01-19T14:30:00Z",
    "ended_at": null,
    "is_active": true,
    "current_assistant_name": "Sales Specialist",
    "graph_name": "Customer Service Router"
  },
  {
    "id": 500,
    "call_sid": "CA0987654321fedcba",
    "graph_id": 1,
    "current_node_id": 103,
    "context": {
      "customer_name": "Jane",
      "inquiry_type": "support",
      "issue_resolved": true
    },
    "started_at": "2025-01-19T13:00:00Z",
    "ended_at": "2025-01-19T13:15:00Z",
    "is_active": false,
    "current_assistant_name": "Support Agent",
    "graph_name": "Customer Service Router"
  }
]

---

Get Session by Call SID

Retrieve a specific conversation session by its call SID.

call_sid · string · required

The unique call identifier (SID) for the session.

Get Session

curl https://api.burki.dev/api/v1/assistant-graphs/sessions/CA1234567890abcdef \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Session Response

{
  "id": 501,
  "call_sid": "CA1234567890abcdef",
  "graph_id": 1,
  "current_node_id": 102,
  "context": {
    "customer_name": "John",
    "inquiry_type": "sales",
    "product_interest": "enterprise plan",
    "transition_count": 1,
    "initial_greeting_complete": true
  },
  "started_at": "2025-01-19T14:30:00Z",
  "ended_at": null,
  "is_active": true,
  "current_assistant_name": "Sales Specialist",
  "graph_name": "Customer Service Router"
}

---

Understanding Session Context

The context object in a session is a shared state that persists across assistant transitions. It’s used to:

1. Pass Information: Share customer data between assistants
2. Track State: Store conversation state variables
3. Enable Conditions: Provide data for state variable transition conditions

Context Example

{
  "customer_name": "John Smith",
  "account_number": "12345",
  "inquiry_type": "billing",
  "issue_description": "Overcharge on last invoice",
  "sentiment": "frustrated",
  "previous_assistants": ["receptionist", "billing"],
  "escalation_requested": false,
  "call_duration_at_transition": 180
}

Assistants can read from and write to the session context during the conversation. Use descriptive key names to make the context self-documenting.

---

Error Responses

Status Code	Description
401	Unauthorized - Invalid or missing API key
404	Graph or session not found in your organization
500	Server error retrieving sessions