> ## Documentation Index
> Fetch the complete documentation index at: https://docs.callers.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Build your first agent in 10 minutes

> Create an outbound voice agent, generate its script with AI, test it on your own phone, add contacts, and start calling.

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](https://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](https://docs.callers.ai/documentation/contacts/phone-numbers-and-caller-id.md).
* A short CSV of test contacts (a name and a phone number in international format, for example `+14155550123`).

## Build the agent in the dashboard

**1. 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](https://mintcdn.com/voxiaai/_YXKfF6QWkI2BTUf/images/documentation/build-your-agent/agents-list.png?fit=max\&auto=format\&n=_YXKfF6QWkI2BTUf\&q=85\&s=cc7a5374141e0f892d8a34e29c9686e6)

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](https://mintcdn.com/voxiaai/_YXKfF6QWkI2BTUf/images/documentation/build-your-agent/general-settings.png?fit=max\&auto=format\&n=_YXKfF6QWkI2BTUf\&q=85\&s=a67909170067446bfbb177bc6ba4d735)

General Settings: the agent name, use case, direction cards, and channel type.

**2. 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](https://docs.callers.ai/documentation/build-your-agent/studio-chat.md).

> [!TIP]
>
> Put company facts, product details, and answers to common questions in a [knowledge base](https://docs.callers.ai/documentation/using-callers/knowledge-base.md) instead of the script. The script handles the flow; the knowledge base handles the facts.

**3. 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](https://docs.callers.ai/documentation/build-your-agent/agent-script.md) and [Variables](https://docs.callers.ai/documentation/build-your-agent/agent-variables.md).

Open **Agent** from the toolbar to choose the **Language** and **Voice**. Click play to preview the voice with the sample text.

**4. 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.

**5. 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](https://docs.callers.ai/documentation/results/success-criteria.md).

**6. 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](https://mintcdn.com/voxiaai/DUXJUr2YtBjwx26G/images/documentation/build-your-agent/initiate-new-test.png?fit=max\&auto=format\&n=DUXJUr2YtBjwx26G\&q=85\&s=a1e0dba56b3ed2f94e974bebcd62bd3d)

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](https://docs.callers.ai/documentation/build-your-agent/testing-your-agent.md).

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

**7. 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](https://docs.callers.ai/documentation/build-your-agent/versions-and-split-traffic.md).

**8. 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](https://docs.callers.ai/documentation/using-callers/uploading-contacts.md).

**9. 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](https://docs.callers.ai/documentation/contacts/scheduling-and-retries.md).

**10. 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](https://docs.callers.ai/documentation/using-callers/agent-insights.md).

![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](https://mintcdn.com/voxiaai/wqnSuR-gwKpmU86L/images/documentation/using-callers/agent-results-status-bar.png?fit=max\&auto=format\&n=wqnSuR-gwKpmU86L\&q=85\&s=0e1f97100e50a9e6ed89310d3c961c5b)

The agent page while running: the contact status bar, Connect Rate, and Success Rate.

> [!TIP]
>
> 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](https://docs.callers.ai/documentation/webhook/webhook-overview.md).

## 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](https://docs.callers.ai/documentation/using-callers/generate-api-key.md)).

**Add a contact**

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

```bash cURL theme={"dark"}
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"
    }
  }'
```

```javascript Node.js theme={"dark"}
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());
```

```python Python theme={"dark"}
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:

```json theme={"dark"}
{
  "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.

**Start the agent**

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

```bash cURL theme={"dark"}
curl -X POST "https://api.callers.ai/agents/$AGENT_ID/start" \
  -H "Authorization: $CALLERS_API_KEY"
```

```javascript Node.js theme={"dark"}
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());
```

```python Python theme={"dark"}
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.

> [!NOTE]
>
> 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](https://docs.callers.ai/api-reference/quickstart.md).

## Next steps

> **[Handle questions and objections](https://docs.callers.ai/documentation/build-your-agent/agent-scenarios.md)**
>
> Add scenarios for pricing questions, "I'm busy", and other off-script moments.

> **[Connect your systems](https://docs.callers.ai/documentation/build-your-agent/agent-actions.md)**
>
> Look up data during the call, book meetings, and update your CRM after it.

> **[Collect structured answers](https://docs.callers.ai/documentation/using-callers/key-questions.md)**
>
> Define key questions and get the answers in every call summary.

> **[Send results to your systems](https://docs.callers.ai/documentation/webhook/webhook-overview.md)**
>
> Receive call outcomes, transcripts, and recordings as webhooks.

> **[Create an agent](https://docs.callers.ai/documentation/build-your-agent/starting-a-new-agent.md)**
>
> Every option when creating voice, text, and email agents.

> **[Path to production](https://docs.callers.ai/documentation/best-practices/path-to-production.md)**
>
> The go-live checklist for your first real launch.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.