Place a Voice call from the terminal

Prove the telephone connection before connecting your PBX or voice agent. The Bird CLI starts a local SIP client for one real call, then you inspect the resulting record.

1. Prepare the trunk and destination

Follow first-call setup to create an outbound-enabled trunk, verify a caller ID and enable the destination country. Confirm the workspace balance and the published destination rate. This test is billed like an ordinary call.

Install the Bird CLI and baresip using your operating system’s package manager. Give the terminal microphone access. Set BIRD_API_KEY, BIRD_TRUNK_ID, BIRD_CALLER_ID and VOICE_TO; the last two values are E.164 numbers with a leading +. Use a phone you control for the receiving test.

The trunk must permit your authentication method. An API key used as the SIP password must be explicitly allowed on the trunk. A session-credential trunk can mint a short-lived credential with voice:write; a plain CLI login does not supply that scope. Read the command’s authentication rules before choosing credentials.

2. Call and inspect the record

Exemple de code

bird voice tools test-call "$VOICE_TO" \
  --trunk "$BIRD_TRUNK_ID" \
  --caller-id "$BIRD_CALLER_ID" \
  --protocol tls \
  --duration 30s

bird voice list

Answer the receiving phone and speak in both directions. The command hangs up after 30 seconds. Its local client establishes the call over SIP. The first-call guide also covers number setup and inspecting the call. Use the returned call list to locate the test by its time and numbers.

The command’s --dry-run option does not dial, but it can still mint a session credential while resolving authentication. Do not treat it as a read-only preview of every action.

Use baresip directly

For a PBX-style account test without the CLI wrapper, add this line to your local baresip accounts file, replacing every placeholder:

Exemple de code

<sip:YOUR_VERIFIED_E164_CALLER_ID@YOUR_TRUNK_DOMAIN>;auth_user=bird;auth_pass=YOUR_API_KEY_SECRET;regint=0;outbound="sip:YOUR_TRUNK_DOMAIN:5060;transport=udp";audio_codecs=PCMU/8000/1

The caller ID is the account user; the digest authentication user is bird. regint=0 disables registration. This direct example uses an allowed API key and Bird's UDP port; protect the accounts file because it contains the key secret. The baresip account reference describes these settings.

Start baresip with that account, enter /dial YOUR_CONTROLLED_E164_DESTINATION, answer the receiving phone and verify audio in both directions. End the call with /hangup and inspect its Bird call record using the steps below. Use the client setup guide if an existing multi-account installation selects a different account.

3. Read calls from your application

Use the Voice API reference and call log guide for Node.js, Python, Go, PHP, CLI and cURL examples. Store the call ID beside the application session; use Voice events for ongoing observations.

4. Connect the actual runtime

Configure your SIP client, PBX or AI voice runtime with the tested trunk. Retaining an external agent runtime means its prompts, tools and conversation state remain there. Moving the telephone connection does not copy the agent.

Test	Evidence to retain
Two-way speech	Caller and receiving party can hear each other.
Rejected destination	The call record’s rejection reason matches the disabled route; no completed conversation is claimed.
Incoming call	The number routes to the intended trunk and runtime.
Agent handoff	The human destination answers and the application retains the customer context.
Ended call	The final call record, duration and application session agree.

Next steps

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Comprendre le conceptWhat is a voice API?Explorer la fonctionnalitéVoice Guide d'implémentationVoice overview

Obtenir un guide d'implémentation