Create AI Assistant

POST

assistants

curl -X POST https://api.avoca.ai/v1/assistants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Receptionist",
    "type": "inbound",
    "voice": {
      "provider": "elevenlabs",
      "voiceId": "emily",
      "speed": 1.0
    },
    "language": "en-US",
    "model": {
      "provider": "openai",
      "model": "gpt-4",
      "temperature": 0.7,
      "systemPrompt": "You are a friendly and professional receptionist for ABC Plumbing, a family-owned plumbing company serving Los Angeles for over 30 years. You should be warm, helpful, and focused on scheduling appointments. Always be empathetic to customers plumbing emergencies."
    },
    "firstMessage": "Thank you for calling ABC Plumbing. This is Emily. How can I help you today?",
    "knowledge_base": {
      "services": [
        "Drain cleaning",
        "Water heater repair and installation",
        "Leak detection and repair",
        "Emergency plumbing",
        "Bathroom remodeling",
        "Sewer line repair"
      ],
      "service_area": ["Los Angeles", "Santa Monica", "Beverly Hills", "Culver City"],
      "business_hours": "Monday through Friday 8am to 6pm, Saturday 9am to 4pm. We offer 24/7 emergency service.",
      "pricing": {
        "service_call": "$89",
        "emergency_fee": "$150 additional for after-hours emergencies",
        "estimates": {
          "drain_cleaning": "$150-$300",
          "water_heater_install": "$1,500-$3,000"
        }
      },
      "faqs": [
        {
          "question": "Do you offer free estimates?",
          "answer": "Yes, we offer free estimates for all non-emergency work."
        },
        {
          "question": "Are you licensed and insured?",
          "answer": "Yes, we are fully licensed, bonded, and insured. Our license number is 123456."
        }
      ]
    },
    "transfer_rules": {
      "emergency": {
        "keywords": ["flooding", "burst pipe", "gas leak", "sewage backup"],
        "action": "transfer_to_oncall",
        "message": "This sounds like an emergency. Let me connect you with our on-call plumber right away."
      },
      "sales": {
        "keywords": ["water heater quote", "remodel", "new construction"],
        "action": "transfer_to_sales",
        "message": "I will connect you with our sales team who can provide a detailed quote."
      }
    },
    "tools": ["schedule_appointment", "check_availability", "create_ticket"],
    "booking_enabled": true,
    "servicetitan_integration": true,
    "webhook_url": "https://your-domain.com/webhooks/avoca",
    "advanced_settings": {
      "endCallPhrases": ["goodbye", "bye", "have a good day"],
      "interruptionThreshold": 0.6,
      "silenceTimeout": 10,
      "maxCallDuration": 900
    }
  }'

{
  "data": {
    "id": "asst_abc123",
    "created_at": "2024-01-15T10:00:00Z",
    "phone_number": "+13105551234",
    "status": "active",
    "vapi_assistant_id": "vapi_asst_xyz789",
    "webhook_secret": "whsec_1234567890abcdef"
  },
  "meta": {
    "request_id": "req_def456",
    "timestamp": "2024-01-15T10:00:00Z"
  }
}

This endpoint creates a fully configured AI assistant that can handle voice calls, with deep customization of voice, personality, knowledge base, and behavior. The assistant integrates with Vapi for voice processing.

Request

name

string

required

A descriptive name for your AI assistant (e.g., “Main Receptionist”, “After Hours Assistant”)

type

string

required

The type of assistant:

inbound - Handles incoming calls
outbound - Makes outgoing calls
both - Handles both inbound and outbound

voice

object

required

Voice configuration

Show properties

provider

string

required

Voice provider: elevenlabs, azure, aws

voiceId

string

required

Voice ID from the provider (e.g., “emily”, “michael”)

speed

number

Speaking speed (0.5 to 2.0, default: 1.0)

pitch

number

Voice pitch adjustment (-20 to 20, default: 0)

language

string

default:"en-US"

Language and locale:

en-US - English (United States)
en-GB - English (United Kingdom)
es-US - Spanish (United States)
es-MX - Spanish (Mexico)

model

object

required

AI model configuration

Show properties

provider

string

required

Model provider: openai, anthropic

model

string

required

