Build your first agent in 10 minutes

This guide takes you from an empty account to a live outbound voice agent. You create the agent, let the AI draft its script, place a test call to your own phone, upload contacts, and start the agent. Before you start, make sure you have:

An admin user on your Callers account at app.callers.ai.
At least one phone number in Phone numbers: a number managed by Callers, or one synced from Twilio, Telnyx, or a SIP connection. See Phone numbers and caller ID.
A short CSV of test contacts (a name and a phone number in international format, for example +14155550123).

Build the agent in the dashboard

Create an outbound voice agent

Go to Agents and click New Agent. The agent editor opens on the Script tab.

Agents page listing one agent named Demo Agent with its contact, interaction, connect rate, and success rate columns, a search field, and a New Agent button — The Agents page, with the New Agent button in the top-right corner.

Open General Settings from the toolbar and set:

Agent name: an internal name, for example “Demo booking – Q4”.
Agent type Voice, direction Outgoing.

General Settings panel with Agent name set to Demo Agent, Use case set to Cold Outreach, the Outgoing direction card selected, Voice chosen as the channel, and collapsed Agent Instructions and Technical Settings sections — General Settings: the agent name, use case, direction cards, and channel type.

Pick a use case and let AI draft the script

In General Settings, choose a Use case (optional) such as Cold Outreach, Lead Revival, or Event Confirmation. Choose Other to describe your own.Then open the AI Assistant panel in the editor, choose Create or edit scenario, and describe the call in a few sentences: who you are, who you are calling, the goal of the call, and the details the agent must collect. For example:

We’re Acme Solar. Call homeowners who requested a quote on our website, confirm they own the home, ask about their average monthly electricity bill, and book a 20-minute consultation.

The assistant drafts the script and shows you the proposed changes, which you can keep or revert. See Studio Chat.

Put company facts, product details, and answers to common questions in a knowledge base instead of the script. The script handles the flow; the knowledge base handles the facts.

Review the script, voice, and language

On the Script tab, read each block and step. Edit the wording so it sounds like your team, and use variables such as {{name}} for details that come from each contact. See Script editor and Variables.Open Agent from the toolbar to choose the Language and Voice. Click play to preview the voice with the sample text.

Set the phone number

Open Channels and, on Voice Channels, select the number (or numbers) the agent calls from. An agent can’t start until at least one phone number is selected.

Review the success criteria

Open the Workflow tab and select Success Criteria. This defines when a conversation counts as a success (“goal reached”), for example “The contact booked a consultation”. Click Generate to draft criteria from your script, then review and save them.Callers asks you to review and save success criteria, with at least one goal-reached criterion, before the agent can start. See Success criteria.

Run a test call

Click Test Call in the toolbar. On the Phone Call tab, enter your own name and phone number, fill in any variables the script uses, and click Start. Your phone rings and you talk to the agent.Prefer not to use a phone? Use the Web Call tab to talk to the agent in your browser.

Initiate a new test form with Phone Call and Web Call tabs, required fields for name, International Phone Number, companyName, agentName, and productName, toggles for Load contact memories, Use a different language, and Use a different time zone, and a Start button — The Initiate a new test form asks for your number and a value for each script variable.

After the call, open it to check the recording, transcript, and outcome. Adjust the script and test again until the conversation sounds right. See Testing your agent.

Test calls are excluded from the US Federal DNC registry check, so you can test with your own number even if it is registered.

Save and publish

Click Save. If your agent shows a Draft / Published label, click Publish to make the saved version live. Only published versions take real calls. See Versions and split traffic.

Add contacts from a CSV

Close the editor to go to the agent page and click Add Contact. On Import File, upload your CSV, map its columns (name, phone number, and any variables your script uses), review the preview, and import. The import runs in the background; you can follow it in Import History.Columns you map to variables fill {{variable}} placeholders in the script for each contact. See Uploading contacts.

Set availability

Open Availability in the editor and set when the agent may call:

The time zone, or Use Contact’s Time Zone to call each contact in their local time.
Weekly calling hours.
Retry rules such as Total Dial Attempts (default 5) and the minimum wait between attempts (default 90 minutes).
Max Outgoing Calls in Parallel (default 10).

See Scheduling and retries.

Start the agent

