Setting Up a Phone Number

Phone numbers connect callers to your AI agent. When someone calls the number, Annie answers and handles the conversation based on the attached bot’s training. This guide walks through every step of setting up a phone number — from choosing the right area code to attaching it to your bot.

Prerequisites

Before provisioning a phone number, make sure you have:

An organization created with a complete address and timezone
A bot configured with greetings and training
An API key with write permissions (see Authentication)

Step 1: Choose the Right Area Code

When you provision a phone number, Annie purchases a real US phone number for your organization. You can specify a 3-digit US area code to control where the number appears to be from.

Choose an area code that matches your organization’s location. Patients are more likely to answer calls and trust numbers with a local area code. For example, a dental office in Chicago should use a 312 or 773 area code.

How area code selection works:

If you provide a valid areaCode, Annie provisions a number from that area code
If you omit areaCode, a default area code is used — we recommend always specifying one
The area code must be a valid US area code (3 digits)

To find the right area code, look up the area code for your organization’s city or region. If your practice has multiple locations, use a local area code for each.

In rare cases, a specific area code may not have numbers available. If provisioning fails, try a nearby area code in the same region.

Step 2: Provision the Phone Number

Create a new phone number by making a POST request to the phone numbers endpoint. You’ll need to specify the organization, a friendly name, the language, voice, and area code.

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",
    areaCode: "312"
  })
})

const { data } = await response.json()
console.log(data.number) // e.g. "+13125551234"
console.log(data.id)     // Use this ID for future operations

Required Fields

orgId

string

required

The organization ID that will own this phone number. The phone number inherits the organization’s context (address, hours, timezone) for handling calls.

name

string

required

A friendly name to identify this phone number. Use descriptive names that reflect the number’s purpose.Examples: "Main Line", "After Hours", "Spanish Line", "Recall Outreach"

language

string

required

The language Annie uses when answering calls on this number. This controls both the voice model and the language of the conversation.

Value	Description
`ENGLISH`	English (US)
`SPANISH`	Spanish
`FRENCH`	French

See Configuring Language for details on setting up language for your phone numbers.

voiceId

string

required

The voice Annie uses when speaking to callers. Each voice has a distinct personality and tone.

Voice ID	Description
`FRIENDLY_BRIGHT`	Warm, welcoming, and easy to understand
`CALM_REASSURING`	Subtle, gentle voice that builds trust
`POLISHED_PROFESSIONAL`	Crisp, formal, business-ready clarity
`KIND_CURIOUS`	Thoughtful and asks with care
`CONFIDENT_UPBEAT`	Energetic, decisive, and positive

FRIENDLY_BRIGHT is the most popular choice for dental and healthcare practices.

Optional Fields

botId

string

The bot ID to attach the phone number to immediately. If omitted, the phone number is created in a detached state and must be attached to a bot before it can handle calls. See Step 3 for details.

areaCode

string

A 3-digit US area code for the phone number (e.g., "312" for Chicago, "212" for New York). If omitted, a default area code is assigned.We strongly recommend providing an area code that matches your organization’s location for caller trust and recognition.

verifiedCallerId

string

A verified caller ID for outbound calls, in +1XXXXXXXXXX format. Must be pre-registered and verified for the organization. See Verified Caller IDs for setup.

callbackForwardingNumber

string

If a recipient calls back an outbound number, the call will be forwarded to this phone number. This field only applies to outbound numbers and is ignored for inbound numbers.

Step 3: Attach to a Bot

If you provided a botId during provisioning, the phone number is already attached and ready to receive calls. If not, attach it now:

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"
    })
  }
)

const { data } = await response.json()
// data.botId now contains the attached bot ID

The bot must belong to the same organization as the phone number. You cannot attach a phone number owned by one organization to a bot in a different organization.

Choosing the Right Bot

Which bot you attach determines how Annie handles calls on this number. Consider your use case:

Use Case	Bot Setup
General receptionist	A bot trained with comprehensive workflows, FAQs, and scheduling capabilities
After-hours line	A bot with a `closedPhoneGreeting` and training focused on message-taking and basic scheduling
Spanish line	A bot with Spanish-language training, paired with a phone number set to `language: "SPANISH"`
Outbound campaigns	A bot with `outbound: true` and campaign-specific workflows (e.g., appointment reminders, recall)
Scheduling only	A bot trained exclusively on appointment scheduling workflows

If you’re managing multiple locations, create a separate bot for each location so that each has location-specific training and greetings. Attach each location’s phone number to its corresponding bot.

Detaching a Phone Number

To switch a phone number to a different bot, first detach it:

// Detach from current bot
await fetch(
  "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/detach",
  {
    method: "POST",
    headers: { "Authorization": "Bearer YOUR_API_KEY" }
  }
)

// Attach to new bot
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: "NEW_BOT_ID" })
  }
)

Step 4: Verify Your Setup

After provisioning and attaching, confirm everything is configured correctly by retrieving your phone number:

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

const { data } = await response.json()

// Verify these fields are set correctly:
console.log("Number:", data.number)       // The provisioned phone number
console.log("Bot:", data.botId)           // Should be your bot's ID
console.log("Org:", data.orgId)           // Should be your org's ID
console.log("Language:", data.language)   // ENGLISH, SPANISH, or FRENCH
console.log("Voice:", data.voiceId)       // Your selected voice

