enterprise_ai.telephony

Source: sdks/python/src/enterprise_ai/telephony/__init__.py. Back to the Python SDK reference index.

note

This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.

Class TelephonyClient

/v1/telephony: settings, quotas, PBX pools, SIP trunks, numbers, extensions, routing, IVR, queues, agents, AI voice agents, conferences, publication, calls, recordings, voicemail, prompts, fraud and infrastructure.

Resource

TelephonyClient.acknowledge_fraud_alert

acknowledge_fraud_alert(alert_id: str) -> Any

Acknowledge a fraud alert. Marks the alert acknowledged and answers it. Needs tenant_admin or platform_admin. Audited under telephony.fraud.acknowledge.

Route: /v1/telephony/fraud-alerts/{alert_id}/acknowledge (POST).

Name	Type	Default	Required	Description
alert_id	str		yes	Identifier (UUID) of the fraud alert.

Returns: Any. Decoded JSON answer of the operation "Acknowledge a fraud alert".

Raises: the typed errors of the transport (Errors).

TelephonyClient.active_calls

active_calls(extension: str | None = None, queue: str | None = None) -> Any

List the active calls. Calls in progress of the tenant: {items, count}, each item linkedid, call_id, navin_call_id, branch, state (ringing, queued, answered), direction, from, to, extension, queue, started_at, answered_at, duration_seconds, node and channels (uniqueid, channel, state, node). Kept up to date by the CEL events (CHAN_START, ANSWER, CHAN_END, LINKEDID_END) and the LiveKit webhooks. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/active-calls (GET).

Name	Type	Default	Required	Description
extension	str | None	None	no	Only this extension number (2 to 8 digits).
queue	str | None	None	no	Only this queue (name without the tid).

Returns: Any. Decoded JSON answer of the operation "List the active calls".

Raises: the typed errors of the transport (Errors).

TelephonyClient.add_queue_member

add_queue_member(queue_id: str, extension_id: str | None = None, agent_id: str | None = None, penalty: int | None = None, idempotency_key: str | None = None) -> Any

Add a member to a queue. Adds exactly one extension or human agent of the tenant (422 telephony_member_target or telephony_reference_invalid). Idempotency-Key honoured. Needs tenant_admin or platform_admin; audited under telephony.queue_member.create.

Route: /v1/telephony/queues/{queue_id}/members (POST).

Name	Type	Default	Required	Description
queue_id	str		yes	Identifier (UUID) of the queue.
extension_id	str | None	None	no	Extension of the tenant (or agent_id, not both).
agent_id	str | None	None	no	Human agent of the tenant, reached on its extension.
penalty	int | None	None	no	Penalty 0 to 100, lower rings first.
idempotency_key	str | None	None	no	Idempotency-Key header: a retry with the same key replays the first answer.

Returns: Any. Decoded JSON answer of the operation "Add a member to a queue".

Raises: the typed errors of the transport (Errors).

TelephonyClient.agent

agent(agent_id: str) -> Any

Read a human agent. One human agent of the caller's tenant; 404 telephony_not_found otherwise. Secrets are never returned, only has_* flags. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/agents/{item_id} (GET).

Name	Type	Default	Required	Description
agent_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).

Returns: Any. Decoded JSON answer of the operation "Read a human agent".

Raises: the typed errors of the transport (Errors).

TelephonyClient.agents

agents(enabled: bool | None = None, limit: int | None = None, cursor: str | None = None) -> Any

List the human agents. The human agents of the caller's tenant, by identifier, limit per page (default 50, at most 500) with next_cursor for the next page. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/agents (GET).

Name	Type	Default	Required	Description
enabled	bool | None	None	no	Only the enabled (true) or disabled (false) objects. Default: both.
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the human agents".

Raises: the typed errors of the transport (Errors).

TelephonyClient.blocks

blocks(active: bool | None = None) -> Any

List the blocks. Blocks of the tenant and of its extensions, newest first: id, scope, extension, reason, origin (manual, automatic), alert_id, active, kamailio_key (key of the Kamailio hash table tenant_blocks), kamailio (push report per JSONRPC endpoint), created_by, created_at, lifted_by, lifted_at, lift_reason. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/blocks (GET).

Name	Type	Default	Required	Description
active	bool | None	None	no	Only the active (true) or lifted (false) blocks.

Returns: Any. Decoded JSON answer of the operation "List the blocks".

Raises: the typed errors of the transport (Errors).

TelephonyClient.call

call(call_id: str) -> Any

Read a call. One call with legs (one per Asterisk channel, from the Cdr events), events (CEL, AMI, LiveKit and voice worker events in time order: source, type, occurred_at, uniqueid, channel, node, data) and recordings (same fields as GET /v1/telephony/recordings). Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/calls/{call_id} (GET).

Name	Type	Default	Required	Description
call_id	str		yes	Identifier (UUID) of the call record, in the caller's tenant (another tenant's call answers 404).

Returns: Any. Decoded JSON answer of the operation "Read a call".

Raises: the typed errors of the transport (Errors).

TelephonyClient.calls

calls(direction: str | None = None, branch: str | None = None, disposition: str | None = None, extension: str | None = None, number: str | None = None, queue: str | None = None, answered: bool | None = None, since: str | None = None, until: str | None = None, limit: int | None = None, cursor: str | None = None) -> Any

List the calls. Call history of the tenant, newest first. Each item: id, navin_call_id, linkedid, branch (pbx or ai), direction (inbound, outbound, internal, unknown), from, from_name, to, did, extension, queue, voice_agent_id, started_at, answered_at, ended_at, duration_seconds, billsec, wait_seconds, disposition, hangup_cause, hangup_cause_text, recording_id, legs, sip_call_id, livekit_room, pbx_instance_id, node. Built from the Cdr and CEL events of AMI and the LiveKit webhooks. Keyset pagination: limit (1 to 500, default 50) and the opaque cursor of next_cursor. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/calls (GET).

Name	Type	Default	Required	Description
direction	str | None	None	no	Only this direction.
branch	str | None	None	no	Only this branch: pbx (Asterisk) or ai (LiveKit SIP).
disposition	str | None	None	no	Only this disposition of the Asterisk CDR.
extension	str | None	None	no	Only this extension number (2 to 8 digits).
number	str | None	None	no	Only the calls whose caller, callee or DID is this number.
queue	str | None	None	no	Only this queue (name without the tid).
answered	bool | None	None	no	true: answered calls only; false: unanswered calls only.
since	str | None	None	no	Calls started at or after this time (ISO 8601).
until	str | None	None	no	Calls started before this time (ISO 8601).
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the calls".

Raises: the typed errors of the transport (Errors).

TelephonyClient.conference

conference(conference_id: str) -> Any

Read a conference room. One conference room of the caller's tenant; 404 telephony_not_found otherwise. Secrets are never returned, only has_* flags. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/conferences/{item_id} (GET).

Name	Type	Default	Required	Description
conference_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).

Returns: Any. Decoded JSON answer of the operation "Read a conference room".

Raises: the typed errors of the transport (Errors).

TelephonyClient.conference_session

conference_session(session_id: str) -> Any

Read a conference session. One conference session with its participants (same fields as the list). Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/conference-sessions/{session_id} (GET).

Name	Type	Default	Required	Description
session_id	str		yes	Identifier (UUID) of the conference session.

Returns: Any. Decoded JSON answer of the operation "Read a conference session".

Raises: the typed errors of the transport (Errors).

TelephonyClient.conference_sessions

conference_sessions(conference_id: str | None = None, active: bool | None = None, limit: int | None = None, cursor: str | None = None) -> Any

List the conference sessions. Sessions of the conference rooms of the tenant, from the Confbridge events of AMI, newest first: id, conference_id, number, started_at, ended_at, active, participant_count, max_participants, total_joins, participants (uniqueid, channel, caller, name, joined_at), recorded, recording_id. Keyset pagination: limit (1 to 500, default 50) and the opaque cursor of next_cursor. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/conference-sessions (GET).

Name	Type	Default	Required	Description
conference_id	str | None	None	no	Only the sessions of this conference room.
active	bool | None	None	no	true: sessions in progress; false: ended sessions.
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the conference sessions".

Raises: the typed errors of the transport (Errors).

TelephonyClient.conferences

conferences(limit: int | None = None, cursor: str | None = None) -> Any

List the conference rooms. The conference rooms of the caller's tenant, by identifier, limit per page (default 50, at most 500) with next_cursor for the next page. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/conferences (GET).

Name	Type	Default	Required	Description
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the conference rooms".

Raises: the typed errors of the transport (Errors).

TelephonyClient.config_version

config_version(version_id: str) -> Any

Read a configuration version. One version with its files (secrets masked), Kamailio tables, LiveKit objects, delivery report per node (files read back and compared, reload outputs, restore), status and diff to the previous version. 404 when the caller may not read its pool.

Route: /v1/telephony/config-versions/{version_id} (GET).

Name	Type	Default	Required	Description
version_id	str		yes	Identifier (UUID) of the configuration version.

