Provide local numbers

Provision local numbers in any country through your own Twilio or Telnyx account.

What it unlocks

Provision local numbers in the countries you support, using your own telephony account.

• Provision new phone numbers into your own Twilio account instead of Kapso’s shared account
• Support multiple countries in the same project
• Keep reusable project-owned pools per country
• Import numbers you already own, including numbers your carrier sells only through a manual request
• Use project-owned pre-verified numbers for faster onboarding

Plans

• Enterprise: included
• Pro, Team, Platform: available as a $400/mo add-on on the existing project subscription
• Free and Legacy: visible in the UI, but cannot be enabled

How custom Twilio works

Enable the Custom telephony add-on in Billing. Enterprise projects already include it. Then open Multi-tenant → Telephony → Configuration and add your Twilio credentials.

Once the credentials are active, Kapso uses that Twilio account for number search, provisioning, and pool maintenance for that project.

You can configure:

• a default country
• multiple allowed countries
• per-country overrides for regulatory bundle and address data

API keys are optional. If present, Kapso uses them for Twilio API calls. The auth token is still required.

Custom Twilio changes phone ownership. These numbers belong to the project’s Twilio account, not Kapso’s shared pool.

Other telephony providers

Telephony → Configuration lets you store credentials per provider and pick the Preferred provider for search, provisioning, and pool maintenance. Each provider keeps its own secrets, allowed countries, and per-country configuration.

Configuring any provider here counts as custom telephony: setup links and embedded signup can then request non-US countries.

Telnyx is enabled per project by Kapso. If it is not available on your project, ask support to turn it on.

What to set

Required

• Account SID: the Twilio account Kapso should use for search and provisioning
• Auth token: required for webhook validation and for Twilio client auth when API keys are not used

These two fields are enough for the basic flow.

Optional

Open Advanced options to set:

• Subaccount SID: use a Twilio subaccount instead of the main account
• API key SID and API key secret: authenticate Twilio API calls with an API key pair instead of the auth token
• Default Bundle SID and Default Address SID: project-level regulatory values

Kapso still requires the auth token because Twilio webhook validation uses it.

Country configuration

• Allowed countries: the ISO country codes this project is allowed to provision in
• Country and regulatory configuration: per-country regulatory values used when Twilio requires them

Use Allowed countries to keep provisioning scoped to the countries you actually support.

Use a country configuration when a specific country needs different regulatory setup than your project default. The main Twilio fields are:

• Bundle SID
• Address SID

If a country configuration exists, Kapso uses it for that country. Otherwise it uses the project-level values, and if none are set it relies on the values passed in the provisioning flow.

Why these fields matter

• Account SID decides which Twilio account owns the number
• Allowed countries controls where setup links and embedded signup are allowed to provision
• Bundle SID and Address SID are how you satisfy country-specific Twilio compliance requirements
• pool settings decide whether onboarding can use a ready pre-verified number or has to fall back to live provisioning

How project pools work

Project pools work with Twilio and Telnyx. Manage them in Telephony → Pools.

Each project can keep multiple pools, with one pool per country and provider. A pool config includes:

• country
• enabled
• target pool size
• post disconnect behavior

What each pool setting does

• Country: which country this pool covers
• Enabled: whether Kapso maintains the pool and offers its ready numbers during onboarding. Kapso only uses numbers from enabled pools.
• Target pool size: how many ready project-owned numbers Kapso should keep available for that country. Kapso never buys more numbers for the pool than this target. Set it to 0 when you only import numbers yourself, so that Kapso does not buy numbers for this pool.
• Post disconnect behavior: what happens after a WhatsApp config is removed from a pool-managed number

Kapso maintains each enabled pool by provisioning numbers into the project’s telephony account and pre-verifying them for onboarding.

Import existing numbers

Import a number when you already own it, or when your carrier does not sell numbers in a country on demand. For example, Twilio sells numbers in Spain only through a manual request.

1. In Telephony → Pools, add a pool for the country of the number.
2. Set Target to 0, so that Kapso does not try to buy numbers for this country.
3. Turn on the pool and click Save.
4. In Import an existing number, select the pool country.
5. Enter the number in E.164 format, for example [phone].
6. Optional: enter the provider resource ID. For Twilio, this is the PN... SID of the number.
7. Click Import number.

For Twilio, the number must:

• be in the Twilio account that is configured in Kapso. If you set a Subaccount SID, the number must be in that subaccount.
• support voice calls, because Kapso verifies the number with a voice call
• not be connected to WhatsApp or used by another Kapso project

Do not import a number that another system still uses. For Twilio, import replaces the voice and SMS webhooks of the number. For Telnyx, import assigns the number to the TeXML connection that is configured in Kapso.

After the import, Kapso pre-verifies the number with Meta in the background. Follow the status in Telephony → Numbers.

If a pool is empty, onboarding falls back to live provisioning. In countries where your carrier sells numbers only through a manual request, live provisioning fails. Keep enough imported numbers in those pools.

Pre-verified project pools

When a pool has ready numbers for a country, Kapso can pass those pre-verified numbers into the onboarding flow and skip the normal OTP step.

This only works when the project has:

• custom telephony
• an enabled pool with ready numbers for the requested country
• Meta credentials that can pre-verify numbers

Projects that use Kapso’s Meta app meet the last requirement automatically.

Projects with their own Meta app

If the project uses its own Meta app as the default app for embedded signup, Kapso pre-verifies pool numbers in your Meta business portfolio, not in Kapso’s. Add these two values to that Meta app in Phone numbers → Meta apps:

• Business portfolio ID: the portfolio that owns the Meta app
• System access token: a token from a system user in that portfolio

See Add pool credentials to your Meta app for the steps.

Without these values, Kapso does not buy or import pool numbers for the project, and Telephony → Pools shows what is missing. Live provisioning through your telephony account still works.

Embedded signup does not need these values. Kapso uses them only to pre-verify pool numbers.

Embedded signup behavior

Kapso resolves the number path in this order:

1. Matching project pool with a ready pre-verified number
2. Live provisioning through the project’s telephony account
3. Standard Kapso behavior when custom telephony is not enabled

That means:

• if a matching pool exists, onboarding can skip OTP
• if no matching pool exists, onboarding still works
• pooled and non-pooled countries can coexist in the same project

Setup links behavior

Setup links use the same logic as embedded signup.

If a setup link requests a country that has a ready project pool, Kapso uses that project-owned pre-verified path.

If the setup link requests a country without a pool, or the pool is empty, the setup link still works. Kapso falls back to live search and provisioning for that country.

Disconnect behavior

Each pool has a default disconnect policy:

• mark_unavailable: keep the number on the project, but do not reuse it for WhatsApp again
• return_to_pool: keep the number on the project and make it reusable by that same project’s pool

In both cases, the number stays on the project’s telephony account. Kapso does not return it to the shared global pool.

Project-owned custom-Twilio numbers are not auto-released after 24h.

Typical setup

1. Enable the Custom telephony add-on in Billing, or use Enterprise
2. Add your carrier credentials in Telephony → Configuration
3. Add allowed countries
4. If the project uses its own Meta app, add the pool credentials to that app
5. Create one pool per country you want pre-verified capacity for
6. Set target size and disconnect behavior
7. If your carrier sells numbers in a country only through a manual request, import them
8. Use embedded signup or setup links normally

When to use it

Use this when you need Kapso to provision numbers through your telephony account for:

• local non-US numbers
• numbers billed directly to your telephony account
• project-owned reusable inventory
• numbers you bought through a manual carrier request
• instant onboarding from your own pre-verified pool

If you only need the default US instant-setup flow, use Instant setup.