Calls
Retrieve call recording URLs and flow execution runs associated with calls through the Talkturo API — access pre-signed recording links and TurboFlow run history.
curl --request GET \
--url "https://app.talkturo.com/api/calls/cal_7f3c2a91-6f2d-4e1f-9f6a-2d8f3a1b4c55/recording-url" \
--cookie "sb-access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example; sb-refresh-token=v1.example.refresh"
const response = await fetch(
"https://app.talkturo.com/api/calls/cal_7f3c2a91-6f2d-4e1f-9f6a-2d8f3a1b4c55/recording-url",
{
method: "GET",
credentials: "include",
headers: {
"Accept": "application/json"
}
}
);
const data = await response.json();
console.log(data);
{
"url": "https://talkturo-recordings.s3.amazonaws.com/calls/2024/09/cal_7f3c2a91-6f2d-4e1f-9f6a-2d8f3a1b4c55-stereo.wav?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=talkturo-prod%2F20240920%2Fus-east-1%2Fs3%2Faws4_request",
"expiresIn": 600
}
{
"error": "Missing call ID"
}
{
"error": "Forbidden"
}
{
"error": "Call not found or no recording available"
}
{
"error": "S3 is not configured"
}
curl --request GET \
--url "https://app.talkturo.com/api/calls/cal_7f3c2a91-6f2d-4e1f-9f6a-2d8f3a1b4c55/flow-runs" \
--cookie "sb-access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example; sb-refresh-token=v1.example.refresh"
const response = await fetch(
"https://app.talkturo.com/api/calls/cal_7f3c2a91-6f2d-4e1f-9f6a-2d8f3a1b4c55/flow-runs",
{
method: "GET",
credentials: "include",
headers: {
"Accept": "application/json"
}
}
);
const data = await response.json();
console.log(data.runs);
{
"runs": [
{
"id": "run_2bd91cc8-4a62-4d83-a684-bf923f6f1e11",
"flowId": "flo_8b7bda66-957d-4bb4-92a4-38a2702a6651",
"name": "Post-call follow-up",
"status": "completed",
"startedAt": "2024-09-20T14:22:18.000Z",
"finishedAt": "2024-09-20T14:22:24.000Z",
"error": null,
"input": {
"call_id": "cal_7f3c2a91-6f2d-4e1f-9f6a-2d8f3a1b4c55",
"outcome": "answered"
}
},
{
"id": "run_3e96c5d2-0f44-4d0d-b26c-1c2cae91878c",
"flowId": "flo_8b7bda66-957d-4bb4-92a4-38a2702a6651",
"name": "Transcript sync",
"status": "failed",
"startedAt": "2024-09-20T14:25:09.000Z",
"finishedAt": "2024-09-20T14:25:10.000Z",
"error": "Webhook endpoint returned 502",
"input": {
"call_id": "cal_7f3c2a91-6f2d-4e1f-9f6a-2d8f3a1b4c55",
"recording_ready": true
}
}
]
}
{
"error": "Missing ID"
}
{
"error": "Forbidden"
}
{
"error": "Call not found"
}
{
"error": "Internal server error"
}
curl --request POST \
--url "https://app.talkturo.com/api/crm/calls" \
--header "Authorization: Bearer dkai_example_9xmk7q2r" \
--header "Content-Type: application/json" \
--data '{
"assistant_id": "asst_4e8f7c21-6d3a-4b92-9a1e-2f6c8d7b5a40",
"to_number": "+14155550128",
"from_number": "+14155550100",
"metadata": {
"contact_id": "contact_8f3a21c9",
"source": "crm"
}
}'
curl --request POST \
--url "https://app.talkturo.com/api/crm/calls" \
--cookie "sb-access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example; sb-refresh-token=v1.example.refresh" \
--header "Content-Type: application/json" \
--data '{
"assistant_id": "asst_4e8f7c21-6d3a-4b92-9a1e-2f6c8d7b5a40",
"to_number": "+14155550128",
"metadata": {
"contact_id": "contact_8f3a21c9",
"source": "crm"
}
}'
{
"success": true,
"roomName": "crm-call-8f3a21c9-1726842138",
"sipCallId": "sip_5c7e9a12-3b64-4d8f-a201-6e9c2b7d4f50",
"to_number": "+14155550128"
}
Endpoint summary
| Method | Path | Purpose | Auth |
|---|---|---|---|
GET | /api/calls/{id}/recording-url | Get a pre-signed recording URL for a call | Session cookie |
GET | /api/calls/{id}/flow-runs | List TurboFlow runs associated with a call | Session cookie |
GET | /api/transcripts | Retrieve call transcripts | Session cookie |
POST | /api/crm/calls | Start an outbound CRM call | API key or session |
GET | /api/summaries | Retrieve call summaries | Session cookie |
Both endpoints require an authenticated Talkturo session cookie. The API checks that your user belongs to the workspace that owns the call before returning data. The CRM calls endpoint also supports API key authentication with the calls:create scope.
Get recording URL
Retrieve a short-lived pre-signed URL for a call recording. If both mono and stereo recordings exist, the API returns the stereo recording URL.
Path parameters
The call UUID. The API uses this ID to load the call, verify workspace membership, and locate the recording asset.
Response fields
A pre-signed S3 URL for the recording file. The URL expires after a short time and cannot be reused indefinitely.
The number of seconds until the pre-signed URL expires. The current value is 600.
Errors and behavior
Treat the recording URL as temporary and sensitive. Do not store it as a permanent asset URL, and do not expose it to users who should not have access to the call recording.
400— The request did not include a call ID.403— Your session is valid, but your user is not a member of the workspace that owns the call.404— The call does not exist, or the call exists but has no recording available.500— Recording URL generation failed because S3 is not configured.
Get flow runs for a call
List TurboFlow runs associated with a call. The API finds runs by matching the call ID against the call_id value stored in each run's context.
Path parameters
The call UUID. The API loads the call first, verifies that your user can access the call's workspace, then returns matching flow runs.
Response fields
The list of TurboFlow runs associated with the call. The array is empty when no runs reference the call ID.
The unique flow run identifier.
The TurboFlow identifier for the flow that produced the run.
The flow name at the time the API returns the run data.
The run status, such as completed, failed, or running.
The ISO 8601 timestamp when the run started.
The ISO 8601 timestamp when the run finished. This field is null for runs that are still in progress.
The run error message when execution failed. This field is null for successful runs.
The input payload or extracted context associated with the run. Its exact shape depends on the flow trigger and execution context.
Errors and behavior
400— The request did not include a call ID.403— Your user is authenticated but is not a member of the workspace that owns the call.404— The call does not exist.500— The server failed to query associated flow runs.
Retrieve transcripts
Retrieve call transcripts for the authenticated workspace. Supports optional filtering by call ID or date range.
Endpoint
GET /api/transcripts
Query parameters
Filter transcripts by a specific call ID.
Maximum number of transcripts to return.
Number of transcripts to skip for pagination.
Response fields
Array of transcript objects. Each transcript includes the call ID, transcript text, segments, and timestamps.
Total number of transcripts matching the query.
Retrieve summaries
Retrieve call summaries for the authenticated workspace. Supports optional filtering by call ID or date range.
Endpoint
GET /api/summaries
Query parameters
Filter summaries by a specific call ID.
Maximum number of summaries to return.
Number of summaries to skip for pagination.
Response fields
Array of summary objects. Each summary includes the call ID, summary text, key outcomes, and metadata.
Total number of summaries matching the query.
Start an outbound CRM call
Start an outbound call for a CRM contact using an assistant and destination phone number. Authenticate with an API key that has the calls:create scope or with an authenticated Talkturo session cookie.
Body parameters
The assistant to use for the call.
The destination phone number. The value must contain at least four characters.
The phone number to use as the caller ID. If omitted, the API uses the first active number assigned to the assistant.
Additional metadata passed into the room metadata.
Response fields
Indicates whether the outbound CRM call started successfully.
The room name created for the call.
The SIP call identifier for the outbound call.
The destination phone number used for the call.
Notes on access control
Both endpoints are scoped to the call's workspace, not only to the call ID itself. A valid session cookie is not enough on its own; your user must also belong to the workspace that owns the call.
If you need call details, transcripts, or other call-facing resources alongside these endpoints, use the same authenticated browser session or server-side session context that you already use for the rest of the Talkturo app.