Returns: Any. Decoded JSON answer of the operation "Read a configuration version".

Raises: the typed errors of the transport (Errors).

TelephonyClient.create_agent

create_agent(user_id: str, display_name: str, idempotency_key: str | None = None, **extra: Any) -> Any

Create a human agent. Creates the human agent in the caller's tenant and returns it (201). The extension must belong to the tenant. With an Idempotency-Key, a retry with the same body returns the first answer (Idempotency-Replayed: true), another body answers 409 idempotency_conflict. Validation problems answer 422 with every problem in details.errors (code, path, message_en, message_fr). Needs tenant_admin or platform_admin; audited under telephony.agent.create.

Route: /v1/telephony/agents (POST).

Name	Type	Default	Required	Description
user_id	str		yes	Identifier of the user in the platform, unique in the tenant.
display_name	str		yes	Name of the agent.
idempotency_key	str | None	None	no	Idempotency-Key header: a retry with the same key replays the first answer.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Create a human agent".

Raises: the typed errors of the transport (Errors).

TelephonyClient.create_block

create_block(scope: str, reason: str, extension: str | None = None) -> Any

Block the tenant or an extension. Writes the key {tid} or {tid}-{extension} into the Kamailio hash table tenant_blocks of every JSONRPC endpoint of the pool (htable.sets) and answers the block (201); an existing active block of the same scope is answered as is. 422 telephony_block_scope when the scope and the extension do not match. The worker job telephony_blocks pushes the active blocks again after a Kamailio restart. Needs tenant_admin or platform_admin. Audited under telephony.block.create, published as telephony.block.created.

Route: /v1/telephony/blocks (POST).

Name	Type	Default	Required	Description
scope	str		yes	tenant (every call of the tenant) or extension.
reason	str		yes	Reason kept with the block and in the audit trail.
extension	str | None	None	no	Extension number, required for the scope extension only.

Returns: Any. Decoded JSON answer of the operation "Block the tenant or an extension".

Raises: the typed errors of the transport (Errors).

TelephonyClient.create_conference

create_conference(number: str, name: str, idempotency_key: str | None = None, **extra: Any) -> Any

Create a conference room. Creates the conference room in the caller's tenant and returns it (201). The PIN is write only: the answer carries has_pin. With an Idempotency-Key, a retry with the same body returns the first answer (Idempotency-Replayed: true), another body answers 409 idempotency_conflict. Validation problems answer 422 with every problem in details.errors (code, path, message_en, message_fr). Needs tenant_admin or platform_admin; audited under telephony.conference.create.

Route: /v1/telephony/conferences (POST).

Name	Type	Default	Required	Description
number	str		yes	Number of the room, 2 to 8 digits, unique in the tenant.
name	str		yes	Name of the room.
idempotency_key	str | None	None	no	Idempotency-Key header: a retry with the same key replays the first answer.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Create a conference room".

Raises: the typed errors of the transport (Errors).

TelephonyClient.create_extension

create_extension(number: str, display_name: str, idempotency_key: str | None = None, **extra: Any) -> Any

Create an extension. Creates the extension in the caller's tenant and returns it (201). The SIP password and the voicemail PIN are write only: the answer carries has_password and has_voicemail_pin. The number is unique in the tenant across extensions, queues and conferences (409 telephony_number_in_use) and may not start with a national or international prefix nor be an emergency number (422 telephony_number_reserved). With an Idempotency-Key, a retry with the same body returns the first answer (Idempotency-Replayed: true), another body answers 409 idempotency_conflict. Validation problems answer 422 with every problem in details.errors (code, path, message_en, message_fr). Needs tenant_admin or platform_admin; audited under telephony.extension.create.

Route: /v1/telephony/extensions (POST).

Name	Type	Default	Required	Description
number	str		yes	Extension number, 2 to 8 digits, unique in the tenant.
display_name	str		yes	Name shown as caller id.
idempotency_key	str | None	None	no	Idempotency-Key header: a retry with the same key replays the first answer.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Create an extension".

Raises: the typed errors of the transport (Errors).

TelephonyClient.create_ivr_flow

create_ivr_flow(name: str, description: str | None = None, idempotency_key: str | None = None) -> Any

Create an IVR flow. Creates the IVR flow in the caller's tenant and returns it (201). The graph lives in the versions of the flow. With an Idempotency-Key, a retry with the same body returns the first answer (Idempotency-Replayed: true), another body answers 409 idempotency_conflict. Validation problems answer 422 with every problem in details.errors (code, path, message_en, message_fr). Needs tenant_admin or platform_admin; audited under telephony.ivr_flow.create.

Route: /v1/telephony/ivr-flows (POST).

Name	Type	Default	Required	Description
name	str		yes	Name, unique in the tenant: lowercase letters, digits and -, 1 to 41 characters; it is part of the names on the engines.
description	str | None	None	no	Description of the flow.
idempotency_key	str | None	None	no	Idempotency-Key header: a retry with the same key replays the first answer.

Returns: Any. Decoded JSON answer of the operation "Create an IVR flow".

Raises: the typed errors of the transport (Errors).

TelephonyClient.create_ivr_flow_version

create_ivr_flow_version(flow_id: str, graph: dict[str, Any]) -> Any

Create a version of an IVR flow. Adds a draft version (number + 1). The graph is validated: one start node, every edge names an existing node, every node reachable, unique DTMF digits, every menu with prompt, timeout and invalid exits, a wait of 1 to 30 seconds and 1 to 5 retries; the extensions, queues and voice agents it names exist in the tenant. The prompt of a play or menu node is a sound name of Asterisk or navin:<name>, an uploaded prompt of the tenant (POST /v1/telephony/ivr-prompts) the dialplan plays from its signed URL. Problems answer 422 with every one in details.errors. Needs tenant_admin or platform_admin; audited under telephony.ivr_flow.version.create.

Route: /v1/telephony/ivr-flows/{flow_id}/versions (POST).

Name	Type	Default	Required	Description
flow_id	str		yes	Identifier (UUID) of the IVR flow.
graph	dict[str, Any]		yes	Graph of the flow: start and nodes; menu nodes carry prompt, options (digit, next), timeout, invalid, timeout_seconds and max_retries.

Returns: Any. Decoded JSON answer of the operation "Create a version of an IVR flow".

Raises: the typed errors of the transport (Errors).

TelephonyClient.create_number

create_number(e164: str, destination_kind: str, idempotency_key: str | None = None, **extra: Any) -> Any

Create a phone number. Creates the phone number in the caller's tenant and returns it (201). The E.164 number is unique on the platform (409 telephony_number_taken); the destination must be an object of the tenant (422 telephony_reference_invalid); branch ai needs a voice agent. With an Idempotency-Key, a retry with the same body returns the first answer (Idempotency-Replayed: true), another body answers 409 idempotency_conflict. Validation problems answer 422 with every problem in details.errors (code, path, message_en, message_fr). Needs tenant_admin or platform_admin; audited under telephony.number.create.

Route: /v1/telephony/numbers (POST).

Name	Type	Default	Required	Description
e164	str		yes	Public number in E.164 format, unique on the platform.
destination_kind	str		yes	Kind of destination: extension, ivr, queue, voice_agent, conference or external.
idempotency_key	str | None	None	no	Idempotency-Key header: a retry with the same key replays the first answer.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Create a phone number".

Raises: the typed errors of the transport (Errors).

TelephonyClient.create_pool

create_pool(name: str, mode: str, **extra: Any) -> Any

