Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,7 @@ This is stderr only — it won't break piped output parsing.
| `BW_CLIENT_SECRET` | OAuth2 client secret |
| `OPENAI_API_KEY` | OpenAI API key for the `live-assistant` sample |
| `TRANSFER_TO` | Transfer destination (E.164) for the `live-assistant` sample |
| `USER_NUMBER` | Destination number (E.164) for the `voice-bridge` sample |
| `BW_ACCOUNT_ID` | Override active account |
| `BW_ENVIRONMENT` | API environment: `prod` (default), `test` |
| `BW_API_URL` | Override API base URL (overrides environment-based default) |
Expand Down Expand Up @@ -376,7 +377,8 @@ For full flag/argument reference, use `band <command> --help`. This section cove

- **`band sample run` is helpful for demoing what a developer can accomplish with Bandwidth.** It clones a repo, starts a local process, launches ngrok, and blocks for the lifetime of the app. If you need to deploy a sample for a user, use the step-by-step [Agent Workflows](#agent-workflows) for the underlying provisioning.
- **`band sample list` is safe for discovery.** Run it to enumerate available samples and supported languages before telling a user which command to run.
- **Credentials are auto-wired.** `band sample run` reads the active band profile and writes `BW_ACCOUNT_ID`, `BW_CLIENT_ID`, and `BW_CLIENT_SECRET` to a `.env` file in the clone directory — the user never needs to copy credentials manually. Sample-specific configuration (like `OPENAI_API_KEY` and `TRANSFER_TO` for the `live-assistant` sample) is read from the environment and must be exported before running. There are no flags for these — run the sample without them and the error names each one.
- **Credentials are auto-wired.** `band sample run` reads the active band profile and wires `BW_ACCOUNT_ID`, `BW_CLIENT_ID`, and `BW_CLIENT_SECRET` into the sample (via a `.env` file and process environment). Sample-specific configuration (like `OPENAI_API_KEY`, `TRANSFER_TO`, and `USER_NUMBER`) is read from the environment and must be exported before running. There are no flags for these — run the sample without them and the error names each one.
- **Python samples require Python 3.11+.** The pinned dependencies in the sample repos require it; the CLI fails fast with a clear message if you run a Python sample on an older interpreter.
- **The `live-assistant` sample is the primary voice AI demo.** It pairs Bandwidth's PSTN infrastructure (dialing, audio streaming, webhook routing) with the OpenAI Realtime API. The command to give a user:

```bash
Expand All @@ -390,7 +392,10 @@ For full flag/argument reference, use `band <command> --help`. This section cove

Prerequisites the user needs: ngrok (`brew install ngrok/ngrok/ngrok`), Python 3.11+, and an OpenAI API key with Realtime API access. A Bandwidth Build trial account is sufficient — no full account required.

- **Voice application and phone number are resolved automatically.** `band sample run` calls `band app list` internally and creates (or reuses) a voice application named `band-sample-<name>`. It picks the first in-service phone number on the account. No manual provisioning needed before running the sample.
- **Voice application and phone number are resolved automatically.** `band sample run` creates (or reuses) a voice application named `band-sample-<name>` and updates its callback URLs for the current ngrok tunnel.

- For **inbound-only** samples (e.g. `voice-record`), Build credentials may not be permitted to change location-level routing via the Dashboard API. In that case the CLI temporarily updates the inbound app that the number already routes to (falling back to an app named `default-http-voice` when it can't be resolved), and restores the original callback URLs on exit.
- For other samples, the CLI best-effort assigns the sample app to the number's location so inbound calls reach the sample callbacks when the account permits it.

---

Expand Down
16 changes: 9 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,15 @@ make test # run tests
make lint # run golangci-lint
```

Requires Go 1.27.3+ and [golangci-lint](https://golangci-lint.run/welcome/install/).

Go 1.27.3 includes the `crypto/x509` fix rejecting the compromised eMudhra
intermediate certificates. CI and release builds select the toolchain from
`go.mod`; keep the Docker builder's version aligned with that minimum. Existing
CLI binaries and container images must be rebuilt to pick up the fix; updating
the host's Go installation does not patch an already compiled binary.
Requires Go 1.27.4+ and [golangci-lint](https://golangci-lint.run/welcome/install/).

Go 1.27.4 includes the `crypto/x509` fix rejecting the compromised eMudhra
intermediate certificates (introduced in 1.27.3), and also includes fixes for
newer standard-library vulnerabilities flagged by `govulncheck`. CI and release
builds select the toolchain from `go.mod`; keep the Docker builder's version
aligned with that minimum. Existing CLI binaries and container images must be
rebuilt to pick up fixes; updating the host's Go installation does not patch an
already compiled binary.

## What happens when you open a PR

Expand Down
2 changes: 1 addition & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
FROM golang:1.27.3-alpine AS builder
FROM golang:1.27.4-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
Expand Down
13 changes: 12 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -623,6 +623,7 @@ All five share the same filters: `--to`/`--from` (comma-separated E.164), `--dir
| `BW_MESSAGING_URL` | Override the Messaging API base URL. Messaging is production-only (no test host), so `--environment`/`BW_ENVIRONMENT` does not change it; use this for local proxies or the internal lab. |
| `OPENAI_API_KEY` | OpenAI API key for the `live-assistant` sample (`band sample run`) |
| `TRANSFER_TO` | Transfer destination in E.164 for the `live-assistant` sample (`band sample run`) |
| `USER_NUMBER` | Destination number for the `voice-bridge` sample (`band sample run`) |

---

Expand Down Expand Up @@ -708,9 +709,19 @@ Want to see Bandwidth in action without writing any boilerplate? The CLI ships w
```sh
band sample list # see what's available
OPENAI_API_KEY=sk-... TRANSFER_TO=+19195550100 band sample run live-assistant --language python
band sample run voice-gather --language python --call-to +19195550101
band sample run voice-record --language python
USER_NUMBER=+19195550100 band sample run voice-bridge --language python
band sample run voice-redirect-loop --language python
```

`band sample run` handles everything: clones the GitHub repo, creates a virtual environment, installs dependencies, starts an ngrok tunnel, wires your Bandwidth credentials into a `.env` file, creates or reuses a voice application, and launches the app. Pass `--call-to` and it dials a number automatically once the app is healthy.
`band sample run` handles everything: clones the GitHub repo, creates a Python virtual environment (for Python samples), installs dependencies, starts an ngrok tunnel, wires your Bandwidth credentials into a `.env` file, creates or reuses a voice application, and launches the app.

**Python samples require Python 3.11+.** The pinned dependencies in the sample repos require it; the CLI fails fast with a clear message if you run a Python sample on an older interpreter.

Pass `--call-to` to automatically dial a number once the app is healthy. This is only supported by samples that implement outbound call flows (for example, `voice-gather` and `live-assistant`). Inbound-only samples (for example, `voice-record`) should be tested by calling your Bandwidth number after the app starts.

**Bandwidth Build accounts:** inbound-only samples temporarily update your account's default inbound voice application (`default-http-voice`) to point at the ngrok URL for this run, then restore it when the sample exits. This makes inbound testing work out of the box even when the account doesn't permit location-level routing changes via API.

Samples that need their own configuration read it from the environment, the same way `BW_CLIENT_ID` and `BW_CLIENT_SECRET` do. Run a sample without them and the CLI tells you which variables it expects.

Expand Down
152 changes: 149 additions & 3 deletions cmd/sample/catalog.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,22 @@ type langSetup struct {
RunCmd []string
// HealthPath is the HTTP path polled to detect a ready server.
HealthPath string
// MinPython is the minimum required Python version for python variants,
// in major.minor form (e.g. "3.11"). Empty means "no minimum enforced".
MinPython string
}

// voiceConfig describes how to wire a sample app up for Programmable Voice callbacks.
type voiceConfig struct {
// InitiateCallbackPath is appended to the ngrok base URL and used as the voice
// application's CallInitiatedCallbackUrl.
InitiateCallbackPath string
// StatusCallbackPath is appended to the ngrok base URL and used as the voice
// application's CallStatusCallbackUrl. When empty, InitiateCallbackPath is used.
StatusCallbackPath string
// DialAnswerPath is appended to the ngrok base URL and used as the answer URL
// when `band sample run --call-to` auto-initiates an outbound call.
DialAnswerPath string
}

// SampleEntry describes one sample app and its variants.
Expand All @@ -28,6 +44,8 @@ type SampleEntry struct {
ExtraEnv []envPrompt
// Setup maps language name → build/run instructions.
Setup map[string]langSetup
// Voice is non-nil when the sample expects Programmable Voice callbacks.
Voice *voiceConfig
// Port is the default local port the app listens on.
Port int
}
Expand All @@ -47,24 +65,152 @@ var catalog = map[string]*SampleEntry{
"python": {
AppDir: "app",
InstallCmd: []string{".venv/bin/pip", "install", "-q", "-r", "app/requirements.txt"},
RunCmd: []string{".venv/bin/python3", "main.py"},
RunCmd: []string{".venv/bin/python", "main.py"},
HealthPath: "/health",
MinPython: "3.11",
},
},
Voice: &voiceConfig{
InitiateCallbackPath: "/webhooks/bandwidth/voice/initiate",
StatusCallbackPath: "/webhooks/bandwidth/voice/status",
DialAnswerPath: "/webhooks/bandwidth/voice/initiate",
},
Port: 3000,
},
"voice-gather": {
Description: "In-call DTMF gather example",
Repos: map[string]string{
"python": "https://github.com/Bandwidth-Samples/in-call-gather-python",
"python": "https://github.com/Bandwidth-Samples/voice-gather-python",
"node": "https://github.com/Bandwidth-Samples/voice-gather-js",
"java": "https://github.com/Bandwidth-Samples/voice-gather-java",
},
Setup: map[string]langSetup{
"python": {
AppDir: ".",
InstallCmd: []string{".venv/bin/pip", "install", "-q", "-r", "requirements.txt"},
RunCmd: []string{".venv/bin/python", "main.py"},
HealthPath: "/",
MinPython: "3.11",
},
"node": {
AppDir: ".",
InstallCmd: []string{"npm", "i"},
RunCmd: []string{"npm", "start"},
HealthPath: "/",
},
"java": {
AppDir: ".",
InstallCmd: []string{"mvn", "package", "-q"},
RunCmd: []string{"mvn", "spring-boot:run"},
HealthPath: "/",
},
},
Voice: &voiceConfig{
InitiateCallbackPath: "/callbacks/outbound/voice",
DialAnswerPath: "/callbacks/outbound/voice",
},
Port: 3000,
},
"voice-record": {
Description: "Record a message from a call (voicemail-style)",
Repos: map[string]string{
"python": "https://github.com/Bandwidth-Samples/voice-record-python",
"node": "https://github.com/Bandwidth-Samples/voice-record-js",
"java": "https://github.com/Bandwidth-Samples/voice-record-java",
},
Setup: map[string]langSetup{
"python": {
AppDir: ".",
InstallCmd: []string{".venv/bin/pip", "install", "-q", "-r", "requirements.txt"},
RunCmd: []string{".venv/bin/python", "main.py"},
HealthPath: "/",
MinPython: "3.11",
},
"node": {
AppDir: ".",
InstallCmd: []string{"npm", "i"},
RunCmd: []string{"npm", "start"},
HealthPath: "/",
},
"java": {
AppDir: ".",
InstallCmd: []string{"mvn", "package", "-q"},
RunCmd: []string{"mvn", "spring-boot:run"},
HealthPath: "/",
},
},
Voice: &voiceConfig{
InitiateCallbackPath: "/callbacks/inbound/voice",
},
Port: 3000,
},
"voice-bridge": {
Description: "Mask a call by bridging the caller to a configured destination number",
Repos: map[string]string{
"python": "https://github.com/Bandwidth-Samples/voice-bridge-python",
"node": "https://github.com/Bandwidth-Samples/voice-bridge-js",
"java": "https://github.com/Bandwidth-Samples/voice-bridge-java",
},
ExtraEnv: []envPrompt{
{Key: "USER_NUMBER", Description: "Phone number to bridge calls to (E.164, e.g. +19195550100)"},
},
Setup: map[string]langSetup{
"python": {
AppDir: ".",
InstallCmd: []string{".venv/bin/pip", "install", "-q", "-r", "requirements.txt"},
RunCmd: []string{".venv/bin/python3", "app.py"},
RunCmd: []string{".venv/bin/python", "main.py"},
HealthPath: "/",
MinPython: "3.11",
},
"node": {
AppDir: ".",
InstallCmd: []string{"npm", "i"},
RunCmd: []string{"npm", "start"},
HealthPath: "/",
},
"java": {
AppDir: ".",
InstallCmd: []string{"mvn", "package", "-q"},
RunCmd: []string{"mvn", "spring-boot:run"},
HealthPath: "/",
},
},
Voice: &voiceConfig{
InitiateCallbackPath: "/callbacks/inbound/voice",
},
Port: 3000,
},
"voice-redirect-loop": {
Description: "Indefinitely redirect a call until interrupted (demo of Redirect and UpdateCall)",
Repos: map[string]string{
"python": "https://github.com/Bandwidth-Samples/voice-redirect-loop-python",
"node": "https://github.com/Bandwidth-Samples/voice-redirect-loop-js",
"java": "https://github.com/Bandwidth-Samples/voice-redirect-loop-java",
},
Setup: map[string]langSetup{
"python": {
AppDir: ".",
InstallCmd: []string{".venv/bin/pip", "install", "-q", "-r", "requirements.txt"},
RunCmd: []string{".venv/bin/python", "main.py"},
HealthPath: "/",
MinPython: "3.11",
},
"node": {
AppDir: ".",
InstallCmd: []string{"npm", "i"},
RunCmd: []string{"npm", "start"},
HealthPath: "/",
},
"java": {
AppDir: ".",
InstallCmd: []string{"mvn", "package", "-q"},
RunCmd: []string{"mvn", "spring-boot:run"},
HealthPath: "/",
},
},
Voice: &voiceConfig{
InitiateCallbackPath: "/callbacks/inbound/voice",
StatusCallbackPath: "/callbacks/inbound/voice/disconnect",
},
Port: 3000,
},
Expand Down
Loading
Loading