Skip to main content

​
When to Use Custom Integration

Use Custom Integration If...

  • You built your own voice AI platform
  • You’re using a provider not yet supported by Tuner
  • You need full control over when and how data is sent

Use Native Integration If...

  • You’re using Retell, Vapi, or another supported provider
  • You want automatic webhook configuration
  • You prefer a no-code setup

​
What You’ll Need

Before you begin, make sure you have:
1

A Tuner Account

Sign up at tuner.ai if you haven’t already.
2

Generate Your API Key

Navigate to Workspace Settings > API Keys in your Tuner dashboard and generate a new API key. Keep this key secure—you’ll need it to authenticate your API requests.
3

Create a New Agent

In your Tuner dashboard, click Add New Agent and select Custom API as the integration type.
4

Set Your Agent ID

Enter your Agent ID (also called Agent Remote Identifier). This is the unique identifier that links calls from your voice platform to this agent in Tuner.
The Agent ID must match the agent identifier used in your voice platform. This ensures that call data sent to Tuner is correctly associated with the right agent. If your voice platform already assigns an agent ID, use that exact same ID here.
5

Complete Agent Setup & Send Your First Call

Finish configuring your agent settings (name, system prompt, evaluation criteria). For guidance on setting up evaluations, see Creating Custom Evaluations and Classifying Calls.Once configured, use the API to send your first call data. See the examples below to get started.

​
Integration Overview

The integration process is straightforward:
  1. After each call ends in your voice AI platform, collect the transcript and metadata.
  2. Send the call data to Tuner using the Create Call API.
  3. Tuner processes the call and runs it through your configured evaluations.
  4. View results in your Tuner dashboard.

​
API Endpoint

Full URL: https://api.usetuner.ai/api/v1/public/call Method: POST

​
Authentication

Include your API key in the X-API-Key header: 
X-API-Key: YOUR_API_KEY
You can generate API keys in Workspace Settings > API Keys from your Tuner dashboard.

​
Required Parameters

​
Query Parameters

ParameterTypeDescriptionWhere to Find
workspace_idnumberYour Tuner workspace IDworkspace-settings > General Settings
agent_remote_identifierstringYour Agent IDagent-settings > Agent Connection > Agent ID

​
Body Parameters

ParameterTypeDescriptionExample
call_idstringA unique identifier for this call from your system"call_12345"
call_typestringThe type of call interaction. Use this to distinguish between different communication channels."phone_call"
transcript_with_tool_callsobject[]Array of messages in the conversationSee format below
start_timestampintegerEpoch timestamp of when the call ended1705392000000
end_timestampintegerEpoch timestamp of when the call ended1705392000000
recording_urlstringURL to the audio recording of the call. Tuner will use this for audio analysis and playback in the dashboard."https://..."

​
Transcript Format

The transcript_with_tool_calls field accepts an array of message objects. Each message should have a role and content: 
[
  {"role": "agent", "content": "Hello, how can I help you today?"},
  {"role": "user", "content": "I'd like to book an appointment."},
  {"role": "agent", "content": "Of course! What date works best for you?"}
]

​
User Sentiment Values

When sending the user_sentiment field in your call data, it is highly recommended to use one of the following standardized values:
ValueDescription
positiveThe user expressed satisfaction or positive emotions
neutralThe user’s tone was neither positive nor negative
negativeThe user expressed frustration, dissatisfaction, or negative emotions
unknownThe sentiment could not be determined
While the API will accept other values without returning an error, using non-standard sentiment values may result in inconsistent reporting and analytics in your Tuner dashboard. For best results, always use one of the four recommended values above.

​
Sending Call Data

Send Call Data API Reference

View the complete API documentation with all available parameters, response formats, and error codes.

​
Example Request

curl --request POST \
  --url 'https://api.usetuner.ai/api/v1/public/call?workspace_id=123&agent_remote_identifier=agent_abc123' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "call_id": "call_12345",
    "call_type": "phone_call",
    "transcript_with_tool_calls": [
      {"role": "agent", "content": "Hello, thank you for calling. How can I help you today?"},
      {"role": "user", "content": "Hi, I would like to book an appointment for next week."},
      {"role": "agent", "content": "Of course! I can help you with that. What day works best for you?"},
      {"role": "user", "content": "How about Tuesday at 2pm?"},
      {"role": "agent", "content": "Tuesday at 2pm is available. I have booked that for you. Is there anything else I can help with?"},
      {"role": "user", "content": "No, that is all. Thank you!"},
      {"role": "agent", "content": "You are welcome. Have a great day!"}
    ],
	"start_timestamp": 1705392000000,
    "end_timestamp": 1705392000000,
    "recording_url": "https://your-storage.com/recordings/call_12345.mp3"
  }'
For the best monitoring results, include as much data as possible: timestamps, duration, user sentiment, and the full transcript.

​
Response

A successful request returns a 201 Created response: 
{
  "id": 12345,
  "provider_call_id": "call_12345",
  "is_new": true
}
FieldDescription
idTuner’s internal ID for this call
provider_call_idThe call_id you provided
is_newWhether this is a new call or an update

​
Best Practices

Send call data to Tuner as soon as each call ends. This keeps your dashboard up-to-date and enables real-time alerting.
Always send the full conversation transcript. Partial transcripts may result in incomplete evaluations.
Use your platform’s unique call identifier as the call_id. This makes it easy to correlate calls between systems.
Implement retry logic with exponential backoff. If a request fails, store the call data locally and retry later.
Always include the recording_url so you can play back the audio directly in the Tuner dashboard for deeper analysis.

​
Troubleshooting

Check that all required fields are present: workspace_id and agent_remote_identifier in the query string, and call_id, call_type, transcript_with_tool_calls, end_timestamp, and recording_url in the body.
Verify your API key is correct and included in the X-API-Key header.
Ensure the agent_remote_identifier matches an agent you’ve created in Tuner. Check that the workspace_id is correct.

​
Next Steps

Once your integration is working, explore these resources to get the most out of Tuner:

How to Review Your First Call

Learn how to review and analyze calls in the Tuner dashboard.

Creating Custom Evaluations

Set up custom evaluations to automatically assess call quality.
Using a Supported Provider? If you’re using Retell, Vapi, or another supported platform, check out our native integration guides for a simpler setup experience.

Connecting to Retell

Connect your Retell agent to Tuner with automatic webhook configuration.