Declare a PBX pool. Declares an Asterisk pool installed by the Navin Manager: nodes and their AMI port, references of the AMI, ARI, JSONRPC and auth_ephemeral secrets (openbao:// or env://EAI_CRED_*, never a value), Kamailio endpoints and addresses, dispatcher sets and LiveKit binding. A shared pool has no tenant, a dedicated pool one (422 telephony_pool_mode). Needs platform_admin; audited under telephony.pbx_pool.create.

Route: /v1/telephony/pbx-pools (POST).

Name	Type	Default	Required	Description
name	str		yes	Name of the pool, unique on the platform.
mode	str		yes	shared (several tenants) or dedicated (one tenant).
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Declare a PBX pool".

Raises: the typed errors of the transport (Errors).

TelephonyClient.create_queue

create_queue(name: str, idempotency_key: str | None = None, **extra: Any) -> Any

Create a call queue. Creates the call queue in the caller's tenant and returns it (201). Its optional number follows the extension number rules. With an Idempotency-Key, a retry with the same body returns the first answer (Idempotency-Replayed: true), another body answers 409 idempotency_conflict. Validation problems answer 422 with every problem in details.errors (code, path, message_en, message_fr). Needs tenant_admin or platform_admin; audited under telephony.queue.create.

Route: /v1/telephony/queues (POST).

Name	Type	Default	Required	Description
name	str		yes	Name, unique in the tenant: lowercase letters, digits and -, 1 to 41 characters; it is part of the names on the engines.
idempotency_key	str | None	None	no	Idempotency-Key header: a retry with the same key replays the first answer.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Create a call queue".

Raises: the typed errors of the transport (Errors).

TelephonyClient.create_routing_rule

create_routing_rule(name: str, direction: str, pattern: str, idempotency_key: str | None = None, **extra: Any) -> Any

Create a routing rule. Creates the routing rule in the caller's tenant and returns it (201). Outbound rules list the trunks of the tenant in failover order; inbound rules need a destination of the tenant. With an Idempotency-Key, a retry with the same body returns the first answer (Idempotency-Replayed: true), another body answers 409 idempotency_conflict. Validation problems answer 422 with every problem in details.errors (code, path, message_en, message_fr). Needs tenant_admin or platform_admin; audited under telephony.routing_rule.create.

Route: /v1/telephony/routing-rules (POST).

Name	Type	Default	Required	Description
name	str		yes	Name, unique in the tenant: lowercase letters, digits and -, 1 to 41 characters; it is part of the names on the engines.
direction	str		yes	inbound (called DID) or outbound (dialled E.164 number).
pattern	str		yes	Asterisk pattern on the E.164 number, for example _+33X..
idempotency_key	str | None	None	no	Idempotency-Key header: a retry with the same key replays the first answer.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Create a routing rule".

Raises: the typed errors of the transport (Errors).

TelephonyClient.create_trunk

create_trunk(name: str, host: str, idempotency_key: str | None = None, **extra: Any) -> Any

Create a SIP trunk. Creates the SIP trunk in the caller's tenant and returns it (201). The password is write only: the answer carries has_password. With an Idempotency-Key, a retry with the same body returns the first answer (Idempotency-Replayed: true), another body answers 409 idempotency_conflict. Validation problems answer 422 with every problem in details.errors (code, path, message_en, message_fr). Needs tenant_admin or platform_admin; audited under telephony.trunk.create.

Route: /v1/telephony/trunks (POST).

Name	Type	Default	Required	Description
name	str		yes	Name, unique in the tenant: lowercase letters, digits and -, 1 to 41 characters; it is part of the names on the engines.
host	str		yes	Host name or address of the operator SIP server.
idempotency_key	str | None	None	no	Idempotency-Key header: a retry with the same key replays the first answer.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Create a SIP trunk".

Raises: the typed errors of the transport (Errors).

TelephonyClient.create_voice_agent

create_voice_agent(name: str, llm_model_alias: str, idempotency_key: str | None = None, **extra: Any) -> Any

Create an AI voice agent. Creates the AI voice agent in the caller's tenant and returns it (201). The fallback queue must belong to the tenant. With an Idempotency-Key, a retry with the same body returns the first answer (Idempotency-Replayed: true), another body answers 409 idempotency_conflict. Validation problems answer 422 with every problem in details.errors (code, path, message_en, message_fr). Needs tenant_admin or platform_admin; audited under telephony.voice_agent.create.

Route: /v1/telephony/voice-agents (POST).

Name	Type	Default	Required	Description
name	str		yes	Name, unique in the tenant: lowercase letters, digits and -, 1 to 41 characters; it is part of the names on the engines.
llm_model_alias	str		yes	Alias of the language model in the LLM gateway.
idempotency_key	str | None	None	no	Idempotency-Key header: a retry with the same key replays the first answer.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Create an AI voice agent".

Raises: the typed errors of the transport (Errors).

TelephonyClient.delete_agent

delete_agent(agent_id: str) -> Any

Delete a human agent. Deletes the human agent (204); the engines lose it at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.agent.delete.

Route: /v1/telephony/agents/{item_id} (DELETE).

Name	Type	Default	Required	Description
agent_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).

Returns: Any. Decoded JSON answer of the operation "Delete a human agent".

Raises: the typed errors of the transport (Errors).

TelephonyClient.delete_conference

delete_conference(conference_id: str) -> Any

Delete a conference room. Deletes the conference room (204); the engines lose it at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.conference.delete.

Route: /v1/telephony/conferences/{item_id} (DELETE).

Name	Type	Default	Required	Description
conference_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).

Returns: Any. Decoded JSON answer of the operation "Delete a conference room".

Raises: the typed errors of the transport (Errors).

TelephonyClient.delete_extension

delete_extension(extension_id: str) -> Any

Delete an extension. Deletes the extension (204); the engines lose it at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.extension.delete.

Route: /v1/telephony/extensions/{item_id} (DELETE).

Name	Type	Default	Required	Description
extension_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).

Returns: Any. Decoded JSON answer of the operation "Delete an extension".

Raises: the typed errors of the transport (Errors).

TelephonyClient.delete_ivr_flow

delete_ivr_flow(flow_id: str) -> Any

Delete an IVR flow. Deletes the IVR flow (204); the engines lose it at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.ivr_flow.delete.

Route: /v1/telephony/ivr-flows/{item_id} (DELETE).

Name	Type	Default	Required	Description
flow_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).

Returns: Any. Decoded JSON answer of the operation "Delete an IVR flow".

Raises: the typed errors of the transport (Errors).

TelephonyClient.delete_ivr_prompt

delete_ivr_prompt(prompt_id: str) -> Any

Delete an IVR prompt. Deletes the prompt and its audio (204); its playback URL answers 404 from then on. 409 telephony_prompt_in_use (with details.ivr_flows) while a draft or published IVR version plays it. Needs tenant_admin or platform_admin. Audited under telephony.ivr_prompt.delete.

Route: /v1/telephony/ivr-prompts/{prompt_id} (DELETE).

Name	Type	Default	Required	Description
prompt_id	str		yes	Identifier (UUID) of the IVR prompt.

Returns: Any. Decoded JSON answer of the operation "Delete an IVR prompt".

Raises: the typed errors of the transport (Errors).

TelephonyClient.delete_number

delete_number(number_id: str) -> Any

Delete a phone number. Deletes the phone number (204); the engines lose it at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.number.delete.

Route: /v1/telephony/numbers/{item_id} (DELETE).

Name	Type	Default	Required	Description
number_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).

Returns: Any. Decoded JSON answer of the operation "Delete a phone number".

Raises: the typed errors of the transport (Errors).

TelephonyClient.delete_pool

delete_pool(pool_id: str) -> Any

Delete a PBX pool. Deletes a pool no tenant uses (409 telephony_pool_in_use otherwise) with its versions. Needs platform_admin; audited under telephony.pbx_pool.delete.

Route: /v1/telephony/pbx-pools/{pool_id} (DELETE).

Name	Type	Default	Required	Description
pool_id	str		yes	Identifier (UUID) of the PBX pool.

Returns: Any. Decoded JSON answer of the operation "Delete a PBX pool".

Raises: the typed errors of the transport (Errors).

TelephonyClient.delete_queue

delete_queue(queue_id: str) -> Any

Delete a call queue. Deletes the call queue (204); the engines lose it at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.queue.delete.

Route: /v1/telephony/queues/{item_id} (DELETE).

Name	Type	Default	Required	Description
queue_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).

Returns: Any. Decoded JSON answer of the operation "Delete a call queue".

Raises: the typed errors of the transport (Errors).

TelephonyClient.delete_recording

delete_recording(recording_id: str, reason: str | None = None) -> Any

Delete a recording. Deletes the object in SeaweedFS and marks the index row deleted (a voicemail message on it is deleted too). 409 telephony_legal_hold under legal hold. Needs tenant_admin or platform_admin. Audited under telephony.recording.delete with the reason.

Route: /v1/telephony/recordings/{recording_id} (DELETE).

Name	Type	Default	Required	Description
recording_id	str		yes	Identifier (UUID) of the recording, in the caller's tenant (another tenant's recording answers 404).
reason	str | None	None	no	Why the action is taken. Written to the audit trail with the actor and the time.

Returns: Any. Decoded JSON answer of the operation "Delete a recording".

Raises: the typed errors of the transport (Errors).

TelephonyClient.delete_routing_rule

delete_routing_rule(rule_id: str) -> Any

Delete a routing rule. Deletes the routing rule (204); the engines lose it at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.routing_rule.delete.

Route: /v1/telephony/routing-rules/{item_id} (DELETE).

Name	Type	Default	Required	Description
rule_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).

Returns: Any. Decoded JSON answer of the operation "Delete a routing rule".

Raises: the typed errors of the transport (Errors).

TelephonyClient.delete_trunk

delete_trunk(trunk_id: str) -> Any

Delete a SIP trunk. Deletes the SIP trunk (204); the engines lose it at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.trunk.delete.

Route: /v1/telephony/trunks/{item_id} (DELETE).

Name	Type	Default	Required	Description
trunk_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).

Returns: Any. Decoded JSON answer of the operation "Delete a SIP trunk".

Raises: the typed errors of the transport (Errors).

TelephonyClient.delete_voice_agent

delete_voice_agent(voice_agent_id: str) -> Any

Delete an AI voice agent. Deletes the AI voice agent (204); the engines lose it at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.voice_agent.delete.

Route: /v1/telephony/voice-agents/{item_id} (DELETE).

Name	Type	Default	Required	Description
voice_agent_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).

