Phone numbers

Your phone numbers are added in the console, on the Telephony page, where each is connected to your carrier. Through the API you can list them and choose which agent each one belongs to.

List them

#!/bin/sh
# List phone numbers
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/phone-numbers" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

This needs phone_numbers:read. Each number says which way it carries calls, whether it is in service, and the agent it belongs to. can_receive_calls and can_place_calls say whether it works right now: a number still waiting to be verified, or switched off, cannot. Use a number that can place calls as phone_number_id when you place a call.

Point a number at an agent

#!/bin/sh
# Point a number at an agent. With a live key: a phone number is real.
curl -sS --fail-with-body -X PATCH "https://api.aigently.ai/v1/phone-numbers/7a9c1e3f-5b7d-4f9a-8c2e-4d6f8a0c2e4a" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY" \
  --json '{
  "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f"
}'

This needs phone_numbers:write, a permission no starting point in the console includes, and a live key: a phone number is real, so a test key is refused with 403 live_key_required.

• A number that only receives calls rings its agent, so the agent must be an inbound agent that answers phone calls.
• A number that only places calls is the caller ID of an outbound agent.
• A number that does both can belong to either. An inbound agent answers it; an outbound agent calls from it, and calls back to it go where that agent's When somebody calls back setting says.
• The agent must be in the number's project.

A mismatch is refused with 409 number_agent_mismatch, and detail says what to change. Send "agent_id": null to leave the number with no agent. The change takes effect on the next call; a call already in progress is not affected.

If the number's previous agent made calls from it, that agent keeps calling from it: only the owner changes. Each change is recorded in your organization's audit log under the key.

What a key sees

A key limited to some projects lists their numbers alone. A key limited to some agents lists the numbers those agents own or call from, and moves a number only between those agents.