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

import requests

url = "https://api.callhq.ai/api/phone-numbers/inbound/setup"

payload = {
    "assistantId": "<string>",
    "phoneNumberId": "<string>"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({assistantId: '<string>', phoneNumberId: '<string>'})
};

fetch('https://api.callhq.ai/api/phone-numbers/inbound/setup', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.callhq.ai/api/phone-numbers/inbound/setup",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'assistantId' => '<string>',
    'phoneNumberId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.callhq.ai/api/phone-numbers/inbound/setup"

	payload := strings.NewReader("{\n  \"assistantId\": \"<string>\",\n  \"phoneNumberId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.callhq.ai/api/phone-numbers/inbound/setup")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"assistantId\": \"<string>\",\n  \"phoneNumberId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.callhq.ai/api/phone-numbers/inbound/setup")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"assistantId\": \"<string>\",\n  \"phoneNumberId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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

import requests

url = "https://api.callhq.ai/api/phone-numbers/inbound/setup"

payload = {
    "assistantId": "<string>",
    "phoneNumberId": "<string>"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({assistantId: '<string>', phoneNumberId: '<string>'})
};

fetch('https://api.callhq.ai/api/phone-numbers/inbound/setup', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.callhq.ai/api/phone-numbers/inbound/setup",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'assistantId' => '<string>',
    'phoneNumberId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.callhq.ai/api/phone-numbers/inbound/setup"

	payload := strings.NewReader("{\n  \"assistantId\": \"<string>\",\n  \"phoneNumberId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.callhq.ai/api/phone-numbers/inbound/setup")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"assistantId\": \"<string>\",\n  \"phoneNumberId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.callhq.ai/api/phone-numbers/inbound/setup")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"assistantId\": \"<string>\",\n  \"phoneNumberId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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

Header	Value	Required
`x-api-key`	Your API key	Yes
`Content-Type`	`application/json`	Yes
`accept`	`/`	No

Request Body

Field	Type	Required	Description
`assistantId`	String	Yes	ID of the assistant to handle inbound calls
`phoneNumberId`	String	Yes	ID 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 Code	Description
400	Missing required fields
404	Assistant or phone number not found
500	Failed 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

List Phone Numbers - Retrieve available phone numbers and their IDs
List Assistants - Retrieve assistant IDs to use with inbound routing

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

API Documentation

Assistant

Call

Chat

Phone Numbers

Knowledge Base

Setup Inbound Agent

Overview

Request

Headers

Request Body

Example Request

Response

Success Response (200)

Error Responses

Use Cases

Authorizations

Body

Response

​Overview

​Request

​Headers

​Request Body

​Example Request

​Response

​Success Response (200)

​Error Responses

​Use Cases

​Related Endpoints

Authorizations

Body

Response

Overview

Request

Headers

Request Body

Example Request

Response

Success Response (200)

Error Responses

Use Cases

Related Endpoints