Returns: Any. Decoded JSON answer of the operation "Delete an AI voice agent".

Raises: the typed errors of the transport (Errors).

TelephonyClient.delete_voicemail

delete_voicemail(message_id: str) -> Any

Delete a voicemail message. Deletes the message and its audio (409 telephony_legal_hold when the audio is held) and answers it with status deleted. Allowed to the readers and to the agent of the mailbox. Audited under telephony.voicemail.delete.

Route: /v1/telephony/voicemail/{message_id} (DELETE).

Name	Type	Default	Required	Description
message_id	str		yes	Identifier (UUID) of the voicemail message.

Returns: Any. Decoded JSON answer of the operation "Delete a voicemail message".

Raises: the typed errors of the transport (Errors).

TelephonyClient.download_ivr_prompt

download_ivr_prompt(prompt_id: str) -> Any

Get a download link of an IVR prompt. Answers {url, method: GET, expires_seconds: 300, expires_at, content_type, size_bytes, sha256}: a SeaweedFS presigned URL valid 300 seconds; no storage credential is returned. 409 telephony_recording_unavailable when the object is not stored, 503 telephony_storage_missing when the platform profile is missing, 409 storage_capability_missing when presign was not verified. Needs tenant_admin, support_engineer, auditor or platform_admin. Audited under telephony.ivr_prompt.download.

Route: /v1/telephony/ivr-prompts/{prompt_id}/download (POST).

Name	Type	Default	Required	Description
prompt_id	str		yes	Identifier (UUID) of the IVR prompt.

Returns: Any. Decoded JSON answer of the operation "Get a download link of an IVR prompt".

Raises: the typed errors of the transport (Errors).

TelephonyClient.download_recording

download_recording(recording_id: str) -> Any

Get a download link. Answers {url, method: GET, expires_seconds: 300, expires_at, content_type, size_bytes, sha256}: a SeaweedFS presigned URL valid 300 seconds; no storage credential is returned. 409 telephony_recording_unavailable when the object is not stored, 503 telephony_storage_missing when the platform profile is missing, 409 storage_capability_missing when presign was not verified. Needs tenant_admin, support_engineer, auditor or platform_admin. Audited under telephony.recording.download with the SHA-256 of the URL.

Route: /v1/telephony/recordings/{recording_id}/download (POST).

Name	Type	Default	Required	Description
recording_id	str		yes	Identifier (UUID) of the recording, in the caller's tenant (another tenant's recording answers 404).

Returns: Any. Decoded JSON answer of the operation "Get a download link".

Raises: the typed errors of the transport (Errors).

TelephonyClient.drain_destination

drain_destination(pool_id: str, address: str, state: str, group: int | None = None) -> Any

Drain or restore a dispatcher destination. Sets the state of a destination on every Kamailio of the pool (dispatcher.set_state: drain inactive, active back in service) and returns the dispatcher.list of each. Needs platform_admin; audited under telephony.pbx_pool.drain or telephony.pbx_pool.active.

Route: /v1/telephony/pbx-pools/{pool_id}/drain (POST).

Name	Type	Default	Required	Description
pool_id	str		yes	Identifier (UUID) of the PBX pool.
address	str		yes	SIP URI of the destination, for example sip:10.0.0.20:5070.
state	str		yes	drain (no new call) or active.
group	int | None	None	no	Dispatcher set (default: the set of the pool).

Returns: Any. Decoded JSON answer of the operation "Drain or restore a dispatcher destination".

Raises: the typed errors of the transport (Errors).

TelephonyClient.event_streams

event_streams() -> Any

List the AMI event connections. State of the AMI event connection of every node (worker job telephony_events): pool_id, node, connected, connected_at, events, reconnects, last_error, updated_at. Needs platform_admin.

Route: /v1/telephony/event-streams (GET).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "List the AMI event connections".

Raises: the typed errors of the transport (Errors).

TelephonyClient.extension

extension(extension_id: str) -> Any

Read an extension. One extension of the caller's tenant; 404 telephony_not_found otherwise. Secrets are never returned, only has_* flags. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/extensions/{item_id} (GET).

Name	Type	Default	Required	Description
extension_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).

Returns: Any. Decoded JSON answer of the operation "Read an extension".

Raises: the typed errors of the transport (Errors).

TelephonyClient.extensions

extensions(enabled: bool | None = None, limit: int | None = None, cursor: str | None = None) -> Any

List the extensions. The extensions of the caller's tenant, by identifier, limit per page (default 50, at most 500) with next_cursor for the next page. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/extensions (GET).

Name	Type	Default	Required	Description
enabled	bool | None	None	no	Only the enabled (true) or disabled (false) objects. Default: both.
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the extensions".

Raises: the typed errors of the transport (Errors).

TelephonyClient.fraud_alerts

fraud_alerts(status: str | None = None, kind: str | None = None, limit: int | None = None, cursor: str | None = None) -> Any

List the fraud alerts. Fraud signals of the tenant, newest first: id, kind (cps, concurrency, destination_refused, extension_volume), severity, extension, destination, linkedid, details, status, block_id, created_at, acknowledged_at, acknowledged_by. Each alert is also published as telephony.fraud.alert. Keyset pagination: limit (1 to 500, default 50) and the opaque cursor of next_cursor. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/fraud-alerts (GET).

Name	Type	Default	Required	Description
status	str | None	None	no	Only the open or the acknowledged alerts.
kind	str | None	None	no	Only this kind of signal.
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the fraud alerts".

Raises: the typed errors of the transport (Errors).

TelephonyClient.hangup_call

hangup_call(linkedid: str) -> Any

Hang up an active call. Hangs up every channel of the call through ARI (DELETE /ari/channels/{uniqueid} on the node of each channel), or removes the SIP participant through the LiveKit RoomService for the AI branch. Answers {linkedid, results} with one status (ok, gone, failed) per channel; 502 telephony_control_failed when every channel failed. Needs tenant_admin or platform_admin. Audited under telephony.call.hangup.

Route: /v1/telephony/active-calls/{linkedid}/hangup (POST).

Name	Type	Default	Required	Description
linkedid	str		yes	Asterisk linkedid of the active call (linkedid of GET /v1/telephony/active-calls).

Returns: Any. Decoded JSON answer of the operation "Hang up an active call".

Raises: the typed errors of the transport (Errors).

TelephonyClient.infrastructure

infrastructure(cluster_id: str | None = None) -> Any

List the telephony infrastructure of the Navin Manager. Reads, through the Platform Manager bridge (Manager API token, X-NM-On-Behalf-Of, the permissions of the Manager apply), the clusters and their asterisk, kamailio, livekit and livekit-sip instances. Answers {clusters, binding, problems}: each cluster {id, name, mode, services}, each service {name, catalog_service, display_name, mode, method, version, managed, state, health, admin_state, tls_enabled, config_source (manager or defaults), config_version, bound, endpoints [{name, scheme, port, path}], nodes [{name, instance_id, host_id, hostname, fqdn, ip, component, state, desired_state, health, maintenance, host_state, addresses}], bindings {binding: {ref, kind}}, pool ({id, name, mode} of the PBX pool linked to an Asterisk instance, else null)}. Asterisk addresses ami, ari, sip; Kamailio jsonrpc (/RPC, admin address of the host group), sip, wss with TLS; LiveKit api, signal; LiveKit SIP sip. bound is true for the instance bound to navin-enterprise. binding gives flags only (cluster_id, asterisk.bound, asterisk.ami_secret, asterisk.ari_secret, kamailio.bound, kamailio.ephemeral_secret, livekit.bound, livekit.api_secret, livekit_sip.bound), never a value. problems lists the instances whose configuration the Manager refused (telephony_inventory_config_unreadable, catalog defaults used). Needs platform_admin; 503 platform_manager_not_configured, 502 platform_manager_unreachable, a refusal of the Manager is relayed.

Route: /v1/telephony/infrastructure (GET).

Name	Type	Default	Required	Description
cluster_id	str | None	None	no	Only this cluster of the Manager (its identifier).

Returns: Any. Decoded JSON answer of the operation "List the telephony infrastructure of the Navin Manager".

Raises: the typed errors of the transport (Errors).

TelephonyClient.ivr_flow

ivr_flow(flow_id: str) -> Any

Read an IVR flow. One IVR flow of the caller's tenant; 404 telephony_not_found otherwise. Secrets are never returned, only has_* flags. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/ivr-flows/{item_id} (GET).

Name	Type	Default	Required	Description
flow_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).

Returns: Any. Decoded JSON answer of the operation "Read an IVR flow".

Raises: the typed errors of the transport (Errors).

TelephonyClient.ivr_flow_version

ivr_flow_version(flow_id: str, version: int) -> Any

Read a version of an IVR flow. One version of the flow with its graph; 404 telephony_not_found otherwise. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/ivr-flows/{flow_id}/versions/{version} (GET).

Name	Type	Default	Required	Description
flow_id	str		yes	Identifier (UUID) of the IVR flow.
version	int		yes	Version number (1, 2, ...).

Returns: Any. Decoded JSON answer of the operation "Read a version of an IVR flow".

