Example Use Cases

Common workflows and patterns for voice, messaging, scripting, and BXML generation.

Set up a voice application

This walkthrough sets up Voice on the Universal Platform, which uses Voice Configuration Packages (or VCPs) to manage settings and routing functionality for groups of phone numbers.

# 1. Create a voice app
band app create --name "My voice app" --type voice \
  --callback-url https://your-server.example.com/callbacks

# 2. Create a VCP and link it to the app
band vcp create --name "My VCP" --app-id <app-id>

# 3. Search for and order a number
band number search --area-code 919 --quantity 1
band number order +19195551234 --wait

# 4. Assign the number to the VCP
band vcp assign <vcp-id> +19195551234

# 5. Place a call
band call create \
  --from +19195551234 \
  --to +15559876543 \
  --app-id <app-id> \
  --answer-url https://your-server.example.com/answer

Useful call commands:

band call list
band call get <call-id>
band call hangup <call-id>

Recordings and transcriptions:

band recording list
band recording download <recording-id> --output call.mp3
band transcription create <recording-id>
band transcription get <recording-id>

Set up a messaging application

# 1. Create a messaging app
band app create --name "My messaging app" --type messaging \
  --callback-url https://your-server.example.com/callbacks

# 2. Find your sub-account and location
band subaccount list
band location list --site <site-id>

# 3. Assign the app to the location
band app assign <app-id> --site <site-id> --location <location-id>

# 4. Send an SMS
band message send \
  --to +15551234567 \
  --from +15559876543 \
  --app-id <app-id> \
  --text "Hello from Bandwidth"

Send an MMS:

band message media upload image.png   # returns a media URL
band message send \
  --to +15551234567 \
  --from +15559876543 \
  --app-id <app-id> \
  --text "Here's your image" \
  --media <media-url>

Check message status:

band message get <message-id>
band message list

Generate BXML locally

The band bxml commands generate Bandwidth XML (BXML) without making any API calls. Use this to build and test callback server responses before wiring them up.

band bxml speak "Welcome to Bandwidth"

band bxml gather \
  --url https://your-server.example.com/gather \
  --max-digits 1 \
  --prompt "Press 1 for sales"

band bxml transfer +19195551234 --caller-id +19195550000

band bxml record

band bxml raw '<Response><SpeakSentence>Hello</SpeakSentence></Response>'

No auth required for any bxml command.

Automate with scripts and CI/CD

band is designed for automation. JSON is the default output, exit codes are structured, and async operations can block until complete.

Use environment variables for auth

export BW_CLIENT_ID=your-client-id
export BW_CLIENT_SECRET=your-client-secret
band auth login

Variable	Purpose
BW_CLIENT_ID	OAuth2 client ID
BW_CLIENT_SECRET	OAuth2 client secret
BW_ACCOUNT_ID	Override the active account
BW_ENVIRONMENT	prod or test
BW_FORMAT	Output format override
NO_COLOR=1	Disable terminal colors

Parse output with --plain

--plain outputs flat JSON — ideal for piping to jq or feeding to an agent. It's enabled automatically when stdout is piped.

band number list --plain | jq '.[] | .phoneNumber'

Create resources idempotently

--if-not-exists returns the existing resource if a name match is found, instead of erroring. Safe to run repeatedly.

band app create --name "My app" --type voice \
  --callback-url https://your-server.example.com/callbacks \
  --if-not-exists

Block on async operations

Number ordering and call setup are async by default. Use --wait to block until they complete.

band number order +19195551234 --wait --timeout 300

Use exit codes for control flow

Don't parse error strings — use exit codes.

Code	Meaning
0	Success
1	General error
2	Auth failure
3	Not found
4	Conflict
5	Timeout

Example: CI provisioning script

#!/bin/bash
set -e

export BW_CLIENT_ID=$BANDWIDTH_CLIENT_ID
export BW_CLIENT_SECRET=$BANDWIDTH_CLIENT_SECRET

band auth login

APP_ID=$(band app create \
  --name "ci-voice-app" \
  --type voice \
  --callback-url "$CALLBACK_URL" \
  --if-not-exists \
  --plain | jq -r '.id')

echo "App ID: $APP_ID"