FIfish
Phone Numbers

Update Phone Number

Changed on

Change the label and/or repoint the number at another agent — the deployment-pipeline move (rebind from the staging agent to the production one). Send agent_id: null to unbind; unbound numbers ring busy. The agent must live in the number's workspace. Rebinding is a routing-table update resolved on the next inbound call; nothing about the number itself is reprovisioned.

Managed twilio numbers also accept transfer_caller_id, which picks the number a transfer target sees (cold and warm alike), and retry_caller_id_sync to re-apply it after a failed synchronization. Read caller_id_sync_status on the response. Imported sip numbers return 409 for either field because their carrier owns the setting.

Every field here is a number setting, not agent config: changes apply from the next call without publishing, and publishing or rolling back the agent never changes them. Cold-transfer caller ID applies once caller_id_sync_status is synced.

patch/v1/agent/phone-numbers/{phone_number_id}

Request

  • Base URL
    https://api.fish.audio
  • URL
    https://api.fish.audio/v1/agent/phone-numbers/{phone_number_id}
  • Auth
    HTTP bearer

Path parameters

phone_number_idstring required

Request body

labelstring nullable
agent_idstring nullable

Agent that answers this number's inbound calls. Explicit null unbinds; omit the field to keep the current binding.

transfer_caller_id'agent_number' | 'original_caller' nullable

Managed twilio numbers only: the caller ID a transfer target sees, agent_number (this number) or original_caller (the caller's own number). Applies to cold and warm transfers. It is a number setting, not agent config: no publish is needed and agent rollbacks leave it alone. Warm transfers follow it from the next call, cold transfers once caller_id_sync_status is synced. The deprecated boolean cold_transfer_use_original_caller is still accepted in its place.

retry_caller_id_syncboolean

Re-apply the current caller ID policy after a failed synchronization.

Response

Request fulfilled, document follows

phone_number_idstring required
workspace_idstring required
phone_numberstring required

E.164, e.g. +14155550123.

provider'livekit' | 'twilio' | 'sip' | 'whatsapp' required
labelstring
agent_idstring nullable required

Inbound calls route to this agent; unbound numbers ring busy.

transfer_caller_id'agent_number' | 'original_caller' nullable

Managed twilio numbers: the caller ID a transfer target sees, on cold and warm transfers alike. agent_number shows this number, original_caller shows the caller's own number (a warm transfer falls back to this number when the caller withholds theirs). null for imported sip numbers, whose carrier decides.

cold_transfer_use_original_callerboolean nullable

Deprecated, read transfer_caller_id. True when it is original_caller.

cold_transfer_use_original_caller_effectiveboolean nullable

Deprecated, read caller_id_sync_status. Whether the carrier has confirmed the original caller policy for cold transfers, null while unknown.

caller_id_sync_status'synced' | 'pending' | 'error' | 'carrier_managed'

synced once the carrier confirmed the policy, pending while it is being applied, error when the last attempt failed (send retry_caller_id_sync), carrier_managed for imported sip numbers.

caller_id_sync_errorstring

Why the last synchronization failed; empty otherwise.

status'provisioning' | 'active' | 'error' | 'released' required
status_detailstring

What failed when status is error; empty otherwise.

supports_outboundboolean

Whether the number can place calls (outbound and warm-transfer consult legs): managed twilio always, imported sip only when a termination was configured.

termination_uristring nullable

Imported sip numbers: the customer trunk's termination host.

inbound_auth_usernamestring nullable

Imported sip numbers: the inbound digest username. Passwords are never echoed.

inbound_allowed_addressesstring[]

Imported sip numbers: allowed source IPs/CIDRs.

termination_transportstring nullable

Imported sip numbers: termination transport.

termination_auth_usernamestring nullable

Imported sip numbers: the termination digest username. Passwords are never echoed.

termination_headersobject

Imported sip numbers: custom SIP headers added to every outbound INVITE through the termination.

created_atstring date-time required
updated_atstring date-time required

Changes