Model name: gpt-4, gpt-3.5-turbo, claude-3

temperature

number

Response randomness (0.0 to 1.0, default: 0.7)

systemPrompt

string

required

The core instructions defining the assistant’s personality and behavior

firstMessage

string

required

The initial greeting when answering calls

knowledge_base

object

required

Business information the assistant can reference

Show properties

services

array

required

List of services your business offers

service_area

array

required

Geographic areas you serve

business_hours

string

required

Your business hours in natural language

pricing

object

Pricing information

Show properties

service_call

string

Base service call fee

emergency_fee

string

Emergency service fee

estimates

object

Common service price ranges

faqs

array

Common questions and answers

Show properties

question

string

The question

answer

string

The answer

transfer_rules

object

Rules for when to transfer calls to humans

Show properties

emergency

object

Emergency transfer configuration

Show properties

keywords

array

Keywords that trigger emergency transfer

action

string

Action to take: transfer_to_oncall, transfer_to_queue

message

string

What to say before transferring

sales

object

Sales transfer rules

custom

array

Custom transfer rules

tools

array

Tools/functions the assistant can use:

schedule_appointment - Book appointments
check_availability - Check schedule availability
create_ticket - Create service tickets
lookup_customer - Search customer records
send_sms - Send text messages
send_email - Send emails

booking_enabled

boolean

default:"true"

Whether the assistant can schedule appointments

servicetitan_integration

boolean

default:"false"

Enable ServiceTitan integration for this assistant

webhook_url

string

URL to receive call events and transcripts

advanced_settings

object

Advanced configuration options

Show properties

endCallPhrases

array

Phrases that should end the call

interruptionThreshold

number

How easily the assistant can be interrupted (0-1)

silenceTimeout

number

Seconds of silence before ending call

maxCallDuration

number

Maximum call duration in seconds

Response

string

Unique identifier for the assistant

created_at

string

ISO 8601 timestamp of creation

phone_number

string

Phone number assigned to this assistant

status

string

Assistant status:

active - Ready to handle calls
provisioning - Being set up
paused - Temporarily disabled
error - Configuration error

vapi_assistant_id

string

The Vapi platform assistant ID for direct integration

webhook_secret

string

Secret for verifying webhook signatures

curl -X POST https://api.avoca.ai/v1/assistants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Receptionist",
    "type": "inbound",
    "voice": {
      "provider": "elevenlabs",
      "voiceId": "emily",
      "speed": 1.0
    },
    "language": "en-US",
    "model": {
      "provider": "openai",
      "model": "gpt-4",
      "temperature": 0.7,
      "systemPrompt": "You are a friendly and professional receptionist for ABC Plumbing, a family-owned plumbing company serving Los Angeles for over 30 years. You should be warm, helpful, and focused on scheduling appointments. Always be empathetic to customers plumbing emergencies."
    },
    "firstMessage": "Thank you for calling ABC Plumbing. This is Emily. How can I help you today?",
    "knowledge_base": {
      "services": [
        "Drain cleaning",
        "Water heater repair and installation",
        "Leak detection and repair",
        "Emergency plumbing",
        "Bathroom remodeling",
        "Sewer line repair"
      ],
      "service_area": ["Los Angeles", "Santa Monica", "Beverly Hills", "Culver City"],
      "business_hours": "Monday through Friday 8am to 6pm, Saturday 9am to 4pm. We offer 24/7 emergency service.",
      "pricing": {
        "service_call": "$89",
        "emergency_fee": "$150 additional for after-hours emergencies",
        "estimates": {
          "drain_cleaning": "$150-$300",
          "water_heater_install": "$1,500-$3,000"
        }
      },
      "faqs": [
        {
          "question": "Do you offer free estimates?",
          "answer": "Yes, we offer free estimates for all non-emergency work."
        },
        {
          "question": "Are you licensed and insured?",
          "answer": "Yes, we are fully licensed, bonded, and insured. Our license number is 123456."
        }
      ]
    },
    "transfer_rules": {
      "emergency": {
        "keywords": ["flooding", "burst pipe", "gas leak", "sewage backup"],
        "action": "transfer_to_oncall",
        "message": "This sounds like an emergency. Let me connect you with our on-call plumber right away."
      },
      "sales": {
        "keywords": ["water heater quote", "remodel", "new construction"],
        "action": "transfer_to_sales",
        "message": "I will connect you with our sales team who can provide a detailed quote."
      }
    },
    "tools": ["schedule_appointment", "check_availability", "create_ticket"],
    "booking_enabled": true,
    "servicetitan_integration": true,
    "webhook_url": "https://your-domain.com/webhooks/avoca",
    "advanced_settings": {
      "endCallPhrases": ["goodbye", "bye", "have a good day"],
      "interruptionThreshold": 0.6,
      "silenceTimeout": 10,
      "maxCallDuration": 900
    }
  }'

