Get conversation by ID
GET
https://api.telvana.com/conversation/{id}
Retrieve details of a specific conversation including transcript and analytics.
A conversation is written when its call ends. Until then, and for an id that is not in your workspace, the response is 200 with "data": null. recordingUrl is a signed link that expires an hour after the request.
Path parameters
| Name | Description |
|---|---|
id
string
required
|
Unique identifier for the conversation |
Example request
curl "https://api.telvana.com/conversation/{id}" \
-H "x-api-key: $TELVANA_API_KEY"Response 200
Conversation retrieved successfully. Errors use the format in Errors .
Fields in data
| Name | Description |
|---|---|
id
string
|
ID of conversation |
dateInitiated
string (date-time)
|
Date initialized of conversation (ISO timestamp) |
agentId
string
|
ID of Agent used in the conversation |
direction
INBOUND | OUTBOUND
|
Direction of call: OUTBOUND (Calling a Human) or INBOUND (Incoming Call from Human) |
tags
array of string
|
Zero or more tags for the conversation (built-in and custom) |
summary
string | null
|
AI-generated summary of the conversation |
durationSeconds
number
|
Precise call duration in seconds |
cost
number
|
Cost of the call in cents |
humanPhoneNumber
string
|
The customer/human's phone number |
agentPhoneNumber
string
|
The phone number used by the AI agent |
sentimentClassification
POSITIVE | NEUTRAL | NEGATIVE | N_A | null
|
Sentiment classification of the conversation. N_A indicates no sentiment is available (e.g., the call failed to connect). |
transcript
string
|
Full text transcript of the conversation |
recordingUrl
string
|
Pre-signed S3 URL for downloading the audio recording (expires in 1 hour) |
Example response
{
"data": {
"id": "clx8y9z1a2b3c4d5e6f7g8h9i",
"dateInitiated": "2025-12-01T14:30:00.000Z",
"agentId": "agent_abc123",
"direction": "OUTBOUND",
"tags": [
"appointment_booked"
],
"summary": "Successfully confirmed customer appointment for tomorrow at 2:00 PM. Customer was polite and confirmed availability.",
"durationSeconds": 210,
"cost": 125,
"humanPhoneNumber": "+15551234567",
"agentPhoneNumber": "+15559876543",
"sentimentClassification": "POSITIVE",
"transcript": "Agent: Hello, this is Sarah from Telvana calling to confirm your appointment tomorrow at 2:00 PM. Is this still convenient for you?\n\nCustomer: Yes, that works perfectly. Thank you for calling to confirm.\n\nAgent: Great! We look forward to seeing you tomorrow. Have a wonderful day!\n\nCustomer: Thank you, you too!",
"recordingUrl": "https://s3.amazonaws.com/recordings/clx8y9z1a2b3c4d5e6f7g8h9i.wav"
}
}Get conversations list
GET
https://api.telvana.com/conversations
Retrieve a list of conversations with optional filtering. Results are ordered by date initiated (most recent first).
The response is { "data": [ ... ] }, newest first. A limit above 100 is refused with a 400. Page with skip: request again with skip raised by limit until a page comes back shorter than limit.
Query parameters
| Name | Description |
|---|---|
datetime_start
integer
|
Start timestamp for filtering conversations (Unix timestamp in milliseconds, e.g., 1764547200000) |
datetime_end
integer
|
End timestamp for filtering conversations (Unix timestamp in milliseconds, e.g., 1764720000000) |
agent_id
string
|
Filter by agent ID |
direction
INBOUND | OUTBOUND
|
Filter by call direction |
sentiment
POSITIVE | NEUTRAL | NEGATIVE
|
Filter by sentiment classification |
limit
integer
|
Number of records to return (default: 50, max: 100) (1 to 100, default 50) |
skip
integer
|
Number of records to skip for pagination (default: 0) (default 0) |
Example request
curl "https://api.telvana.com/conversations?limit=10" \
-H "x-api-key: $TELVANA_API_KEY"Response 200
Conversations retrieved successfully. Errors use the format in Errors .
Fields in data
| Name | Description |
|---|---|
id
string
|
ID of conversation |
dateInitiated
string (date-time)
|
Date initialized of conversation (ISO timestamp) |
agentId
string
|
ID of Agent used in the conversation |
direction
INBOUND | OUTBOUND
|
Direction of call: OUTBOUND (Calling a Human) or INBOUND (Incoming Call from Human) |
tags
array of string
|
Zero or more tags for the conversation (built-in and custom) |
summary
string | null
|
AI-generated summary of the conversation |
durationSeconds
number
|
Precise call duration in seconds |
cost
number
|
Cost of the call in cents |
humanPhoneNumber
string
|
The customer/human's phone number |
agentPhoneNumber
string
|
The phone number used by the AI agent |
sentimentClassification
POSITIVE | NEUTRAL | NEGATIVE | N_A | null
|
Sentiment classification of the conversation. N_A indicates no sentiment is available (e.g., the call failed to connect). |
transcript
string
|
Full text transcript of the conversation |
recordingUrl
string
|
Pre-signed S3 URL for downloading the audio recording (expires in 1 hour) |
Example response
{
"data": [
{
"id": "clx8y9z1a2b3c4d5e6f7g8h9i",
"dateInitiated": "2025-12-01T14:30:00.000Z",
"agentId": "agent_abc123",
"direction": "OUTBOUND",
"tags": [
"appointment_booked"
],
"summary": "Successfully confirmed customer appointment for tomorrow at 2:00 PM. Customer was polite and confirmed availability.",
"durationSeconds": 210,
"cost": 125,
"humanPhoneNumber": "+15551234567",
"agentPhoneNumber": "+15559876543",
"sentimentClassification": "POSITIVE",
"transcript": "Agent: Hello, this is Sarah from Telvana calling to confirm your appointment tomorrow at 2:00 PM. Is this still convenient for you?\n\nCustomer: Yes, that works perfectly. Thank you for calling to confirm."
}
]
}