Raises: the typed errors of the transport (Errors).

TelephonyClient.ivr_flow_versions

ivr_flow_versions(flow_id: str, limit: int | None = None, cursor: str | None = None) -> Any

List the versions of an IVR flow. Versions of the flow with their status (draft, published, archived) and graph, by identifier. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/ivr-flows/{flow_id}/versions (GET).

Name	Type	Default	Required	Description
flow_id	str		yes	Identifier (UUID) of the IVR flow.
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the versions of an IVR flow".

Raises: the typed errors of the transport (Errors).

TelephonyClient.ivr_flows

ivr_flows(limit: int | None = None, cursor: str | None = None) -> Any

List the IVR flows. The IVR flows of the caller's tenant, by identifier, limit per page (default 50, at most 500) with next_cursor for the next page. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/ivr-flows (GET).

Name	Type	Default	Required	Description
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the IVR flows".

Raises: the typed errors of the transport (Errors).

TelephonyClient.ivr_prompt

ivr_prompt(prompt_id: str) -> Any

Read an IVR prompt. One IVR prompt; playback_url is filled for tenant_admin and platform_admin only. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/ivr-prompts/{prompt_id} (GET).

Name	Type	Default	Required	Description
prompt_id	str		yes	Identifier (UUID) of the IVR prompt.

Returns: Any. Decoded JSON answer of the operation "Read an IVR prompt".

Raises: the typed errors of the transport (Errors).

TelephonyClient.ivr_prompts

ivr_prompts(limit: int | None = None, cursor: str | None = None) -> Any

List the IVR prompts. IVR prompts of the tenant, newest first (fields of the upload answer, playback_url empty). Keyset pagination: limit (1 to 500, default 50) and the opaque cursor of next_cursor. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/ivr-prompts (GET).

Name	Type	Default	Required	Description
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the IVR prompts".

Raises: the typed errors of the transport (Errors).

TelephonyClient.lift_block

lift_block(block_id: str, reason: str) -> Any

Lift a block. Deletes the Kamailio key on every JSONRPC endpoint (htable.delete) and marks the block lifted. Needs tenant_admin or platform_admin. Audited under telephony.block.lift, published as telephony.block.lifted.

Route: /v1/telephony/blocks/{block_id}/lift (POST).

Name	Type	Default	Required	Description
block_id	str		yes	Identifier (UUID) of the block.
reason	str		yes	Reason kept with the block and in the audit trail.

Returns: Any. Decoded JSON answer of the operation "Lift a block".

Raises: the typed errors of the transport (Errors).

TelephonyClient.listen_voicemail

listen_voicemail(message_id: str) -> Any

Listen to a voicemail message. Answers the message (message) and its presigned link. Answers {url, method: GET, expires_seconds: 300, expires_at, content_type, size_bytes, sha256}: a SeaweedFS presigned URL valid 300 seconds; no storage credential is returned. 409 telephony_recording_unavailable when the object is not stored, 503 telephony_storage_missing when the platform profile is missing, 409 storage_capability_missing when presign was not verified. Allowed to the readers and to the agent of the mailbox. Audited under telephony.voicemail.download.

Route: /v1/telephony/voicemail/{message_id}/listen (POST).

Name	Type	Default	Required	Description
message_id	str		yes	Identifier (UUID) of the voicemail message.

Returns: Any. Decoded JSON answer of the operation "Listen to a voicemail message".

Raises: the typed errors of the transport (Errors).

TelephonyClient.mark_voicemail

mark_voicemail(message_id: str, read: bool | None = None) -> Any

Mark a voicemail message read. Marks the message read (or new again with read=false) and answers it. Allowed to the readers and to the agent of the mailbox. Audited under telephony.voicemail.read or telephony.voicemail.unread.

Route: /v1/telephony/voicemail/{message_id}/read (POST).

Name	Type	Default	Required	Description
message_id	str		yes	Identifier (UUID) of the voicemail message.
read	bool | None	None	no	true (default): read; false: new again.

Returns: Any. Decoded JSON answer of the operation "Mark a voicemail message read".

Raises: the typed errors of the transport (Errors).

TelephonyClient.number

number(number_id: str) -> Any

Read a phone number. One phone number of the caller's tenant; 404 telephony_not_found otherwise. Secrets are never returned, only has_* flags. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/numbers/{item_id} (GET).

Name	Type	Default	Required	Description
number_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).

Returns: Any. Decoded JSON answer of the operation "Read a phone number".

Raises: the typed errors of the transport (Errors).

TelephonyClient.numbers

numbers(enabled: bool | None = None, limit: int | None = None, cursor: str | None = None) -> Any

List the phone numbers. The phone numbers of the caller's tenant, by identifier, limit per page (default 50, at most 500) with next_cursor for the next page. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/numbers (GET).

Name	Type	Default	Required	Description
enabled	bool | None	None	no	Only the enabled (true) or disabled (false) objects. Default: both.
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the phone numbers".

Raises: the typed errors of the transport (Errors).

TelephonyClient.pool

pool(pool_id: str) -> Any

Read a PBX pool. One pool visible to the caller (404 otherwise), limited fields except for platform_admin. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/pbx-pools/{pool_id} (GET).

Name	Type	Default	Required	Description
pool_id	str		yes	Identifier (UUID) of the PBX pool.

Returns: Any. Decoded JSON answer of the operation "Read a PBX pool".

Raises: the typed errors of the transport (Errors).

TelephonyClient.pool_versions

pool_versions(pool_id: str, limit: int | None = None, cursor: str | None = None) -> Any

List the configuration versions of a pool. Versions of the pool, newest first, with status, author, reason, sha256, the SHA-256 of every file, current (the version the engines run) and the delivery report; next_cursor pages by version number. Shared pool: platform_admin; dedicated pool: the readers of its tenant.

Route: /v1/telephony/pbx-pools/{pool_id}/versions (GET).

Name	Type	Default	Required	Description
pool_id	str		yes	Identifier (UUID) of the PBX pool.
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the configuration versions of a pool".

Raises: the typed errors of the transport (Errors).

TelephonyClient.pools

pools(limit: int | None = None, cursor: str | None = None) -> Any

List the PBX pools. Every pool for platform_admin; for the other readers the shared pools and the pools dedicated to their tenant, with id, name, mode, tenant_id, enabled and dispatcher_set only. Secret references are never returned to them; has_* flags tell whether a secret is set. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/pbx-pools (GET).

Name	Type	Default	Required	Description
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the PBX pools".

Raises: the typed errors of the transport (Errors).

TelephonyClient.preview

preview() -> Any

Preview the configuration of the tenant. Compiles the configuration of the caller's tenant alone and validates it, without any delivery: valid, errors (code, path, messages), the five Asterisk files with secrets masked, the Kamailio entries, the desired LiveKit objects and sha256. 409 telephony_not_configured without settings. Needs tenant_admin or platform_admin.

Route: /v1/telephony/preview (POST).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "Preview the configuration of the tenant".

Raises: the typed errors of the transport (Errors).

TelephonyClient.preview_pool

preview_pool(pool_id: str) -> Any

Preview the configuration of a pool. Compiles every tenant of the pool and validates the result (graphs, references, no context of a tenant naming another tenant, a SIP domain for every tenant with extensions: telephony_sip_domain_missing otherwise), without delivery. Returns valid, errors, files (secrets masked), kamailio, livekit, sha256, tenants, current_version, unchanged and diff (unified diff per file to the published version). Shared pool: platform_admin; dedicated pool: its tenant_admin.

Route: /v1/telephony/pbx-pools/{pool_id}/preview (POST).

Name	Type	Default	Required	Description
pool_id	str		yes	Identifier (UUID) of the PBX pool.

Returns: Any. Decoded JSON answer of the operation "Preview the configuration of a pool".

Raises: the typed errors of the transport (Errors).

TelephonyClient.publish_ivr_flow_version

publish_ivr_flow_version(flow_id: str, version: int) -> Any

Publish a version of an IVR flow. Validates the version again and makes it the one the compiler uses; the previously published version is archived. The engines get it at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.ivr_flow.version.publish.

Route: /v1/telephony/ivr-flows/{flow_id}/versions/{version}/publish (POST).

Name	Type	Default	Required	Description
flow_id	str		yes	Identifier (UUID) of the IVR flow.
version	int		yes	Version number (1, 2, ...).

Returns: Any. Decoded JSON answer of the operation "Publish a version of an IVR flow".

Raises: the typed errors of the transport (Errors).

TelephonyClient.publish_pool

publish_pool(pool_id: str, reason: str | None = None, idempotency_key: str | None = None) -> Any

