Skip to main content

​
SDK integrations available

If you use LiveKit Agents, our SDK makes integration easier — no manual API calls. See Connecting to LiveKit. If you use Pipecat Flows, see Connecting to Pipecat. Use this guide if you have a custom voice stack or a platform we don’t yet support with an SDK.

​
What this is

Custom Integration lets you push completed call data (transcript + metadata) from your own voice stack into Tuner so Tuner can process the call and run your configured analyses.

​
The Contract

To make calls show up under the right agent, your integration must consistently map these identifiers:
  • workspace_id: the Tuner workspace receiving the call
  • agent_remote_identifier: Your Agent ID configured in Tuner. Get this value from Agent Settings > Agent Connection > Agent ID
  • call_id: your unique identifier for the call (use the same value every retry)

​
Authentication

All API requests use Bearer authentication. Send your Tuner API key in the Authorization header:
  • Authorization: Bearer <YOUR_TUNER_API_KEY>

​
Happy Path

  1. Create a Tuner Agent and select Custom API as the integration type.
  2. In your voice system, after the call ends, capture:
    • the full structured conversation timeline (including agent and user messages, tool calls, and any node or state transitions)
    • call start and end timestamps
    • a publicly accessible recording URL
    • any relevant operational or enrichment data (for example: cost data, call outcome, dynamic variables, or provider-native analysis)
  3. Call the Create Call endpoint with all data based on the API reference
  4. Open Tuner → Calls to see the processed results.

​
API Reference

See the full Create Call request/response schema and examples: → Create Call API Reference

​
Best practices (what keeps integrations stable)

  • Make retries safe: Treat call_id as immutable and retry the same request on failure.
  • Send the final transcript: If you only have partial transcripts, send only when final to avoid incomplete analysis.
  • Log request IDs + responses: You’ll want these when debugging ingestion issues.

​
Common issues

​
Calls don’t appear in Tuner

Usually one of:
  • wrong workspace_id
  • agent_remote_identifier doesn’t match the agent mapping you intended
  • the call was sent but the transcript is empty/invalid

​
Unauthorized (401)

  • Ensure you’re sending Authorization: Bearer <API_KEY> (not X-API-Key).

​
Validation errors (4xx)

  • Follow the API reference for required fields and types.
  • If you’re unsure which field failed, start from the minimal example in the API reference and add fields incrementally.

​
Next steps

Review your first call

Connecting to Retell

Connecting to LiveKit

Connecting to Pipecat