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 "Authorization: Bearer <YOUR_API_KEY>" \
  -H "X-Organization-Id: <YOUR_ORG_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "agent_name": "Sarah - Receptionist",
      "stt_provider": "deepgram-nova-3",
      "tts_provider": "cartesia",
      "tts_voice": "f786b574-daa5-4673-aa0c-cbe3e8534c02",
      "llm_provider": "google",
      "llm_model": "gemini-2.5-flash-lite",
      "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 agent_id from the response (e.g., agent_123).

​
Step 2: Import a Phone Number

To make or receive calls, you need a phone number. We’ll use a Twilio number for this example. 
curl -X POST "https://api.getbutter.ai/api/phone-numbers" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "X-Organization-Id: <YOUR_ORG_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "provider": "twilio",
    "sid": "<YOUR_TWILIO_SID>",
    "token": "<YOUR_TWILIO_TOKEN>",
    "supports_inbound": true,
    "supports_outbound": true
  }'
Save the phone_number_id.

​
Step 3: 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_123/assign-phone-number?phone_number_id=<PHONE_NUMBER_ID>" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "X-Organization-Id: <YOUR_ORG_ID>"

​
Step 4: 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 "Authorization: Bearer <YOUR_API_KEY>" \
  -H "X-Organization-Id: <YOUR_ORG_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "call_to": "<YOUR_PERSONAL_PHONE_NUMBER>",
    "call_from": "+15551234567",
    "agent_id": "agent_123"
  }'
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.