Developer Quick Start

A step-by-step guide to integrating your voice AI with Tuner. Choose between no-code integration for supported platforms or API integration for custom setups. In just a few minutes, you’ll have your first call analyzed.

Prerequisites: You’ll need an active Tuner account to follow this guide. Sign up here if you haven’t already.

Overview

Here’s what we’ll accomplish:

1. Set up Retell / Vapi keys (if needed)

   For Retell or Vapi, add your platform key in Workspace Settings before you create an agent.

2. Create Your Agent

   Add New Agent, enter name, Agent ID, and provider, then set up with MCP or blank.

3. Send Your First Call

   Make a test call or send sample data to verify the integration.

4. Customize Your Agent

   Review and edit what MCP created, or configure manually if you started blank — outcomes, intents, evaluations, alerts.

Estimated time: 5 minutes from start to finish

---

Step 1: Set up workspace keys

For Retell and Vapi, add your platform API key under Workspace Settings → API Keys & Integrations before you create an agent.

Choose the tab that matches how you ingest calls:

No-Code (Retell)

Retell API key

1. In the Retell dashboard, create or copy an API Key from Settings → API Keys.
2. In Tuner, open Workspace Settings (gear icon in the sidebar).
3. Under API Keys & Integrations, paste your key into Retell API Key, then click Save Changes.

Full walkthrough (Agent ID + create agent after keys): Connecting to Retell.

No-Code (Vapi)

Vapi Private API key

1. In the Vapi dashboard, copy a Private API Key (not the Public key) — for example from dashboard.vapi.ai/org/api-keys.
2. In Tuner, open Workspace Settings (gear icon in the sidebar).
3. Under API Keys & Integrations, paste your key into Vapi API Key, then click Save Changes.

Full walkthrough (Assistant ID + create agent after keys): Connecting to Vapi.

LiveKit, Pipecat & Custom API

Tuner API key

LiveKit, Pipecat, and Custom API integrations all use the same Tuner Custom API key from your workspace:

1. Open Workspace Settings → API Keys & Integrations.
2. Find Tuner Custom API, copy or reveal the key, and store it securely. Use Regenerate if you need to rotate it.

Then follow the guide for your stack:

• Connecting to LiveKit — Tuner plugin for LiveKit Agents
• Connecting to Pipecat — FlowsObserver for Pipecat Flows
• Custom Integration — send call data with the REST API

---

Step 2: Create Your Agent

If you use Retell or Vapi, save you platform API keys in Workspace Settings first. See Step 1.

In the sidebar, click the Add New Agent. button

Choose your integration

No-Code (Retell)

Connect your Retell account — Tuner receives call data automatically. ~2 min

No-Code (Vapi)

Connect your Vapi account — Tuner receives call data automatically. ~2 min

Custom API

Use our LiveKit SDK or Pipecat SDK (~2 min), or send data via the REST API directly (~5 min).

Fill in the form and create the agent

In the Create a New Agent modal, complete the required fields:

1. Agent Name — A display name for this agent in Tuner.

2. Call Direction — Inbound or Outbound, depending on how the agent is used.

3. Provider — retell, vapi, or API, matching how call data reaches Tuner.

4. Agent Remote ID — How this works depends on your provider:

   • Retell / Vapi: Copy the agent ID from your provider’s dashboard and paste it here. The Agent Remote ID must match the identifier used in your voice platform so calls map to the right agent in Tuner
   • Custom API / LiveKit / Pipecat: Tuner auto-generates this for you. You’ll use it in your API requests.

5. Click Create agent.

Set up your agent (MCP or blank)

After the agent is created, you’ll see How do you want to configure this agent? Choose how to finish setup:

• Configure via MCP (recommended) — Use your IDE (Cursor, Claude Code, Antigravity) or a chat app with the Tuner MCP server so MCP can generate and update outcomes, intents, evaluations, and alerts. Recommended for complex agents.
• Start from blank — Configure those items manually inside Tuner.

Click Continue after you choose. You can also pick I’ll do this later and configure from Agent Settings when you’re ready.

---

Step 3: Send Your First Call

No-Code (Retell)

Make a Test Call

With your Retell account connected, simply make a test call to your Retell agent. The call data will automatically appear in Tuner within seconds.

1. Trigger a call to your Retell agent
2. Complete a short conversation
3. End the call

No-Code (Vapi)

Make a Test Call

With your Vapi account connected, make a test call to your Vapi assistant. The call data will automatically appear in Tuner within seconds.

