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. If you build voice workflows in Dograh, see Connecting to Dograh. 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)
  • sip_call_id (inbound simulation only): the SIP Call-ID from the inbound call, required to link inbound simulated calls back to their Tuner simulation row. See SIP for other platforms.
  • recipient (outbound simulation only): the SIP URI your system dialed, exactly as Tuner sent it, required to link outbound simulated calls back to their Tuner simulation row. See Outbound Simulation.

​
Authentication

All API requests use Bearer authentication. Send your Tuner API key in the Authorization header (copy it from Workspace Settings → API Keys & Integrations):
  • 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

​
Libraries

You don’t always have to build the timeline against the raw API by hand. Tuner ships small, focused libraries that each handle one part of a Custom Integration — typically capturing events from a specific framework and shaping them into a Tuner-ready transcript, so you write less plumbing and get cleaner data in. Libraries are optional: use one if it fits your stack, or call the Create Call API directly if it doesn’t. Available libraries:

LangChain / LangGraph

Observability for LangChain & LangGraph agents — captures node transitions, tool calls, and results into the Tuner transcript pipeline.

​
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 Vapi

Connecting to LiveKit

Connecting to Pipecat

Connecting to Dograh