Skip to main content
Phone numbers connect callers to your AI agents. When someone calls the number, Annie answers and handles the conversation based on the attached bot’s training.

​
How Phone Numbers Work

  1. Provision a phone number through the Annie platform
  2. Attach it to a bot
  3. Forward calls from your existing number, or use the Annie number directly

​
Provisioning a Phone Number

Create a new phone number for your organization: 
const response = await fetch("https://api.helloannie.com/v1/phone-numbers", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    orgId: "YOUR_ORG_ID",
    botId: "YOUR_BOT_ID",
    name: "Main Line",
    language: "ENGLISH",
    voiceId: "FRIENDLY_BRIGHT"
  })
})

const { data } = await response.json()
// data contains the new phone number

​
Phone Number Fields

​
orgId
string
required
The organization ID that will own this phone number.
​
botId
string
required
The bot ID to attach the phone number to.
​
name
string
required
Friendly name for the phone number (e.g., “Main Line”, “After Hours”).
​
language
string
required
The language for the phone number.Options: ENGLISH, SPANISH, FRENCH
​
voiceId
string
required
The voice Annie uses when answering calls on this number.Options: FRIENDLY_BRIGHT, CALM_REASSURING, POLISHED_PROFESSIONAL, KIND_CURIOUS, CONFIDENT_UPBEAT

​
Listing Phone Numbers

const response = await fetch("https://api.helloannie.com/v1/phone-numbers", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
})

const { data } = await response.json()
// data.phoneNumbers contains an array of phone numbers

​
Attaching a Number to a Bot

Once you have a phone number, attach it to your bot: 
const response = await fetch(
  "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/attach",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      botId: "YOUR_BOT_ID"
    })
  }
)

​
Call Forwarding

You can forward calls from your existing business number to your Annie number. This lets you keep your current phone number while having Annie answer. Common setups:
  • Forward all calls — Annie answers everything
  • Forward after hours — Your staff answers during business hours, Annie handles after-hours
  • Forward on busy/no answer — Annie picks up overflow calls
Configure forwarding through your phone provider (most VoIP and traditional phone systems support this).

​
Multiple Numbers

You can attach different phone numbers to different bots:
  • Main line → General bot with full training
  • Scheduling line → Bot focused on appointment scheduling
  • After-hours line → Bot with after-hours messaging
Or attach multiple numbers to the same bot for tracking different marketing campaigns.

Phone Numbers API

See the full API reference for phone number endpoints.