1. Trigger a call to your Vapi assistant (for example from the Vapi dashboard or your app)
2. Complete a short conversation
3. End the call

SDK (LiveKit)

Run Your Agent

With the Tuner plugin added to your LiveKit agent, run your agent and complete a test session. Call data is automatically sent to Tuner when the session ends.

1. Start your LiveKit agent with the Tuner plugin configured
2. Complete a short conversation
3. End the session — the plugin submits the call data automatically

SDK (Pipecat)

Run Your Pipeline

With the FlowsObserver added to your Pipecat pipeline, run your agent and complete a test session. Call data is automatically sent to Tuner when the call ends.

1. Start your Pipecat pipeline with the FlowsObserver configured
2. Complete a short conversation
3. End the call — the observer submits the call data automatically

API Integration

Send Your First Call via API

Send a POST request to the Tuner API endpoint with your call data. Each request requires the following:

Headers:

Header	Description
X-API-Key	Your Tuner API key
Content-Type	application/json

Query Parameters:

Parameter	Type	Description
workspace_id	number	Found in Workspace Settings > General Settings
agent_remote_identifier	string	Your Agent Remote ID from Agent Settings > Agent Connection

Required Body Fields:

Field	Type	Description
call_id	string	A unique identifier for the call from your system
call_type	string	The type of call interaction (e.g., "phone_call")
transcript_with_tool_calls	object[]	Array of messages with role and content fields
start_timestamp	integer	Epoch timestamp of when the call started
end_timestamp	integer	Epoch timestamp of when the call ended
recording_url	string	URL to the audio recording of the call

A successful request returns a 201 Created response confirming the call was received.

For the complete API reference with all available fields and a ready-to-use example, see Send Call Data.

View Your Call in the Dashboard

Navigate to Call Logs in the sidebar. Your test call should appear within a few seconds. Click on it to see the full monitoring results, including:

• Transcript with speaker labels
• Call duration and metadata
• Evaluation results (once configured)

---

Step 4: Customize Your Agent

Now that your integration is working, refine how Tuner monitors and analyzes calls. Open Agent Settings by clicking the gear icon next to your agent name.

What you do here lines up with Step 2:

• If you chose Configure via MCP — The Tuner MCP server can generate call outcomes, user intents, evaluations, guardrails, alerts, and related settings from your IDE or chat. In Agent Settings, review what was created, edit anything that should change, and add what is still missing. You can keep iterating with MCP or edit everything directly in the dashboard.
• If you chose Start from blank — You define the same pieces yourself in Agent Settings. Nothing is assumed; you have full control to build outcomes, intents, evaluations, and alerts from scratch.

Both paths use the same tabs and screens below—you are either polishing MCP-generated configuration or filling it in by hand.

Define Call Outcomes

Specify what “Success” and “Failure” mean for your agent. For example:

Outcome	Type	Description
Appointment Booked	Success	User successfully scheduled an appointment
User Hung Up	Failure	User ended the call before completing their goal
Transferred to Human	Neutral	Call was escalated to a human agent

Set Up User Intents

Define the possible reasons users might call your agent:

• Schedule Appointment
• Reschedule Appointment
• Cancel Appointment
• General Inquiry

Create Custom Evaluations

Add specific checks to evaluate agent behavior on every call. For example:

• “Did the agent confirm the appointment details?”
• “Did the agent offer alternative times if the requested slot was unavailable?”

Configure Alerts

Set up real-time notifications to get alerted when critical issues occur:

• Email alerts for failed calls
• Slack notifications for evaluation failures

For MCP-driven setup and updates, see Configure Your Agent Using Tuner MCP. For dashboard-only workflows, see Classifying Calls and Configuring Alerts.

---

🎉 Congratulations!

You’ve successfully integrated your voice AI with Tuner! Here’s what you’ve accomplished:

✅ Saved Retell or Vapi keys in Workspace Settings when using those providers

✅ Created your first agent

✅ Verified the integration with a test call or request

✅ Learned how to customize your agent — review MCP-generated config or edit settings you built from Start from blank

What’s Next?

Now that your integration is complete, explore these resources to get the most out of Tuner:

Connecting to Retell

Detailed guide for Retell integration.

Connecting to Vapi

Detailed guide for Vapi integration.

Connecting to LiveKit

SDK integration for LiveKit Agents.

Connecting to Pipecat

SDK integration for Pipecat Flows.

Custom Integration Guide

Deep dive into API integration options.

Classifying Calls

Set up call outcomes and user intents.

Best Practices

Tips for effective agent monitoring.