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

​
Prerequisites

  1. A Butter AI account.
  2. 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.