Skip to main content
POST
/
phone-numbers
/
inbound
/
setup
Setup Inbound Agent
curl --request POST \
  --url https://api.callhq.ai/api/phone-numbers/inbound/setup \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "assistantId": "<string>",
  "phoneNumberId": "<string>"
}
'
Configure a phone number to route inbound calls to a specific voice AI assistant.

​
Overview

This endpoint links an assistant to a phone number so that incoming calls to that number are handled by the specified agent. Use this after you have provisioned a phone number and created an assistant.

​
Request

​
Headers

HeaderValueRequired
x-api-keyYour API keyYes
Content-Typeapplication/jsonYes
accept*/*No

​
Request Body

FieldTypeRequiredDescription
assistantIdStringYesID of the assistant to handle inbound calls
phoneNumberIdStringYesID of the phone number to configure for inbound routing

​
Example Request

curl -X 'POST' \
  'https://api.callhq.ai/api/phone-numbers/inbound/setup' \
  -H 'accept: */*' \
  -H 'x-api-key: your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
  "assistantId": "your_assistant_id",
  "phoneNumberId": "your_phone_number_id"
}'

​
Response

​
Success Response (200)

Inbound agent configured successfully.

​
Error Responses

Status CodeDescription
400Missing required fields
404Assistant or phone number not found
500Failed to setup inbound agent

​
Use Cases

  • Inbound AI front desk: Route incoming calls to a support or reception assistant
  • After-hours handling: Direct callers to an AI agent outside business hours
  • Programmatic setup: Configure inbound routing as part of your onboarding or deployment workflow

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
assistantId
string
required

ID of the assistant to handle inbound calls

​
phoneNumberId
string
required

ID of the phone number to configure for inbound routing

Response

Inbound agent configured successfully