Skip to main content
POST
/
v1
/
voice
/
phone-numbers
/
{phone_number}
/
update-agent
Update Phone Agent
curl --request POST \
  --url https://api.example.com/v1/voice/phone-numbers/{phone_number}/update-agent \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "inbound_agent_id": "<string>",
  "outbound_agent_id": "<string>",
  "nickname": "<string>"
}
'
{
  "success": true,
  "phone_number": "<string>",
  "message": "<string>",
  "inbound_agent_id": "<string>",
  "outbound_agent_id": "<string>",
  "nickname": "<string>",
  "powered_by": "<string>"
}

​
Description

Updates the agent assignments for a phone number. You can configure separate agents for handling inbound calls (calls received) and outbound calls (calls made from this number). This is essential for:
  • Inbound AI receptionist: Link an agent to answer incoming calls
  • Outbound campaigns: Link an agent for making automated outbound calls
  • Dual-purpose numbers: Use different agents for inbound vs outbound

​
Authentication

​
X-API-Key
string
required
Your Teli API key

​
Path Parameters

​
phone_number
string
required
Phone number in E.164 format (e.g., +14155551234)

​
Request Body

​
inbound_agent_id
string
Agent ID for handling incoming calls to this number.
  • Use the agent_id returned when creating a voice agent
  • Set to empty string "" or null to clear the assignment
Example: "agent_abc123"
​
outbound_agent_id
string
Agent ID for making outbound calls from this number.
  • Used in voice campaigns when this number is the caller ID
  • Set to empty string "" or null to clear the assignment
Example: "agent_xyz789"
​
nickname
string
Optional friendly name for the phone number.Example: "Main Reception Line"
At least one of inbound_agent_id, outbound_agent_id, or nickname is required.

​
Response Fields

​
success
boolean
Whether the update was successful
​
phone_number
string
The phone number that was updated
​
message
string
Status message
​
inbound_agent_id
string
The inbound agent ID (if updated)
​
outbound_agent_id
string
The outbound agent ID (if updated)
​
nickname
string
The nickname (if updated)
​
powered_by
string
Always returns “Teli”

​
Example Requests

cURL
curl -X POST "https://api.teli.ai/v1/voice/phone-numbers/+14155551234/update-agent" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_agent_id": "agent_abc123"
  }'
JavaScript
const response = await fetch(
  'https://api.teli.ai/v1/voice/phone-numbers/+14155551234/update-agent',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      inbound_agent_id: 'agent_abc123'
    })
  }
);

const data = await response.json();
console.log(data);
Python
import requests

response = requests.post(
    'https://api.teli.ai/v1/voice/phone-numbers/+14155551234/update-agent',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={
        'inbound_agent_id': 'agent_abc123'
    }
)

data = response.json()
print(data)
cURL
curl -X POST "https://api.teli.ai/v1/voice/phone-numbers/+14155551234/update-agent" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_agent_id": "agent_abc123",
    "outbound_agent_id": "agent_xyz789",
    "nickname": "Main Sales Line"
  }'

​
Clear an Agent Assignment

cURL
curl -X POST "https://api.teli.ai/v1/voice/phone-numbers/+14155551234/update-agent" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_agent_id": ""
  }'

​
Example Responses

200 Success
{
  "success": true,
  "phone_number": "+14155551234",
  "message": "Phone number updated successfully",
  "inbound_agent_id": "agent_abc123",
  "outbound_agent_id": "agent_xyz789",
  "nickname": "Main Sales Line",
  "powered_by": "Teli"
}
400 Missing Fields
{
  "error": "At least one of inbound_agent_id, outbound_agent_id, or nickname required",
  "success": false,
  "powered_by": "Teli"
}
500 Agent Not Found
{
  "error": "Agent not found or invalid agent ID",
  "success": false,
  "powered_by": "Teli"
}
500 Phone Not Found
{
  "error": "Phone number not found or invalid",
  "success": false,
  "powered_by": "Teli"
}

​
Use Cases

​
1. AI Receptionist (Inbound Only)

Link a voice agent to answer incoming calls automatically: 
{
  "inbound_agent_id": "agent_receptionist_001"
}
When calls come in to this number, the linked agent will answer and handle the conversation.

​
2. Outbound Campaign Number

Link an agent for making outbound calls: 
{
  "outbound_agent_id": "agent_sales_dialer_001"
}
When starting a voice campaign with this phone number as the caller ID, this agent will be used.

​
3. Dual-Purpose Number

Use different agents for inbound vs outbound: 
{
  "inbound_agent_id": "agent_support_001",
  "outbound_agent_id": "agent_sales_001",
  "nickname": "Customer Success Line"
}
  • Incoming calls: Handled by support agent
  • Outgoing campaigns: Uses sales agent

​
Notes

  • Agent IDs: Use the agent_id returned from POST /v1/agents (voice agent creation)
  • Phone format: Always use E.164 format (+1XXXXXXXXXX)
  • Clearing agents: Set to empty string "" or null to remove an agent assignment
  • Both methods supported: POST and PATCH are both accepted
  • POST /v1/voice/phone-numbers/create - Create a new phone number
  • GET /v1/voice/phone-numbers - List phone numbers
  • POST /v1/agents - Create a voice agent
  • GET /v1/agents - List agents
  • POST /v1/voice/campaigns - Start a voice campaign