Telephony

Phone numbers

Import DIDs (or PBX extensions) onto a SIP trunk, route inbound calls to an assistant, place outbound calls, and release numbers.

GET/telephony/numbers agents:read

List numbers

List all phone numbers with their trunk and routed assistant.

bash

curl https://api.bolchoai.in/v1/telephony/numbers -H "Authorization: Bearer $BOLCHO_API_KEY"

POST/telephony/numbers agents:write

Import a number

Attach a DID (or non-E164 extension) from a SIP trunk and optionally route it to an assistant.

Body

trunkId*	uuid	SIP trunk the number belongs to.
number*	string	E.164 number, or any string when allowNonE164 is true.
allowNonE164	boolean	Disable E.164 validation (e.g. PBX extension 8200).
label	string	Friendly label.
agentId	uuid	Assistant that answers inbound calls to this number.

bash

curl -X POST https://api.bolchoai.in/v1/telephony/numbers -H "Authorization: Bearer $BOLCHO_API_KEY" -H "Content-Type: application/json" \
  -d '{ "trunkId": "'$TRUNK_ID'", "number": "+14155551234", "agentId": "'$AGENT_ID'" }'

POST/telephony/numbers/{id}/route agents:write

Route to assistant

Set (or clear) the assistant that answers inbound calls to this number.

Path parameters

id*

uuid

Number id.

Body

agentId

uuid | null

Assistant id, or null to unroute.

bash

curl -X POST https://api.bolchoai.in/v1/telephony/numbers/$ID/route \
  -H "Authorization: Bearer $BOLCHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agentId": "00000000-0000-0000-0000-000000000000"
}'

PATCH/telephony/numbers/{id} agents:write

Update number

Update inbound/outbound assistants, capabilities, or label. Only the fields you send are changed.

Path parameters

id*

uuid

Number id.

Body

inboundAgentId	uuid \| null	Assistant that answers inbound calls.
outboundAgentId	uuid \| null	Assistant used for outbound calls.
inbound	boolean	Enable/disable inbound.
outbound	boolean	Enable/disable outbound.
label	string	Friendly label.

bash

curl -X PATCH https://api.bolchoai.in/v1/telephony/numbers/$ID \
  -H "Authorization: Bearer $BOLCHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "inboundAgentId": "00000000-0000-0000-0000-000000000000",
  "outboundAgentId": "00000000-0000-0000-0000-000000000000",
  "inbound": true,
  "outbound": true,
  "label": "string"
}'

DELETE/telephony/numbers/{id} agents:write

Release number

Remove the number and re-sync the trunk.

Path parameters

id*

uuid

Number id.

bash

curl -X DELETE https://api.bolchoai.in/v1/telephony/numbers/$ID \
  -H "Authorization: Bearer $BOLCHO_API_KEY"

POST/telephony/dial calls:write

Place an outbound call

Dial a destination from one of your numbers and connect the assistant the moment the callee answers. Waits for the SIP disposition and returns the call id — pass async:true to get the id immediately instead.

Body

fromNumberId*	uuid	The number to call from (must be on an outbound-capable trunk).
to*	string	Destination in E.164, e.g. +14155551234.
agentId	uuid	Assistant to run (defaults to the number's routed assistant).
variableValues	object	Per-call {{variable}} values for this callee — override the assistant's defaults in the prompt and first message.
customerName	string	Names the customer record for this number (otherwise it is created from the number alone).
async	boolean	Return as soon as the call is created (status "queued") instead of waiting up to 45s for pickup. Poll GET /calls/{id} for the outcome. Use this for queue-driven dialing.

bash

curl -X POST https://api.bolchoai.in/v1/telephony/dial -H "Authorization: Bearer $BOLCHO_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "fromNumberId": "'$NUMBER_ID'",
    "to": "+14155551234",
    "agentId": "'$AGENT_ID'",
    "customerName": "Alex Rivera",
    "variableValues": { "name": "Alex", "plan": "Pro" }
  }'

Response

json

{ "ok": true, "status": "answered", "callId": "c1…", "to": "+14155551234" }

// with async: true
{ "ok": true, "status": "queued", "callId": "c1…", "to": "+14155551234" }

// dial failed (400) — the call row exists and is already stamped
{ "message": "Call not connected: no answer", "callId": "c1…", "endedReason": "no_answer" }