Phone numbers

Every outbound call needs a number to call from. You have two options: use a number from the Agoralia pool (auto-assigned per destination country), or bring your own (BYO) from Telnyx, Twilio, Vonage, Sinch, Bird, Infobip, Bandwidth, or SIP.

Pool numbers (auto-assign)

When a campaign has no phone_number_id, the launch pre-flight picks the best pool number for the destination countries of your contacts — preferring a number whose country matches the most leads, then falling back to any active pool number. You do not have to manage this: just leave the campaign's number unset and the system assigns one at launch.

For single calls (POST /calls), phone_number_id is required — there is no auto-assign on a one-off call. Pick one from list_numbers / GET /phone-numbers.

Bring your own (BYO)

Link a number you already own from Telnyx, Twilio, Vonage, Sinch, Bird, Infobip, Bandwidth, or SIP. Agoralia validates it on the provider and registers it with the voice layer. For every provider except SIP, connect the carrier's API credentials first (see Connect a carrier).

curl -X POST https://api.agoralia.app/api/v1/phone-numbers/link \
  -H "X-API-Key: ag_..." \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+14155550123",
    "provider": "twilio",
    "country_code": "US"
  }'

The response includes the new number's id — use that as phone_number_id when placing calls or assigning it to a campaign. Linked (BYO) numbers have pool: false; pool numbers have pool: true. bandwidth is US/Canada only.

Connect a carrier (BYO credentials)

Before linking a number from Telnyx, Twilio, Vonage, Sinch, Bird, Infobip, or Bandwidth, connect that carrier's API credentials once. They are verified against the provider and stored encrypted. SIP needs no credentials.

curl -X POST https://api.agoralia.app/api/v1/integrations/connect \
  -H "X-API-Key: ag_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "twilio",
    "credentials": { "account_sid": "AC...", "auth_token": "..." }
  }'

Required credential fields per provider:

The response includes sms_ready and sms_missing so you can tell whether the connected credentials are enough to also send SMS — see Messaging.

List & inspect

curl https://api.agoralia.app/api/v1/phone-numbers \
  -H "X-API-Key: ag_..."

list_numbers()

Each number returns id, number, country_code, provider, pool, is_active, and the voice-provider registration id.

Inbound

A number can also answer inbound calls — route them to a default agent and/or an external assistant-request server with PUT /phone-numbers/{id}/inbound. The HMAC signing secret is returned once, on first set or rotation.

Next

• Agents — what does the talking.
• Single call · Campaigns