Skip to main content

​
What it unlocks

  • Provision 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
  • 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

Configure this in Project settings → Custom Twilio. You add Twilio credentials at the project level. Once 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.

​
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 BYO Twilio flow.

​
Optional

  • API key SID
  • API key secret
Use these if you want Kapso to authenticate Twilio API calls with an API key pair instead of the auth token. 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 overrides: per-country regulatory values used when Twilio requires them
Use Allowed countries to keep provisioning scoped to the countries you actually support. Use country overrides when a specific country needs different regulatory setup than your project default. In v1, the main fields are:
  • Bundle SID
  • Address SID
If a country override 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 are Twilio-only in v1. Each project can keep multiple pools, with one pool per country. 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 should actively maintain the pool
  • Target pool size: how many ready project-owned numbers Kapso should keep available for that country
  • 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 Twilio account and pre-verifying them for onboarding.

​
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 uses:
  • custom Twilio
  • Kapso-managed Meta credentials
  • an enabled pool with ready numbers for the requested country
If the project uses custom Meta credentials, Kapso still uses the project’s Twilio account for live provisioning, but project-owned pre-verified pools are not available in v1.

​
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 Twilio account
  3. Standard Kapso behavior when custom Twilio 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 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 Twilio 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 Twilio 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 add-on, or use Enterprise
  2. Add custom Twilio credentials
  3. Add allowed countries
  4. Create one pool per country you want pre-verified capacity for
  5. Set target size and disconnect behavior
  6. Use embedded signup or setup links normally

​
When to use it

Use Bring your own Twilio when you need:
  • local non-US numbers
  • numbers billed directly to your Twilio account
  • project-owned reusable inventory
  • instant onboarding from your own pre-verified pool
If you only need the default US instant-setup flow, use Instant setup.