Skip to main content
This guide walks you through creating a basic agent that can answer calls. By the end, you’ll have a working agent attached to a phone number.
Need API access? Email devs@helloannie.com to get started.

​
Prerequisites

  • An Annie account with API access
  • Your API key
Not sure how to authenticate? See the Authentication guide.

​
Step 1: Create an Organization

An organization represents a physical location—your practice, clinic, or office. It stores the details your agent needs to answer questions accurately. 
const response = await fetch("https://api.helloannie.com/v1/organizations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "Downtown Dental",
    phone: "+15551234567",
    timezone: "America/New_York"
  })
})

const { data } = await response.json()
// data.id contains the organization ID for the next steps

import requests

response = requests.post(
    "https://api.helloannie.com/v1/organizations",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "name": "Downtown Dental",
        "phone": "+15551234567",
        "timezone": "America/New_York"
    }
)

data = response.json()["data"]
# data["id"] contains the organization ID for the next steps

curl -X POST https://api.helloannie.com/v1/organizations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Downtown Dental",
    "phone": "+15551234567",
    "timezone": "America/New_York"
  }'
Save the id from the response—you’ll need it in the next steps.

Organizations Guide

Learn about addresses, office hours, staff, and multi-location setups.

​
Step 2: Create a Bot

A bot is your AI agent. It handles conversations and can be trained with custom knowledge specific to your organization. 
const response = await fetch("https://api.helloannie.com/v1/bots", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "Annie",
    orgId: "YOUR_ORG_ID",
    greeting: "Hi! Thanks for reaching out. How can I help you today?"
  })
})

const { data } = await response.json()
// data.id contains your new bot ID

import requests

response = requests.post(
    "https://api.helloannie.com/v1/bots",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "name": "Annie",
        "orgId": "YOUR_ORG_ID",
        "greeting": "Hi! Thanks for reaching out. How can I help you today?"
    }
)

data = response.json()["data"]
# data["id"] contains your new bot ID

curl -X POST https://api.helloannie.com/v1/bots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Annie",
    "orgId": "YOUR_ORG_ID",
    "greeting": "Hi! Thanks for reaching out. How can I help you today?"
  }'

Bots Guide

Configure bot settings, integrations, and parent-child relationships.

​
Step 3: Add Training

Annie supports multiple training modules to teach your agent how to respond—FAQs, insurances, office information, workflows, and more. For this quickstart, we’ll use a template, which bundles common training into a single configuration you can apply to your bot. Templates are pre-built for common use cases like dental scheduling agents or general FAQ agents.
Since the API is invite-only, part of your onboarding includes setting up your first template. We’ll add default templates to your account so you can get up and testing quickly—then tweak and fine-tune them later.
const response = await fetch(
  "https://api.helloannie.com/v1/templates/TEMPLATE_ID/apply",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      botId: "YOUR_BOT_ID",
      variables: {
        "office_name": "Downtown Dental",
        "office_phone": "+15551234567"
      }
    })
  }
)

import requests

response = requests.post(
    "https://api.helloannie.com/v1/templates/TEMPLATE_ID/apply",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "botId": "YOUR_BOT_ID",
        "variables": {
            "office_name": "Downtown Dental",
            "office_phone": "+15551234567"
        }
    }
)

curl -X POST https://api.helloannie.com/v1/templates/TEMPLATE_ID/apply \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "botId": "YOUR_BOT_ID",
    "variables": {
      "office_name": "Downtown Dental",
      "office_phone": "+15551234567"
    }
  }'
Templates may contain variables that must be filled in when applying. The variables field is required—pass an empty object {} if the template has no variables. Check your template’s variables array to see what values are needed.More documentation on template variables is coming soon.

Training Guide

Learn about all the training modules—FAQs, insurances, workflows, and more.

​
Step 4: Attach a Phone Number

Connect a phone number to your bot so it can receive calls. 
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"
    })
  }
)

import requests

response = requests.post(
    "https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/attach",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "botId": "YOUR_BOT_ID"
    }
)

curl -X POST https://api.helloannie.com/v1/phone-numbers/PHONE_NUMBER_ID/attach \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "botId": "YOUR_BOT_ID"
  }'

Phone Numbers Guide

Provision numbers, configure forwarding, and manage number routing.

​
Step 5: Test Your Agent

Call your phone number. Your agent should answer and respond based on the training you’ve provided.

​
What’s Next?

This quickstart covered the basics, but each step has many more customization options and features. Dive deeper with our guides:

Organizations

Addresses, office hours, staff, and multi-location configurations.

Bots

Integrations, parent-child relationships, and advanced settings.

Training

FAQs, insurances, workflows, and how training affects behavior.

Phone Numbers

Provisioning, forwarding, and routing configurations.

Bot Architecture

Architecture patterns for multi-location and enterprise deployments.

API Reference

Full documentation for all endpoints.