Publish the configuration of a pool. Compiles and validates the pool (422 with every problem, telephony_sip_domain_missing for a tenant with extensions but no SIP domain), records a new version (publishing) and answers 202 with version_id, version, sha256 and operation_id (headers Operation-Id, Operation-Location). In the background every node of the pool gets the files through AMI (CreateConfig, UpdateConfig, reloads, GetConfig read back), then the Kamailio tables and the LiveKit SIP objects are reconciled. The version ends published or failed (the failed nodes get the previous version back); follow it with GET /v1/telephony/config-versions/{version_id} or the operation. One publication at a time per pool (409 telephony_publication_running). Idempotency-Key honoured. Shared pool: platform_admin; dedicated pool: its tenant_admin. Audited under telephony.config.publish then telephony.config.published or telephony.config.failed.

Route: /v1/telephony/pbx-pools/{pool_id}/publish (POST).

Name	Type	Default	Required	Description
pool_id	str		yes	Identifier (UUID) of the PBX pool.
reason	str | None	None	no	Reason, kept with the version and in the audit.
idempotency_key	str | None	None	no	Idempotency-Key header: a retry with the same key replays the first answer.

Returns: Any. Decoded JSON answer of the operation "Publish the configuration of a pool".

Raises: the typed errors of the transport (Errors).

TelephonyClient.put_quotas

put_quotas(**extra: Any) -> Any

Set the telephony quotas. Replaces the quotas of the tenant. Prefixes are + then 1 to 8 digits (422 telephony_prefix_invalid). Needs platform_admin: a tenant never raises its own limits. Audited under telephony.quotas.update.

Route: /v1/telephony/quotas (PUT).

Name	Type	Default	Required	Description
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Set the telephony quotas".

Raises: the typed errors of the transport (Errors).

TelephonyClient.put_runtime_settings

put_runtime_settings(**extra: Any) -> Any

Set the runtime settings. Replaces the runtime settings. voicemail_storage reaches Asterisk at the next publication of the pool (platform voicemail: Record then the UserEvent NavinVoicemail). Needs tenant_admin or platform_admin. Audited under telephony.runtime_settings.update.

Route: /v1/telephony/runtime-settings (PUT).

Name	Type	Default	Required	Description
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Set the runtime settings".

Raises: the typed errors of the transport (Errors).

TelephonyClient.put_settings

put_settings(sip_domain: str, **extra: Any) -> Any

Set the telephony settings. Creates or replaces the settings of the tenant. The SIP domain is unique on the platform (409 telephony_domain_taken). Changing model or pbx_instance_id needs platform_admin (403 otherwise); the pool must be shared or dedicated to this tenant and match the model (422 telephony_pool_mode). Needs tenant_admin or platform_admin; audited under telephony.settings.update.

Route: /v1/telephony/settings (PUT).

Name	Type	Default	Required	Description
sip_domain	str		yes	SIP domain of the tenant, unique on the platform; Kamailio maps it to the tenant.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Set the telephony settings".

Raises: the typed errors of the transport (Errors).

TelephonyClient.queue

queue(queue_id: str) -> Any

Read a call queue. One call queue of the caller's tenant; 404 telephony_not_found otherwise. Secrets are never returned, only has_* flags. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/queues/{item_id} (GET).

Name	Type	Default	Required	Description
queue_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).

Returns: Any. Decoded JSON answer of the operation "Read a call queue".

Raises: the typed errors of the transport (Errors).

TelephonyClient.queue_members

queue_members(queue_id: str, limit: int | None = None, cursor: str | None = None) -> Any

List the members of a queue. Extensions and human agents of the queue with their penalty. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/queues/{queue_id}/members (GET).

Name	Type	Default	Required	Description
queue_id	str		yes	Identifier (UUID) of the queue.
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the members of a queue".

Raises: the typed errors of the transport (Errors).

TelephonyClient.queues

queues(limit: int | None = None, cursor: str | None = None) -> Any

List the call queues. The call queues of the caller's tenant, by identifier, limit per page (default 50, at most 500) with next_cursor for the next page. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/queues (GET).

Name	Type	Default	Required	Description
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the call queues".

Raises: the typed errors of the transport (Errors).

TelephonyClient.quotas

quotas() -> Any

Read the telephony quotas. Quotas and fraud limits of the tenant (defaults with configured: false when never set): concurrent calls and calls per second (pushed to Kamailio tenant_limits), monthly minutes, allowed countries, premium prefixes, maximum call duration (dialplan) and recording retention. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/quotas (GET).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "Read the telephony quotas".

Raises: the typed errors of the transport (Errors).

TelephonyClient.reconcile_pool

reconcile_pool(pool_id: str) -> Any

Reconcile the routing of a pool. Compares the Kamailio hash tables and the LiveKit SIP trunks and dispatch rules with the published version and fixes the differences (idempotent: nothing changes when they match). A Kamailio whose core.uptime went down restarted and gets every entry again (full_resync). 409 telephony_nothing_published before the first publication. Same roles as the publication; audited under telephony.config.reconcile.

Route: /v1/telephony/pbx-pools/{pool_id}/reconcile (POST).

Name	Type	Default	Required	Description
pool_id	str		yes	Identifier (UUID) of the PBX pool.

Returns: Any. Decoded JSON answer of the operation "Reconcile the routing of a pool".

Raises: the typed errors of the transport (Errors).

TelephonyClient.recording

recording(recording_id: str) -> Any

Read a recording. One recording of the index (same fields as the list). Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/recordings/{recording_id} (GET).

Name	Type	Default	Required	Description
recording_id	str		yes	Identifier (UUID) of the recording, in the caller's tenant (another tenant's recording answers 404).

Returns: Any. Decoded JSON answer of the operation "Read a recording".

Raises: the typed errors of the transport (Errors).

TelephonyClient.recordings

recordings(call_id: str | None = None, category: str | None = None, status: str | None = None, legal_hold: bool | None = None, limit: int | None = None, cursor: str | None = None) -> Any

List the recordings. Index of the telephony objects of the tenant in SeaweedFS, newest first. Each item: id, category, status (pending, stored, failed, deleted), source (asterisk, livekit, upload, export), content_type, size_bytes, sha256, duration_seconds, encryption (what the backend reported, and profile_mode), call_record_id, navin_call_id, retention_until, legal_hold, created_at, stored_at, deleted_at, last_error. The object key is never returned. Keyset pagination: limit (1 to 500, default 50) and the opaque cursor of next_cursor. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/recordings (GET).

Name	Type	Default	Required	Description
call_id	str | None	None	no	Only the recordings of this call record.
category	str | None	None	no	Only this category of the layout.
status	str | None	None	no	Only this status.
legal_hold	bool | None	None	no	Only the recordings with (true) or without (false) legal hold.
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the recordings".

Raises: the typed errors of the transport (Errors).

TelephonyClient.remove_queue_member

remove_queue_member(queue_id: str, member_id: str) -> Any

Remove a member from a queue. Removes the member (204). Needs tenant_admin or platform_admin; audited under telephony.queue_member.delete.

Route: /v1/telephony/queues/{queue_id}/members/{member_id} (DELETE).

Name	Type	Default	Required	Description
queue_id	str		yes	Identifier (UUID) of the queue.
member_id	str		yes	Identifier (UUID) of the queue member.

Returns: Any. Decoded JSON answer of the operation "Remove a member from a queue".

Raises: the typed errors of the transport (Errors).

TelephonyClient.rollback_pool

rollback_pool(pool_id: str, version: int, reason: str | None = None, idempotency_key: str | None = None) -> Any

Roll a pool back to a version. Publishes the files, tables and LiveKit objects of an earlier published or rolled_back version again as a new version (rollback_of), as a long operation like the publication (202). Once published, the later versions become rolled_back. 409 telephony_rollback_target for another status. Same roles as the publication; audited under telephony.config.rollback.

Route: /v1/telephony/pbx-pools/{pool_id}/rollback (POST).

Name	Type	Default	Required	Description
pool_id	str		yes	Identifier (UUID) of the PBX pool.
version	int		yes	Number of the version to publish again.
reason	str | None	None	no	Reason, kept with the version and in the audit.
idempotency_key	str | None	None	no	Idempotency-Key header: a retry with the same key replays the first answer.

Returns: Any. Decoded JSON answer of the operation "Roll a pool back to a version".

Raises: the typed errors of the transport (Errors).

TelephonyClient.routing_rule

routing_rule(rule_id: str) -> Any

Read a routing rule. One routing rule of the caller's tenant; 404 telephony_not_found otherwise. Secrets are never returned, only has_* flags. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/routing-rules/{item_id} (GET).

Name	Type	Default	Required	Description
rule_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).

Returns: Any. Decoded JSON answer of the operation "Read a routing rule".

Raises: the typed errors of the transport (Errors).

TelephonyClient.routing_rules

routing_rules(enabled: bool | None = None, direction: str | None = None, limit: int | None = None, cursor: str | None = None) -> Any

List the routing rules. The routing rules of the caller's tenant, by identifier, limit per page (default 50, at most 500) with next_cursor for the next page. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/routing-rules (GET).

Name	Type	Default	Required	Description
enabled	bool | None	None	no	Only the enabled (true) or disabled (false) objects. Default: both.
direction	str | None	None	no	Only the inbound or outbound rules. Default: both.
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the routing rules".

Raises: the typed errors of the transport (Errors).

TelephonyClient.runtime_settings

