Link or unlink phone numbers from your assistants. When you link a phone number to an assistant, incoming calls to that number will be handled by that assistant.
Endpoints#
| Endpoint | Method | Description |
|---|
/v1/assistants/{id}/phone-number | GET | Get linked phone number |
/v1/assistants/{id}/phone-number | POST | Link a phone number |
/v1/assistants/{id}/phone-number | DELETE | Unlink phone number |
Get Linked Phone Number#
Retrieve the phone number currently linked to an assistant.Endpoint#
GET /v1/assistants/{id}/phone-number
Path Parameters#
| Parameter | Type | Required | Description |
|---|
id | uuid | Yes | Assistant ID |
Example Request#
Example Response#
{
"data": {
"assistant_id": "660e8400-e29b-41d4-a716-446655440000",
"assistant_name": "Customer Support Agent",
"phone_number": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"number": "+31201234567",
"type": "local",
"locality": "Amsterdam",
"origin": "custom"
}
}
}
Response (No Phone Number Linked)#
{
"data": {
"assistant_id": "660e8400-e29b-41d4-a716-446655440000",
"assistant_name": "Customer Support Agent",
"phone_number": null
}
}
Link Phone Number#
Link a phone number to an assistant. If the assistant already has a phone number, it will be automatically unlinked first.Endpoint#
POST /v1/assistants/{id}/phone-number
Path Parameters#
| Parameter | Type | Required | Description |
|---|
id | uuid | Yes | Assistant ID |
Request Body#
| Field | Type | Required | Description |
|---|
phone_number_id | uuid | Yes | The ID of the phone number to link |
Example Request#
Example Response#
{
"message": "Phone number linked successfully",
"data": {
"assistant_id": "660e8400-e29b-41d4-a716-446655440000",
"phone_number": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"number": "+31201234567",
"type": "local",
"locality": "Amsterdam"
},
"previous_phone_number_id": null,
"released_assistants": 0
}
}
released_assistants field shows how many were affected.
Unlink Phone Number#
Remove the phone number from an assistant. The phone number becomes available again.Endpoint#
DELETE /v1/assistants/{id}/phone-number
Path Parameters#
| Parameter | Type | Required | Description |
|---|
id | uuid | Yes | Assistant ID |
Example Request#
Example Response#
{
"message": "Phone number unlinked successfully",
"data": {
"assistant_id": "660e8400-e29b-41d4-a716-446655440000",
"unlinked_phone_number": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"number": "+31201234567"
}
}
}
Request JSON Schema (POST)#
{
"type": "object",
"properties": {
"phone_number_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the phone number to link (from GET /v1/phone-numbers)"
}
},
"required": ["phone_number_id"]
}
Response JSON Schema (GET)#
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"assistant_id": { "type": "string", "format": "uuid" },
"assistant_name": { "type": "string" },
"phone_number": {
"type": "object",
"nullable": true,
"properties": {
"id": { "type": "string", "format": "uuid" },
"number": { "type": "string" },
"type": { "type": "string", "enum": ["local", "mobile", "national"], "nullable": true },
"locality": { "type": "string", "nullable": true },
"origin": { "type": "string", "enum": ["default", "custom"] }
}
}
}
}
}
}
Response JSON Schema (POST)#
{
"type": "object",
"properties": {
"message": { "type": "string" },
"data": {
"type": "object",
"properties": {
"assistant_id": { "type": "string", "format": "uuid" },
"phone_number": {
"type": "object",
"properties": {
"id": { "type": "string", "format": "uuid" },
"number": { "type": "string" },
"type": { "type": "string", "nullable": true },
"locality": { "type": "string", "nullable": true }
}
},
"previous_phone_number_id": { "type": "string", "format": "uuid", "nullable": true },
"released_assistants": { "type": "integer" }
}
}
}
}
Response JSON Schema (DELETE)#
{
"type": "object",
"properties": {
"message": { "type": "string" },
"data": {
"type": "object",
"properties": {
"assistant_id": { "type": "string", "format": "uuid" },
"unlinked_phone_number": {
"type": "object",
"nullable": true,
"properties": {
"id": { "type": "string", "format": "uuid" },
"number": { "type": "string" }
}
}
}
}
}
}
Error Codes#
| Code | HTTP Status | Description |
|---|
invalid_parameters | 400 | Invalid phone_number_id format |
not_found | 404 | Assistant or phone number not found |
forbidden | 403 | Phone number does not belong to you |
already_linked | 400 | Phone number already linked to this assistant |
already_in_use | 400 | Custom phone number is linked to another assistant |
no_phone_number | 400 | No phone number to unlink |
Modified at 2025-12-08 10:36:20
