Quickstart

This guide will walk you through creating a simple Voice Agent and making your first test call.

Prerequisites

A Butter AI account.
Your API Key and Organization ID from the Dashboard.

Step 1: Create an Agent

We’ll create a simple receptionist agent. You can do this via the Dashboard or the API. Here is the API method:

curl -X POST "https://api.getbutter.ai/api/agents" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Sarah - Receptionist",
    "language": "en",
    "stt_provider": "deepgram",
    "tts_provider": "cartesia",
    "tts_voice": "f786b574-daa5-4673-aa0c-cbe3e8534c02",
    "llm_provider": "openai",
    "llm_model": "gpt-4o-mini",
    "system_prompt": "You are Sarah, a helpful receptionist for Acme Corp. You can answer questions about business hours (9-5 EST) and location (New York). Keep answers brief.",
    "speak_first": true
  }'

Save the id from the response (e.g., agent_a1b2c3d4e5f6).

Step 2: Create a Twilio Integration

Before importing a Twilio number, you must connect your Twilio account to Butter AI.

curl -X POST "https://api.getbutter.ai/api/integrations" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Twilio Account",
    "credentials": {
      "provider": "twilio",
      "account_sid": "<YOUR_TWILIO_SID>",
      "auth_token": "<YOUR_TWILIO_TOKEN>"
    }
  }'

Save the integration_id from the response (e.g., intg_a1b2c3d4e5f6).

Step 3: Import a Phone Number

To make or receive calls, you need a phone number. We’ll use the integration we just created.

curl -X POST "https://api.getbutter.ai/api/phone-numbers" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "provider": "twilio",
    "integration_id": "intg_a1b2c3d4e5f6",
    "supports_inbound": true,
    "supports_outbound": true
  }'

Save the id from the response (e.g., phon_a1b2c3d4e5f6).

Step 4: Assign Number to Agent

Link the number to your agent so it handles inbound calls.

curl -X POST "https://api.getbutter.ai/api/agents/agent_a1b2c3d4e5f6/assign-phone-number" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "phon_b2c3d4e5f6a7"
  }'

Step 5: Make a Call

Now, call the number you imported! Or, trigger an outbound call via API:

curl -X POST "https://api.getbutter.ai/api/make-call" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "call_to": "<YOUR_PERSONAL_PHONE_NUMBER>",
    "call_from": "+15551234567",
    "agent_id": "agent_a1b2c3d4e5f6"
  }'

You should receive a call from your agent “Sarah”.

Next Steps

Add Knowledge: Upload documents so Sarah knows more about your company.
Add Tools: Let Sarah schedule appointments or look up orders.

Getting Started

Core Concepts

Telephony

Cookbook

Best Practices

Resources

Advanced

Prerequisites

Step 1: Create an Agent

Step 2: Create a Twilio Integration

Step 3: Import a Phone Number

Step 4: Assign Number to Agent

Step 5: Make a Call

Next Steps

​Prerequisites

​Step 1: Create an Agent

​Step 2: Create a Twilio Integration

​Step 3: Import a Phone Number

​Step 4: Assign Number to Agent

​Step 5: Make a Call

​Next Steps

Prerequisites

Step 1: Create an Agent

Step 2: Create a Twilio Integration

Step 3: Import a Phone Number

Step 4: Assign Number to Agent

Step 5: Make a Call

Next Steps