Checklist — make sure:

botId is not null (the number is attached to a bot)
language matches the language your bot is trained in
orgId matches the organization for this location
voiceId is the voice you want callers to hear

Updating Phone Number Configuration

After provisioning, you can update the language, voice, or caller ID settings:

const response = await fetch(
  "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID",
  {
    method: "PATCH",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      language: "SPANISH",
      voiceId: "CALM_REASSURING"
    })
  }
)

To change which bot a phone number is attached to, use the attach and detach endpoints instead of PATCH. This is a deliberate design decision to prevent accidental changes.

Configuring Language

The language field on a phone number controls how Annie listens to and speaks with callers. When you set a language (ENGLISH, SPANISH, or FRENCH), Annie conducts the entire conversation in that language — including speech recognition, responses, and voice output.

Dedicated Language Lines

For practices that serve specific language communities, dedicate a phone number to each language:

// Create a Spanish-language line
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_SPANISH_BOT_ID",
    name: "Spanish Line",
    language: "SPANISH",
    voiceId: "FRIENDLY_BRIGHT",
    areaCode: "305"
  })
})

Make sure the bot attached to a non-English phone number has training in that language. For example, a Spanish line should be attached to a bot with Spanish-language FAQs, workflows, and greetings.

Changing a Phone Number’s Language

You can update the language of an existing phone number at any time using the PATCH endpoint:

const response = await fetch(
  "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID",
  {
    method: "PATCH",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      language: "SPANISH"
    })
  }
)

Listing Phone Numbers

Retrieve all phone numbers for your organization:

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

You can filter by organization using the orgId query parameter:

curl "https://api.helloannie.com/v1/phone-numbers?orgId=YOUR_ORG_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

Each organization can have up to 10 phone numbers. You can use multiple numbers for different purposes:

Main line → General bot with full training
Scheduling line → Bot focused on appointment scheduling
After-hours line → Bot with after-hours messaging
Spanish line → Bot trained in Spanish, with a number set to language: "SPANISH"
Outbound line → Bot configured for outbound campaigns

You can also attach multiple numbers to the same bot — useful for tracking different marketing campaigns or serving the same bot from different area codes.

Deleting a Phone Number

To delete a phone number, it must first be detached from any bot:

// First detach if attached
await fetch(
  "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/detach",
  {
    method: "POST",
    headers: { "Authorization": "Bearer YOUR_API_KEY" }
  }
)

// Then delete
await fetch(
  "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID",
  {
    method: "DELETE",
    headers: { "Authorization": "Bearer YOUR_API_KEY" }
  }
)

Deleting a phone number is irreversible. The number will be permanently released and cannot be recovered. Make sure you no longer need the number before deleting it.

Migrating a Phone Number

To move a phone number to a different organization (e.g., when restructuring locations), use the migrate endpoint:

const response = await fetch(
  "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/migrate",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      targetOrgId: "NEW_ORG_ID"
    })
  }
)

Migrating a phone number clears its bot attachment, since the bot belongs to the original organization. After migration, attach the number to a bot in the new organization.

What’s Next

Inbound Calls

Start receiving calls once your phone number is attached

Outbound Calls

Use your phone number to place outbound calls to patients

Bot Configuration

Configure your bot’s greetings, industry, and training

Phone Numbers API

See the full API reference for all phone number endpoints

Get Started

Guides

Setting Up a Phone Number

Prerequisites

Step 1: Choose the Right Area Code

Step 2: Provision the Phone Number

Required Fields

Optional Fields

Step 3: Attach to a Bot

Choosing the Right Bot

Detaching a Phone Number

Step 4: Verify Your Setup

Updating Phone Number Configuration

Configuring Language

Dedicated Language Lines

Changing a Phone Number’s Language

Listing Phone Numbers

Call Forwarding

Multiple Numbers

Deleting a Phone Number

Migrating a Phone Number

What’s Next

Inbound Calls

Outbound Calls

Bot Configuration

Phone Numbers API

Get Started

Guides

Documentation Index

​Prerequisites

​Step 1: Choose the Right Area Code

​Step 2: Provision the Phone Number

​Required Fields

​Optional Fields

​Step 3: Attach to a Bot

​Choosing the Right Bot

​Detaching a Phone Number

​Step 4: Verify Your Setup

​Updating Phone Number Configuration

​Configuring Language

​Dedicated Language Lines

​Changing a Phone Number’s Language

​Listing Phone Numbers

​Call Forwarding

​Multiple Numbers

​Deleting a Phone Number

​Migrating a Phone Number

​What’s Next

Inbound Calls

Outbound Calls

Bot Configuration

Phone Numbers API

Prerequisites

Step 1: Choose the Right Area Code

Step 2: Provision the Phone Number

Required Fields

Optional Fields

Step 3: Attach to a Bot

Choosing the Right Bot

Detaching a Phone Number

Step 4: Verify Your Setup

Updating Phone Number Configuration

Configuring Language

Dedicated Language Lines

Changing a Phone Number’s Language

Listing Phone Numbers

Call Forwarding

Multiple Numbers

Deleting a Phone Number

Migrating a Phone Number

What’s Next