{
  "data": {
    "id": "asst_abc123",
    "created_at": "2024-01-15T10:00:00Z",
    "phone_number": "+13105551234",
    "status": "active",
    "vapi_assistant_id": "vapi_asst_xyz789",
    "webhook_secret": "whsec_1234567890abcdef"
  },
  "meta": {
    "request_id": "req_def456",
    "timestamp": "2024-01-15T10:00:00Z"
  }
}

Update AssistantModify an existing assistant configuration

⌘I

curl -X POST https://api.avoca.ai/v1/assistants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Receptionist",
    "type": "inbound",
    "voice": {
      "provider": "elevenlabs",
      "voiceId": "emily",
      "speed": 1.0
    },
    "language": "en-US",
    "model": {
      "provider": "openai",
      "model": "gpt-4",
      "temperature": 0.7,
      "systemPrompt": "You are a friendly and professional receptionist for ABC Plumbing, a family-owned plumbing company serving Los Angeles for over 30 years. You should be warm, helpful, and focused on scheduling appointments. Always be empathetic to customers plumbing emergencies."
    },
    "firstMessage": "Thank you for calling ABC Plumbing. This is Emily. How can I help you today?",
    "knowledge_base": {
      "services": [
        "Drain cleaning",
        "Water heater repair and installation",
        "Leak detection and repair",
        "Emergency plumbing",
        "Bathroom remodeling",
        "Sewer line repair"
      ],
      "service_area": ["Los Angeles", "Santa Monica", "Beverly Hills", "Culver City"],
      "business_hours": "Monday through Friday 8am to 6pm, Saturday 9am to 4pm. We offer 24/7 emergency service.",
      "pricing": {
        "service_call": "$89",
        "emergency_fee": "$150 additional for after-hours emergencies",
        "estimates": {
          "drain_cleaning": "$150-$300",
          "water_heater_install": "$1,500-$3,000"
        }
      },
      "faqs": [
        {
          "question": "Do you offer free estimates?",
          "answer": "Yes, we offer free estimates for all non-emergency work."
        },
        {
          "question": "Are you licensed and insured?",
          "answer": "Yes, we are fully licensed, bonded, and insured. Our license number is 123456."
        }
      ]
    },
    "transfer_rules": {
      "emergency": {
        "keywords": ["flooding", "burst pipe", "gas leak", "sewage backup"],
        "action": "transfer_to_oncall",
        "message": "This sounds like an emergency. Let me connect you with our on-call plumber right away."
      },
      "sales": {
        "keywords": ["water heater quote", "remodel", "new construction"],
        "action": "transfer_to_sales",
        "message": "I will connect you with our sales team who can provide a detailed quote."
      }
    },
    "tools": ["schedule_appointment", "check_availability", "create_ticket"],
    "booking_enabled": true,
    "servicetitan_integration": true,
    "webhook_url": "https://your-domain.com/webhooks/avoca",
    "advanced_settings": {
      "endCallPhrases": ["goodbye", "bye", "have a good day"],
      "interruptionThreshold": 0.6,
      "silenceTimeout": 10,
      "maxCallDuration": 900
    }
  }'

{
  "data": {
    "id": "asst_abc123",
    "created_at": "2024-01-15T10:00:00Z",
    "phone_number": "+13105551234",
    "status": "active",
    "vapi_assistant_id": "vapi_asst_xyz789",
    "webhook_secret": "whsec_1234567890abcdef"
  },
  "meta": {
    "request_id": "req_def456",
    "timestamp": "2024-01-15T10:00:00Z"
  }
}

​Request

​Response

Request

Response