Phone numbers

A phone number is one you already own at your carrier, imported onto a connected carrier account and provisioned so it can carry calls. Buy numbers in the carrier’s console; Talqing only imports them.

Import numbers

GET /v1/telephony/accounts/{account_id}/remote-numbers lists what the account owns at the carrier, read live (so it also proves the credential works). already_imported marks numbers Talqing already has. Then import the ones you want:

curl -sS https://api.talqing.com/v1/telephony/phone-numbers/import \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "telephony_account_id": "3f9a1c72-5d84-4e0b-9a13-6c2e8b7f4d51",
    "e164s": ["+14155550123", "+14155550124"]
  }'

const result = await talqing.telephony.phoneNumbers.import({
  importPhoneNumbersRequest: {
    telephony_account_id: "3f9a1c72-5d84-4e0b-9a13-6c2e8b7f4d51",
    e164s: ["+14155550123", "+14155550124"],
  },
});
for (const item of result.items) {
  if (!item.ok) console.error(item.e164, item.error);
}

result = talqing.telephony.phone_numbers.import_(
    telephony_account_id="3f9a1c72-5d84-4e0b-9a13-6c2e8b7f4d51",
    e164s=["+14155550123", "+14155550124"],
)
for item in result["items"]:
    if not item["ok"]:
        print(item["e164"], item["error"])

string

required

The carrier account that owns the numbers.

string[]

required

Numbers to import. Normalized to E.164 and de-duplicated.

string

us or in. Omit it and each number takes its own: in for +91, us for the rest. See region.

boolean

default:"true"

Provision each number as it is imported. false writes the rows only; provision them later.

Import is per number, not all-or-nothing. A 200 means the request was processed. Check ok on every entry of items: a failure carries error, and phone_number (in error status) when the row was written, so you can retry provisioning it.

`error`	Cause
`not found on this <carrier> account`	The carrier account does not own that number.
`already registered on this platform`	The number is already live on Talqing. Disable the existing row first.

If listing the carrier’s numbers fails, the whole request fails with could not list numbers from <carrier> — usually a dead credential.

Region

Every number is hosted in one region, us (United States) or in (India), and all its calls — inbound and outbound — run there. region is on every number.

+91 numbers must be in. Indian regulation requires their calls to terminate in India; us is refused with 422.
Every other number defaults to us; choose in if most of its callers are in India.
A region this deployment does not run is refused with 503. GET /v1/catalog lists the available ones under regions.

To move a number, PATCH /v1/telephony/phone-numbers/{number_id} with {"region": "in"}. On an active number the new region’s routing is built and the carrier re-pointed before the old routing is removed; a move that fails part-way returns 400 could not move … and the number keeps answering in its old region — send it again. The account must be ready.

Exotel: a number reaches a region through that region’s console Flow, which only you can change. After moving an Exotel number, attach it to the target region’s Flow in ExoPhones (and confirm that region’s step if it is new). See carrier accounts.

Assign an agent

POST /v1/telephony/phone-numbers/{number_id}/assign with agent_id makes the number answer inbound calls:

curl -sS https://api.talqing.com/v1/telephony/phone-numbers/8b41d0e6-2c77-4a19-b3f5-91ad6e40c8b2/assign \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704" }'

Refused unless all of these hold:

the number is active and can_inbound is true (Exotel: the region’s console step is confirmed);
the carrier account is ready;
the agent is published and its published version is a voice agent (video and text are refused);
the agent declares no variable that is required with no default — an inbound call has no request to supply it. See variables.

One agent per number; assigning again replaces it. Calls run the agent’s current published version, so republishing needs no reassignment. A publish or rollback that would make the agent non-voice, or add a required variable with no default, is refused while it answers a number. POST /v1/telephony/phone-numbers/{number_id}/unassign removes the agent. The number stays provisioned and can still dial out; readiness becomes needs_agent.

Readiness

readiness is the one field to show a person. It is computed on every read from status, can_inbound and the routing.

`readiness`	Meaning	What to do
`live`	Active, inbound-capable, agent assigned, routing in place.	Nothing.
`needs_agent`	Provisioned, nothing routed to answer. Also shown after the number’s carrier account is disabled.	Assign a published voice agent (or re-provision after re-enabling the account).
`needs_carrier_setup`	`can_inbound` is false. Outbound works.	Finish the Exotel console step for the number’s region, or set `can_inbound: true`.
`setting_up`	`status` is `pending` or `provisioning`.	Wait, or provision a `pending` number.
`error`	Provisioning failed; `status_message` says why.	Fix the cause, provision again.
`disabled`	Taken out of service.	Re-enable.

status is one of pending, provisioning, active, error, disabled.

Provisioning

POST /v1/telephony/phone-numbers/{number_id}/provision wires the number up at the carrier and in Talqing (pending → provisioning → active, or error with status_message). Import already does this; call it to retry an error number, finish one imported with provision: false, re-enable a disabled one, or restore routing after its carrier account was re-enabled. It provisions a connected account first; a disabled account is refused.

Per-number settings

PATCH /v1/telephony/phone-numbers/{number_id}:

Field	Meaning
`label`	Your name for the number.
`can_outbound`	Whether it may place outbound calls.
`can_inbound`	Whether it may take incoming calls. On Exotel the account’s console confirmation overwrites it per region.
`region`	`us` or `in`; moves the number. See region.
`status`	`disabled` or `pending` only. See below.

Disable and re-enable

{"status": "disabled"} takes a number out of service. Talqing unmaps it at the carrier, then removes its routing, then flips the row, so calls stop before the dashboard shows it off. The assigned agent (inbound_agent_id) is kept.

The carrier-side unmapping is best effort. If the carrier’s API refuses it, the number is still disabled here, but status_message says the carrier may still be routing it to Talqing and names the console to unmap it in. Read status_message after disabling.

Re-enabling takes two calls:

curl -sS -X PATCH https://api.talqing.com/v1/telephony/phone-numbers/8b41d0e6-2c77-4a19-b3f5-91ad6e40c8b2 \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "pending" }'

curl -sS -X POST https://api.talqing.com/v1/telephony/phone-numbers/8b41d0e6-2c77-4a19-b3f5-91ad6e40c8b2/provision \
  -H "Authorization: Bearer $TALQING_API_KEY"

Only a disabled, error or pending number accepts status: "pending" (otherwise 400). A 409 means another live row in your workspace already holds that E.164. Provisioning rebuilds the routing, including the kept agent.

Listing numbers

GET /v1/telephony/phone-numbers, optionally filtered by account_id; limit (default 200) and offset paginate. GET .../phone-numbers/{number_id} reads one.

Inbound calls

What the agent knows when the phone rings, and what is refused.

Outbound calls

Dial out of a number you have imported.

Get started

Build

Guides

Import numbers

Region

Assign an agent

Readiness

Provisioning

Per-number settings

Disable and re-enable

Listing numbers

Next

Inbound calls

Outbound calls

​Import numbers

​Region

​Assign an agent

​Readiness

​Provisioning

​Per-number settings

​Disable and re-enable

​Listing numbers

​Next

Inbound calls

Outbound calls

Import numbers

Region

Assign an agent

Readiness

Provisioning

Per-number settings

Disable and re-enable

Listing numbers

Next