Skip to main content
PUT
Update incoming calls
Read the current settings with Get incoming calls first, and send the full settings back with "confirm": true. MCP keys need numbers:write.

Modes per time slot

Business hours are the Contactability hours of the task where calls start. With no hours set, every call uses in_hours.

Set different modes by hours

  • Any slot other than ai_only needs team_number, with + and the country code. It cannot be the agent’s own number.
  • Set mode the way the dashboard does: ai_human with transfer_to equal to team_number when a slot is ai_first_team_when_asked, forward with transfer_to when both slots are team_only, and ai otherwise.
  • human_first_then_ai and team_only need a number that can ring an outside phone. Otherwise the response is 422 call_forwarding_provider_unsupported.
Without slots, mode applies at all times. off stops incoming calls and keeps the number assigned to the agent.

After saving

The response comes back with status: "pending". Calls pick up the change within a minute or two; read back until status is ready. A pending or error status is not active yet. Responses to these writes include saved_in_agent_draft. It is false when the change was applied to the live agent (every customer API key and MCP key). It is true only when NexorGPT saved the change to the agent’s draft; that change reaches calls when the draft is published. A 409 group_call_settings_number_in_use means another agent already receives calls on this number. Each number answers calls for one agent: remove it from the other agent first, or use another number.

Authorizations

X-API-Key
string
header
required

API key for authentication. Keys are prefixed with nxr_live_.

Path Parameters

id
string<uuid>
required

Agent ID (master_workflow in the API). A malformed ID returns 400 invalid_group_id.

Body

application/json

Any other key returns 400 group_call_settings_invalid.

mode
enum<string>
required

off stops incoming calls and keeps the number assigned. ai: the AI answers. ai_human: the AI answers and transfers to transfer_to on request. forward: calls go to transfer_to without the AI. With slots, use ai_human when a slot is ai_first_team_when_asked, forward when both slots are team_only, and ai otherwise.

Available options:
off,
ai,
ai_human,
forward
number_id
string<uuid>
required

The agent's number, from numbers in the GET response.

confirm
enum<boolean>
required

Must be true.

Available options:
true
transfer_to
string | null

Required for ai_human and forward, not allowed for off and ai. When team_number is also sent, it must be the same number.

Pattern: ^\+[1-9]\d{7,14}$
slots
object | null

Who answers during business hours and after hours. Business hours are the Contactability hours of the task where calls start; with no hours set, every call uses in_hours. ai_only: the AI answers and does not transfer when asked for a person. ai_first_team_when_asked: the AI answers and transfers to team_number when the caller asks for a person. human_first_then_ai: team_number rings first, and the AI answers after rings rings if nobody takes the call. team_only: calls go to team_number without the AI.

team_number
string | null

Your team's number, with + and the country code. Required when a slot is not ai_only. It cannot be the agent's own number.

Pattern: ^\+[1-9]\d{7,14}$
rings
integer | null

Rings before the AI answers in human_first_then_ai, from 1 to 6. Default 4. Only with slots.

Required range: 1 <= x <= 6

Response

Saved settings. status is pending until calls use them.

agent_group_id
string<uuid>
required

Agent ID.

mode
enum<string>
required

Single incoming-call mode. When slots is set, slots decides who answers each call.

Available options:
off,
ai,
ai_human,
forward
number_id
string<uuid> | null
required

The agent's number that receives the calls.

transfer_to
string | null
required

Destination for ai_human or forward; otherwise null.

Pattern: ^\+[1-9]\d{7,14}$
status
enum<string>
required

ready when calls already use these settings. pending while the change is being applied, usually a minute or two. Never treat pending or error as active.

Available options:
ready,
pending,
error,
unconfigured
numbers
object[]
required

Numbers of the account that this agent can use.

linked_numbers
object[]
required

Other numbers whose calls follow these settings.

slots
object | null
required

Who answers during business hours and after hours. Business hours are the Contactability hours of the task where calls start; with no hours set, every call uses in_hours. ai_only: the AI answers and does not transfer when asked for a person. ai_first_team_when_asked: the AI answers and transfers to team_number when the caller asks for a person. human_first_then_ai: team_number rings first, and the AI answers after rings rings if nobody takes the call. team_only: calls go to team_number without the AI. null when incoming calls are off.

team_number
string | null
required

Your team's number, shared by both slots.

Pattern: ^\+[1-9]\d{7,14}$
rings
integer | null
required

Rings before the AI answers in human_first_then_ai. null means the default of 4. Each ring lasts about 6 seconds.

Required range: 1 <= x <= 6
saved_in_agent_draft
boolean
required

false when the change was applied to the live agent (every customer API key and MCP key). true only when NexorGPT saved the change to the agent's draft; that change reaches calls when the draft is published.

Last modified on October 26, 2026