On the agent page, click Start. Callers dials eligible contacts within your calling hours and updates each contact’s status as calls complete. The agent stops on its own when no contacts are left to call.Watch results on the agent page: statuses, recordings, transcripts, and post-call analysis. See Agent results and insights.

Top of a running agent's page showing a Running badge, Edit, Test, and Add Contact buttons, a Total contacts bar of 213 contacts broken down by status, and a panel with 382 total interactions, 100% connect rate, and 38.97% success rate — The agent page while running: the contact status bar, Connect Rate, and Success Rate.

Your agent is live. Each finished call produces a contact status, a success-criteria result, and a summary you can send to your systems with a webhook.

Or do it via API

Once the agent exists in the dashboard, you can add contacts and start it from your own systems. Find the agent ID in the agent’s URL, and create an API key in Settings → API Keys (see API keys).

Add a contact
Start the agent

POST /agents/{agentId}/contacts adds one contact. name and data are required; data holds your script variables as string values.

curl -X POST "https://api.callers.ai/agents/$AGENT_ID/contacts" \
  -H "Authorization: $CALLERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dana Levi",
    "phoneNumber": "+14155550123",
    "data": {
      "company": "Acme Solar",
      "plan": "Premium"
    }
  }'

const res = await fetch(
  `https://api.callers.ai/agents/${process.env.AGENT_ID}/contacts`,
  {
    method: "POST",
    headers: {
      Authorization: process.env.CALLERS_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Dana Levi",
      phoneNumber: "+14155550123",
      data: { company: "Acme Solar", plan: "Premium" },
    }),
  }
);
console.log(await res.json());

import os
import requests

res = requests.post(
    f"https://api.callers.ai/agents/{os.environ['AGENT_ID']}/contacts",
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
    json={
        "name": "Dana Levi",
        "phoneNumber": "+14155550123",
        "data": {"company": "Acme Solar", "plan": "Premium"},
    },
)
print(res.json())

A successful response returns the contact ID and whether the contact was created or updated:

{
  "status": "success",
  "data": { "contactId": "665f1c2e8b3f4a0012ab34cd", "created": true, "modified": false }
}

To add many contacts in one request, use POST /agents/{agentId}/contacts/bulk. Add ?fixUSPhoneNumber=true to prepend 1 to US numbers that are missing it.

POST /agents/{agentId}/start activates the agent. It then calls eligible contacts within its availability.

curl -X POST "https://api.callers.ai/agents/$AGENT_ID/start" \
  -H "Authorization: $CALLERS_API_KEY"

const res = await fetch(
  `https://api.callers.ai/agents/${process.env.AGENT_ID}/start`,
  { method: "POST", headers: { Authorization: process.env.CALLERS_API_KEY } }
);
console.log(await res.json());

import os
import requests

res = requests.post(
    f"https://api.callers.ai/agents/{os.environ['AGENT_ID']}/start",
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
)
print(res.json())

Use POST /agents/{agentId}/stop to stop it.

The API key goes in the Authorization header as-is, without a Bearer prefix. The API also accepts the legacy /campaigns/... paths, which you may see in older integrations.

For a complete API walkthrough, including webhooks, see the API quickstart.

Next steps

Handle questions and objections

Add scenarios for pricing questions, “I’m busy”, and other off-script moments.

Connect your systems

Look up data during the call, book meetings, and update your CRM after it.

Collect structured answers

Define key questions and get the answers in every call summary.

Send results to your systems

Receive call outcomes, transcripts, and recordings as webhooks.

Create an agent

Every option when creating voice, text, and email agents.

Path to production

The go-live checklist for your first real launch.

Get started

Build your agent

Test and deploy

Voice

Channels

Contacts and outreach

Results and analytics

Human operators

Best practices

Account and administration

Enterprise

Resources

Build your first agent in 10 minutes

Build the agent in the dashboard

Or do it via API

Next steps

Handle questions and objections

Connect your systems

Collect structured answers

Send results to your systems

Create an agent

Path to production

​Build the agent in the dashboard

​Or do it via API

​Next steps

Handle questions and objections

Connect your systems

Collect structured answers

Send results to your systems

Create an agent

Path to production

Build the agent in the dashboard

Or do it via API

Next steps