runtime_settings() -> Any

Read the runtime settings. Voicemail storage and fraud thresholds of the tenant (configured false and the defaults when never set). Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/runtime-settings (GET).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "Read the runtime settings".

Raises: the typed errors of the transport (Errors).

TelephonyClient.set_legal_hold

set_legal_hold(recording_id: str, legal_hold: bool, reason: str) -> Any

Set the legal hold of a recording. Places or releases the legal hold: a held recording is never deleted, neither by the API nor by the retention job. Needs tenant_admin or platform_admin. Audited under telephony.recording.legal_hold with the reason.

Route: /v1/telephony/recordings/{recording_id}/legal-hold (PUT).

Name	Type	Default	Required	Description
recording_id	str		yes	Identifier (UUID) of the recording, in the caller's tenant (another tenant's recording answers 404).
legal_hold	bool		yes	true: hold the recording; false: release it.
reason	str		yes	Reason kept in the audit trail (300 characters at most).

Returns: Any. Decoded JSON answer of the operation "Set the legal hold of a recording".

Raises: the typed errors of the transport (Errors).

TelephonyClient.settings

settings() -> Any

Read the telephony settings. Telephony settings of the caller's tenant: model, SIP domain, PBX pool, CDR retention, numbering plan, and tid, the short identifier the engines know the tenant by. configured: false when they were never set. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/settings (GET).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "Read the telephony settings".

Raises: the typed errors of the transport (Errors).

TelephonyClient.stats

stats(window_hours: int | None = None) -> Any

Read the live statistics. Dashboard figures of the tenant computed from the call tables: active_calls, active_by_state, active_by_branch, calls, answered, answer_rate, average_billsec, average_wait_seconds, calls_per_hour (hour, calls, answered, inbound, outbound), queues (queue, sla_seconds, offered, answered, abandoned, waiting, average_wait_seconds, max_wait_seconds, sla = share answered within the SLA of the queue, abandon_rate), agents (queue member states: queue, interface, extension, member_name, device_status, paused, paused_reason, in_call, calls_taken, updated_at), registrations (extension, status, contacts, updated_at), open_fraud_alerts, active_blocks, generated_at, window_hours. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/stats (GET).

Name	Type	Default	Required	Description
window_hours	int | None	None	no	Window of the figures in hours, 1 to 168 (default 24).

Returns: Any. Decoded JSON answer of the operation "Read the live statistics".

Raises: the typed errors of the transport (Errors).

TelephonyClient.sync_infrastructure_pool

sync_infrastructure_pool(cluster_id: str, service: str, **extra: Any) -> Any

Create or refresh a PBX pool from the Manager inventory. Creates (201) or refreshes (200) the PBX pool linked to an Asterisk instance of the Manager (manager_cluster, manager_service): nodes (host, AMI port, SIP address, Manager instance, ARI URL), ami_tls, Kamailio JSONRPC endpoints and addresses (the Kamailio instances bound to this Asterisk, or kamailio_service), livekit_binding (url, sip_host), AMI and ARI user names and the references of the secrets. A secret of the instance bound to navin-enterprise becomes env://EAI_CRED_TELEPHONY_AMI_SECRET, env://EAI_CRED_TELEPHONY_ARI_PASSWORD or env://EAI_CRED_TELEPHONY_EPHEMERAL_SECRET (variables rendered by the Manager in the sensitive environment file), a reference already on the pool is kept, never a value. Idempotent: the same inventory changes nothing (changed: []). Answers {created, changed, pool, secrets {ami, ari, ephemeral: bound, kept or missing}, sources {cluster_id, asterisk, kamailio, livekit, livekit_sip}, problems}. Errors: 404 telephony_inventory_not_found, 409 telephony_inventory_no_nodes, 422 telephony_inventory_too_large, the pool rules (422 telephony_pool_mode, 409 telephony_name_taken). Needs platform_admin; audited under telephony.pbx_pool.sync (plus telephony.pbx_pool.create or telephony.pbx_pool.update).

Route: /v1/telephony/infrastructure/pools (POST).

Name	Type	Default	Required	Description
cluster_id	str		yes	Identifier of the Manager cluster.
service	str		yes	Name of the Asterisk instance in the Manager (for example asterisk).
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Create or refresh a PBX pool from the Manager inventory".

Raises: the typed errors of the transport (Errors).

TelephonyClient.transfer_call

transfer_call(linkedid: str, target: str, uniqueid: str | None = None) -> Any

Transfer an active call. Transfers a channel of the call: AMI Redirect to {tid}-internal (extension of the tenant, 422 telephony_reference_invalid when it does not exist) or {tid}-outbound (E.164 number, the permissions and destination rules of the dialplan apply); for the AI branch, LiveKit TransferSIPParticipant (SIP REFER). ARI continue and redirect are not used: they only act on channels inside a Stasis application. Answers {linkedid, target, status, via, uniqueid}; 502 telephony_control_failed on a refusal. Needs tenant_admin or platform_admin. Audited under telephony.call.transfer.

Route: /v1/telephony/active-calls/{linkedid}/transfer (POST).

Name	Type	Default	Required	Description
linkedid	str		yes	Asterisk linkedid of the active call (linkedid of GET /v1/telephony/active-calls).
target	str		yes	Extension number of the tenant (2 to 8 digits) or E.164 number.
uniqueid	str | None	None	no	Channel to move (default: the first channel of the call).

Returns: Any. Decoded JSON answer of the operation "Transfer an active call".

Raises: the typed errors of the transport (Errors).

TelephonyClient.trunk

trunk(trunk_id: str) -> Any

Read a SIP trunk. One SIP trunk of the caller's tenant; 404 telephony_not_found otherwise. Secrets are never returned, only has_* flags. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/trunks/{item_id} (GET).

Name	Type	Default	Required	Description
trunk_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).

Returns: Any. Decoded JSON answer of the operation "Read a SIP trunk".

Raises: the typed errors of the transport (Errors).

TelephonyClient.trunks

trunks(enabled: bool | None = None, limit: int | None = None, cursor: str | None = None) -> Any

List the SIP trunks. The SIP trunks of the caller's tenant, by identifier, limit per page (default 50, at most 500) with next_cursor for the next page. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/trunks (GET).

Name	Type	Default	Required	Description
enabled	bool | None	None	no	Only the enabled (true) or disabled (false) objects. Default: both.
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the SIP trunks".

Raises: the typed errors of the transport (Errors).

TelephonyClient.update_agent

update_agent(agent_id: str, **changes: Any) -> Any

Change a human agent. Changes the sent fields only and returns the human agent; the same checks as the creation apply. A sent secret replaces the stored one (new vault version). The engines get the change at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.agent.update.

Route: /v1/telephony/agents/{item_id} (PATCH).

Name	Type	Default	Required	Description
agent_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).
**changes	Any		no	Fields of the human agent to change, sent as the PATCH body.

Returns: Any. Decoded JSON answer of the operation "Change a human agent".

Raises: the typed errors of the transport (Errors).

TelephonyClient.update_conference

update_conference(conference_id: str, **changes: Any) -> Any

Change a conference room. Changes the sent fields only and returns the conference room; the same checks as the creation apply. A sent secret replaces the stored one (new vault version). The engines get the change at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.conference.update.

Route: /v1/telephony/conferences/{item_id} (PATCH).

Name	Type	Default	Required	Description
conference_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).
**changes	Any		no	Fields of the conference room to change, sent as the PATCH body.

Returns: Any. Decoded JSON answer of the operation "Change a conference room".

Raises: the typed errors of the transport (Errors).

TelephonyClient.update_extension

update_extension(extension_id: str, **changes: Any) -> Any

Change an extension. Changes the sent fields only and returns the extension; the same checks as the creation apply. A sent secret replaces the stored one (new vault version). The engines get the change at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.extension.update.

Route: /v1/telephony/extensions/{item_id} (PATCH).

Name	Type	Default	Required	Description
extension_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).
**changes	Any		no	Fields of the extension to change, sent as the PATCH body.

Returns: Any. Decoded JSON answer of the operation "Change an extension".

Raises: the typed errors of the transport (Errors).

TelephonyClient.update_ivr_flow

update_ivr_flow(flow_id: str, **changes: Any) -> Any

Change an IVR flow. Changes the sent fields only and returns the IVR flow; the same checks as the creation apply. A sent secret replaces the stored one (new vault version). The engines get the change at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.ivr_flow.update.

Route: /v1/telephony/ivr-flows/{item_id} (PATCH).

Name	Type	Default	Required	Description
flow_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).
**changes	Any		no	Fields of the IVR flow to change (name, description), sent as the PATCH body.

Returns: Any. Decoded JSON answer of the operation "Change an IVR flow".

Raises: the typed errors of the transport (Errors).

TelephonyClient.update_number

update_number(number_id: str, **changes: Any) -> Any

Change a phone number. Changes the sent fields only and returns the phone number; the same checks as the creation apply. A sent secret replaces the stored one (new vault version). The engines get the change at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.number.update.

