Phone numbers and carriers

Reception AI does not sell phone numbers. You bring your own carrier account, import a number into a workspace, and assign it to a receptionist. Carrier charges are billed to you by the carrier.

What each carrier can do#

This table is enforced in code: a call a line cannot make is refused with the reason, rather than attempted.

For a receptionist that answers and makes calls, use Twilio. Plivo is a good choice for answering only.

Test numbers (+14155550…) and test SIP addresses are fictional. They let you try the workspace and the Ring in simulator, and they never ring a real phone.

Before you connect a real number#

• Your install must be reachable at a public HTTPS address, with WebSocket upgrades passed through. See Installation.
• APP_URL must be that address. Webhook URLs, the audio stream URL and signature checks are all built from it.
• OPENAI_API_KEY must be set: live calls are answered by OpenAI Realtime.

For local testing, npm run tunnel gives you a temporary public address; see Quick start.

Importing a number#

Open Phone numbers in the workspace, choose the carrier and fill in:

Credentials are encrypted per number with CREDENTIAL_ENCRYPTION_KEY. Importing the same number again updates it. Each real number counts toward the workspace plan's number allowance (test numbers do not).

Automatic webhook setup#

With Point this number at Reception AI switched on (the default), the app configures the carrier for you:

• Twilio: sets the number's voice webhook to POST https://<APP_URL>/api/voice/inbound.
• Plivo: creates (or reuses) a Plivo application named ReceptionAI with the answer URL https://<APP_URL>/api/voice/plivo, and attaches the number to it.

Existing numbers can be re-pointed later from the same screen. Vonage, Telnyx and SIP are never configured automatically.

Webhooks, if you set them by hand#

The app answers with instructions that point the carrier at wss://<APP_URL>/api/voice/stream, the audio relay. That stream only opens with a signed token that expires after five minutes, issued by a webhook that passed its signature check.

Carrier-specific setup#

Twilio#

• Signatures are checked with the Auth Token stored on the number.
• With APP_URL set, inbound calls stream to the live relay and are answered by OpenAI Realtime.
• Without APP_URL, inbound calls fall back to the turn-based path described below.
• send_sms works from Twilio numbers that have SMS enabled.

Plivo#

Plivo needs three platform settings, all under Configuration:

SIP trunk (OpenAI SIP)#

With a SIP trunk, your carrier sends calls straight to OpenAI and OpenAI notifies Reception AI, which accepts the call and runs the conversation:

1. In the OpenAI dashboard, note your project ID and create a webhook for your project pointing to https://<APP_URL>/api/voice/realtime. Copy its signing secret (whsec_…).
2. In Configuration, set OPENAI_API_KEY, OPENAI_PROJECT_ID and OPENAI_WEBHOOK_SECRET.
3. Configure your trunk to send calls to sip:<your-project-id>@sip.api.openai.com;transport=tls, following OpenAI's SIP documentation.
4. Import the dialled number as a SIP trunk line and assign it to a receptionist. The dialled number must match the imported number.

The SIP URI, username and password stored at import are not used by this path. SIP calls do not speak the greeting first, always use the default Realtime model, and are not checked against the monthly minute allowance in 1.0.0.

Live calls and the turn-based path#

On the turn-based path, Reception AI voices are synthesised by xAI and OpenAI voices by OpenAI. If synthesis fails or takes longer than five seconds, Twilio's built-in voice reads the reply instead.

When a workspace runs out of minutes#

Inbound calls on Twilio and Plivo are checked before they are answered. A workspace over its monthly allowance hears: "This line has used all of its included minutes for the month. Please try again later, or reach the business another way." and the call ends. No minutes are spent.

In 1.0.0, SIP calls, outbound calls and campaigns are not checked against the allowance. See Selling it as SaaS.

Outbound calls and campaigns#

Outbound calling is on by default; FEATURE_OUTBOUND turns it off for the whole platform.

• Call someone on a receptionist's Phone setup places one call.
• Reach out (campaigns) calls a list of contacts.

Every outbound call:

• checks the platform switch, the receptionist's direction, the line's capability and the do-not-call list before dialling;
• uses the caller ID override if you set one, otherwise the line's own number;
• is recorded as failed (and not billed) if the carrier rejects it.

On Twilio, an outbound call runs on the turn-based path and opens with the receptionist's greeting. In 1.0.0 the outbound "First line" and the automated-caller disclosure are saved on the call record but not spoken, so put any disclosure you need in the greeting itself.

Campaign settings#

Campaigns pause on a line that cannot dial. Import contacts as CSV or XLSX with the columns Name, Phone, Email, Company, Notes, or paste phone,name,company lines (numbers without a country code are treated as +1).

How calls are metered#

Rates are adjustable; see Configuration.

Troubleshooting calls#

More in the FAQ.