Route: /v1/telephony/numbers/{item_id} (PATCH).

Name	Type	Default	Required	Description
number_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).
**changes	Any		no	Fields of the phone number to change, sent as the PATCH body.

Returns: Any. Decoded JSON answer of the operation "Change a phone number".

Raises: the typed errors of the transport (Errors).

TelephonyClient.update_pool

update_pool(pool_id: str, **changes: Any) -> Any

Change a PBX pool. Changes the sent fields of the pool. Needs platform_admin; audited under telephony.pbx_pool.update.

Route: /v1/telephony/pbx-pools/{pool_id} (PATCH).

Name	Type	Default	Required	Description
pool_id	str		yes	Identifier (UUID) of the PBX pool.
**changes	Any		no	Fields of the PBX pool to change, sent as the PATCH body; secrets only as *_secret_ref references.

Returns: Any. Decoded JSON answer of the operation "Change a PBX pool".

Raises: the typed errors of the transport (Errors).

TelephonyClient.update_queue

update_queue(queue_id: str, **changes: Any) -> Any

Change a call queue. Changes the sent fields only and returns the call queue; the same checks as the creation apply. A sent secret replaces the stored one (new vault version). The engines get the change at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.queue.update.

Route: /v1/telephony/queues/{item_id} (PATCH).

Name	Type	Default	Required	Description
queue_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).
**changes	Any		no	Fields of the call queue to change, sent as the PATCH body.

Returns: Any. Decoded JSON answer of the operation "Change a call queue".

Raises: the typed errors of the transport (Errors).

TelephonyClient.update_queue_member

update_queue_member(queue_id: str, member_id: str, penalty: int) -> Any

Change the penalty of a queue member. Sets the penalty of the member (0 rings first). Needs tenant_admin or platform_admin; audited under telephony.queue_member.update.

Route: /v1/telephony/queues/{queue_id}/members/{member_id} (PATCH).

Name	Type	Default	Required	Description
queue_id	str		yes	Identifier (UUID) of the queue.
member_id	str		yes	Identifier (UUID) of the queue member.
penalty	int		yes	New penalty, 0 to 100.

Returns: Any. Decoded JSON answer of the operation "Change the penalty of a queue member".

Raises: the typed errors of the transport (Errors).

TelephonyClient.update_routing_rule

update_routing_rule(rule_id: str, **changes: Any) -> Any

Change a routing rule. Changes the sent fields only and returns the routing rule; the same checks as the creation apply. A sent secret replaces the stored one (new vault version). The engines get the change at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.routing_rule.update.

Route: /v1/telephony/routing-rules/{item_id} (PATCH).

Name	Type	Default	Required	Description
rule_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).
**changes	Any		no	Fields of the routing rule to change, sent as the PATCH body.

Returns: Any. Decoded JSON answer of the operation "Change a routing rule".

Raises: the typed errors of the transport (Errors).

TelephonyClient.update_trunk

update_trunk(trunk_id: str, **changes: Any) -> Any

Change a SIP trunk. Changes the sent fields only and returns the SIP trunk; the same checks as the creation apply. A sent secret replaces the stored one (new vault version). The engines get the change at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.trunk.update.

Route: /v1/telephony/trunks/{item_id} (PATCH).

Name	Type	Default	Required	Description
trunk_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).
**changes	Any		no	Fields of the SIP trunk to change, sent as the PATCH body.

Returns: Any. Decoded JSON answer of the operation "Change a SIP trunk".

Raises: the typed errors of the transport (Errors).

TelephonyClient.update_voice_agent

update_voice_agent(voice_agent_id: str, **changes: Any) -> Any

Change an AI voice agent. Changes the sent fields only and returns the AI voice agent; the same checks as the creation apply. A sent secret replaces the stored one (new vault version). The engines get the change at the next publication of the pool. Needs tenant_admin or platform_admin; audited under telephony.voice_agent.update.

Route: /v1/telephony/voice-agents/{item_id} (PATCH).

Name	Type	Default	Required	Description
voice_agent_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).
**changes	Any		no	Fields of the AI voice agent to change, sent as the PATCH body.

Returns: Any. Decoded JSON answer of the operation "Change an AI voice agent".

Raises: the typed errors of the transport (Errors).

TelephonyClient.upload_ivr_prompt

upload_ivr_prompt(name: str, audio: bytes, content_type: str = 'audio/wav') -> Any

Upload an IVR prompt. Raw body: a PCM WAV file (Content-Type: audio/wav, 415 telephony_prompt_type otherwise, 413 telephony_prompt_size above 10 MB, 422 telephony_prompt_invalid when it is not readable, 422 telephony_prompt_format when it is not 8000 Hz, 16 bit, mono, the only WAV the wav format of Asterisk reads). The file goes through the file security pipeline (422 file_blocked, 503 file_scan_unavailable), is stored in the category ivr-prompts (no expiry) and answers 201 with id, name, recording_id, content_type, size_bytes, sha256, duration_seconds, scan_id, created_at and playback_url, the signed URL an IVR plays. 409 telephony_name_taken when the name is used. Needs tenant_admin or platform_admin. Audited under telephony.ivr_prompt.create.

Route: /v1/telephony/ivr-prompts (POST).

Name	Type	Default	Required	Description
name	str		yes	Name of the prompt, unique in the tenant (lowercase letters, digits, -).
audio	bytes		yes	Raw bytes of the PCM WAV file (10 MB at most), sent as is as the request body.
content_type	str	'audio/wav'	no	Content type passed to the backend when the URL is signed (the type the upload is expected to send); 200 characters at most.

Returns: Any. Decoded JSON answer of the operation "Upload an IVR prompt".

Raises: the typed errors of the transport (Errors).

TelephonyClient.voice_agent

voice_agent(voice_agent_id: str) -> Any

Read an AI voice agent. One AI voice agent of the caller's tenant; 404 telephony_not_found otherwise. Secrets are never returned, only has_* flags. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/voice-agents/{item_id} (GET).

Name	Type	Default	Required	Description
voice_agent_id	str		yes	Identifier (UUID) of the object, in the caller's tenant (another tenant's object answers 404).

Returns: Any. Decoded JSON answer of the operation "Read an AI voice agent".

Raises: the typed errors of the transport (Errors).

TelephonyClient.voice_agents

voice_agents(enabled: bool | None = None, limit: int | None = None, cursor: str | None = None) -> Any

List the AI voice agents. The AI voice agents of the caller's tenant, by identifier, limit per page (default 50, at most 500) with next_cursor for the next page. Needs tenant_admin, support_engineer, auditor or platform_admin.

Route: /v1/telephony/voice-agents (GET).

Name	Type	Default	Required	Description
enabled	bool | None	None	no	Only the enabled (true) or disabled (false) objects. Default: both.
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the AI voice agents".

Raises: the typed errors of the transport (Errors).

TelephonyClient.voicemail

voicemail(mailbox: str | None = None, status: str | None = None, limit: int | None = None, cursor: str | None = None) -> Any

List the voicemail messages. Voicemail messages (status new or read) of the tenant, newest first: id, mailbox, extension_id, caller_number, caller_name, navin_call_id, recording_id, duration_seconds, status, read_at, received_at. A message appears once its audio is stored. Readers see every mailbox; a human agent (any role) sees the mailboxes of the extensions it is bound to, 403 for anyone else. Keyset pagination: limit (1 to 500, default 50) and the opaque cursor of next_cursor.

Route: /v1/telephony/voicemail (GET).

Name	Type	Default	Required	Description
mailbox	str | None	None	no	Only this mailbox (extension number).
status	str | None	None	no	Only the new or the read messages.
limit	int | None	None	no	Maximum number of items in one page. The server caps the value; read the next page with cursor.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page.

Returns: Any. Decoded JSON answer of the operation "List the voicemail messages".

Raises: the typed errors of the transport (Errors).

TelephonyClient.webrtc_credentials

webrtc_credentials(extension_id: str, ttl_seconds: int | None = None) -> Any

Get WebRTC credentials. Ephemeral SIP credentials of a WebRTC extension for the Kamailio auth_ephemeral module: username <expiry>:<endpoint>, password base64(HMAC-SHA1(shared secret, username)), expires_at (one hour at most), sip_uri sip:<endpoint>@<SIP domain> (the softphone registers and calls with its endpoint name as From and To user, the user Kamailio checks against the credentials), ws_url, realm, endpoint (<tid>-<extension>) and number (the extension number, for display). The SIP password of the extension never reaches the browser. Allowed for tenant_admin, platform_admin and the human agent bound to the extension (404 for anyone else). 409 telephony_not_webrtc or telephony_not_configured. Audited under telephony.webrtc.credentials.

Route: /v1/telephony/webrtc/credentials (POST).

Name	Type	Default	Required	Description
extension_id	str		yes	WebRTC extension of the tenant.
ttl_seconds	int | None	None	no	Lifetime of the credentials, 60 to 3600 seconds (default 3600).

Returns: Any. Decoded JSON answer of the operation "Get WebRTC credentials".

Raises: the typed errors of the transport (Errors).