# Bridge: full documentation

> Open-source, self-hosted SMS and phone verification. Send through Android phones you own,
> with delivery reports, signed webhooks, a Verify API for one-time passwords and fallback to
> MSG91, Twilio, Vonage or Plivo. This file concatenates the repository README, every guide
> under docs/ and the TypeScript SDK README. Each section starts with its path in the repository.

Source: https://github.com/kroszborg/bridge

---

# README.md

Source: https://github.com/kroszborg/bridge/blob/main/README.md

# Bridge

Open-source infrastructure for SMS and phone verification.

Connect Android devices or professional messaging providers through one developer API.

```text
Application
     │  POST /v1/messages
     ▼
  Bridge  ──  queue · retries · delivery status · logs
     │
     ▼
Android phone + SIM   or   MSG91 · Twilio · Vonage · Plivo
     │
     ▼
    SMS
```

Your application talks to one stable API. What delivers the message underneath (your own Android
phone, or a messaging provider as a fallback or instead) can change without rewriting your code.

> **Status: pre-release.** v0.4.0-rc.1 is released. Working in it: accounts, projects, API keys,
> the dashboard, Docker self-hosting, the Android gateway, sending SMS through paired phones with
> delivery tracking, forwarding of incoming SMS, signed webhooks with retries, the TypeScript SDK,
> the `bridgectl` CLI, usage charts, request logs, a playground, teams with roles and invite links,
> an audit log, a public status page, the Verify API for one-time passwords, SMS providers (MSG91,
> Twilio, Vonage, Plivo) with fallback routing, integrations such as the Supabase Send SMS hook, and
> an MCP server for AI assistants, and Verify Pro: Verify apps per project, delivery failover, fraud
> protection, and a drop-in widget and hosted page with signed tokens. In progress for 0.7, with the
> API, SDK and CLI done and the dashboard pages under way: broadcasts, scheduled messages, an
> opt-out list with keyword auto-replies, and forwarding rules for incoming SMS. Bridge has not yet been verified on enough
> real phones and provider accounts to call it stable. See the [Era 0 plan](https://github.com/kroszborg/bridge/blob/main/docs/architecture/era-0-plan.md) for exactly
> what works today. Do not run it in production yet.

## Run it

You need Docker with Compose.

```bash
git clone https://github.com/kroszborg/bridge.git
cd bridge
docker compose up -d
```

| Service | URL |
| --- | --- |
| Dashboard | http://localhost:3000 |
| API | http://localhost:8080 |
| API reference | http://localhost:8080/docs |
| Status page | http://localhost:3000/status |

This builds the images from source. To run a published release instead, set
`BRIDGE_IMAGE_PREFIX=ghcr.io/kroszborg/` and `BRIDGE_VERSION` in `.env` (see
[Releases](https://github.com/kroszborg/bridge/releases)).

Create an account in the dashboard. You get a workspace and a default project. Create an API key
under **API keys**, pair a phone under **Devices**, then send:

```bash
curl http://localhost:8080/v1/messages \
  -H "Authorization: Bearer $BRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+919876543210", "message": "Your order has shipped."}'
```

```json
{ "id": "msg_01ja8z3k5wq2v7c9e4r2n0w6yb", "status": "queued", "to": "+919876543210", "segments": 1, "...": "..." }
```

Follow it under **Messages**, or with `GET /v1/messages/{id}`, which includes the full delivery timeline.
To be told when it is delivered, or when a phone receives an SMS, add a webhook endpoint. See
[Sending messages](https://github.com/kroszborg/bridge/blob/main/docs/messages/README.md) and [Webhooks](https://github.com/kroszborg/bridge/blob/main/docs/webhooks/README.md). For login and
sign-up codes, use [Verify](https://github.com/kroszborg/bridge/blob/main/docs/otp/README.md): `POST /v1/otp`, then `POST /v1/otp/verify`, or
drop in the [verification widget](https://github.com/kroszborg/bridge/blob/main/docs/otp/README.md#drop-in-widget) and check its signed token.

Messaging tools (0.7):

* [Broadcasts](https://github.com/kroszborg/bridge/blob/main/docs/broadcasts/README.md): one template with `{name}` variables to up to 10,000
  numbers, with a dry run, a scheduled start, cancel, and pacing to what your phones can send.
* [Scheduled messages](https://github.com/kroszborg/bridge/blob/main/docs/schedules/README.md): once, daily, weekly or monthly at a local time
  in any time zone, with daylight saving handled.
* [Opt-outs and auto-replies](https://github.com/kroszborg/bridge/blob/main/docs/automation/README.md): `STOP`, `START` and `HELP` work out of
  the box; opted-out numbers are refused (`opted_out`) except for one-time passwords.
* [Forwarding rules](https://github.com/kroszborg/bridge/blob/main/docs/automation/README.md#forwarding-rules): copy incoming SMS to another
  phone, Telegram, Slack, Discord, a signed webhook or email.

**Use Bridge with** [Supabase Auth](https://github.com/kroszborg/bridge/blob/main/docs/integrations/supabase.md),
[Better Auth](https://github.com/kroszborg/bridge/blob/main/docs/integrations/better-auth.md), [Auth0](https://github.com/kroszborg/bridge/blob/main/docs/integrations/auth0.md),
[Firebase and Clerk](https://github.com/kroszborg/bridge/blob/main/docs/integrations/firebase-clerk.md), and
[n8n, Zapier or Make](https://github.com/kroszborg/bridge/blob/main/docs/integrations/no-code.md). No phone, or need a fallback? Add an
[SMS provider](https://github.com/kroszborg/bridge/blob/main/docs/providers/README.md).

From a terminal, use [`bridgectl`](https://github.com/kroszborg/bridge/blob/main/docs/cli/README.md): `bridgectl send +919876543210 "Hello" --wait`.
From TypeScript, use the [SDK](https://github.com/kroszborg/bridge/blob/main/packages/sdk/README.md):

```ts
const bridge = new Bridge({ apiKey: process.env.BRIDGE_API_KEY, baseUrl: 'http://localhost:8080' });
const msg = await bridge.messages.send({ to: '+919876543210', message: 'Your order has shipped.' });
```

To check a key without sending anything:

```bash
export BRIDGE_API_KEY="bk_test_…"
curl http://localhost:8080/v1/whoami -H "Authorization: Bearer $BRIDGE_API_KEY"
```

```json
{
  "project_id": "prj_01j9tq4m2xk3v8c7e5r2n0w6yb",
  "project_name": "Default",
  "organization_id": "org_01j9tq4m2xk3v8c7e5r2n0w6yb",
  "environment": "test",
  "api_key_id": "key_01j9tq4m2xk3v8c7e5r2n0w6yb",
  "api_key_name": "Local test"
}
```

`bk_test_` keys use the full API but never send a real SMS. `bk_live_` keys send through your paired devices
(or your SMS providers, if the project routes to them).

Configuration lives in environment variables; see [`.env.example`](https://github.com/kroszborg/bridge/blob/main/.env.example) and the
[self-hosting guide](https://github.com/kroszborg/bridge/blob/main/docs/self-hosting/README.md).

## What is inside

| Path | What |
| --- | --- |
| `apps/api` | Go API, background worker and migrations in one binary (`bridge serve`, `bridge worker`, `bridge migrate`) |
| `apps/dashboard` | Next.js dashboard, including the public status page |
| `apps/web` | Public website (static Next.js export) |
| `apps/api/cmd/bridgectl` | Command-line tool: send, broadcast from CSV, opt-outs, follow, tail events, forward webhooks locally, see [docs/cli](https://github.com/kroszborg/bridge/blob/main/docs/cli/README.md) |
| `packages/sdk` | TypeScript SDK (MIT, zero dependencies), see [its README](https://github.com/kroszborg/bridge/blob/main/packages/sdk/README.md) |
| `packages/api-types` | TypeScript types generated from the API's OpenAPI document |
| `examples` | [curl](https://github.com/kroszborg/bridge/blob/main/examples/curl/README.md) and [Node.js](https://github.com/kroszborg/bridge/blob/main/examples/node/README.md) examples |
| `android/gateway` | Android gateway app (Kotlin, `foss` and `gms` builds), see [docs/android](https://github.com/kroszborg/bridge/blob/main/docs/android/README.md) |
| `docs` | Guides ([messages](https://github.com/kroszborg/bridge/blob/main/docs/messages/README.md), [broadcasts](https://github.com/kroszborg/bridge/blob/main/docs/broadcasts/README.md), [schedules](https://github.com/kroszborg/bridge/blob/main/docs/schedules/README.md), [automation](https://github.com/kroszborg/bridge/blob/main/docs/automation/README.md), [Verify](https://github.com/kroszborg/bridge/blob/main/docs/otp/README.md), [providers](https://github.com/kroszborg/bridge/blob/main/docs/providers/README.md), [integrations](https://github.com/kroszborg/bridge/blob/main/docs/integrations/README.md)), architecture, security model, self-hosting, [releasing](https://github.com/kroszborg/bridge/blob/main/docs/releasing.md) |

The stack is deliberately boring: Go, PostgreSQL (data and job queue), Next.js. Self-hosting needs
one binary and one database.

## Roadmap

| Version | Scope |
| --- | --- |
| 0.1 | Android gateway: pair a phone, send SMS through its SIM, delivery status, message timeline |
| 0.2 | Inbound SMS, webhooks, TypeScript SDK |
| 0.3 | Developer platform: playground, CLI, usage, request logs, teams, audit log, status page |
| 0.4 | Verify API: `bridge.otp.send()` / `bridge.otp.verify()` with a zero-cost test mode (done, released as v0.4.0-rc.1; see [docs/otp](https://github.com/kroszborg/bridge/blob/main/docs/otp/README.md)) |
| 0.5 | [SMS providers](https://github.com/kroszborg/bridge/blob/main/docs/providers/README.md) (MSG91, Twilio, Vonage, Plivo) with fallback routing, and [integrations](https://github.com/kroszborg/bridge/blob/main/docs/integrations/README.md) (Supabase hook, Better Auth, Auth0, no-code tools) |
| 0.6 | Verify Pro: [Verify apps](https://github.com/kroszborg/bridge/blob/main/docs/otp/README.md#verify-apps) per project, delivery failover, fraud protection, drop-in widget and hosted page |
| 0.7 | Messaging tools: [broadcasts](https://github.com/kroszborg/bridge/blob/main/docs/broadcasts/README.md) and [scheduled sends](https://github.com/kroszborg/bridge/blob/main/docs/schedules/README.md), [auto-replies with opt-out, forwarding rules](https://github.com/kroszborg/bridge/blob/main/docs/automation/README.md) |

Bridge is not a marketing tool, and it does not help you bypass carrier rules, DLT registration or
provider policies. Broadcasts are for messages people expect from you, are paced to your phones'
send limits, and always honour opt-outs. Throughput is limited by your SIM and carrier, and Bridge
reports those limits rather than hiding them.

## Contributing

Read [CONTRIBUTING.md](https://github.com/kroszborg/bridge/blob/main/CONTRIBUTING.md) for local setup, tests and conventions. Report security
issues privately as described in [SECURITY.md](https://github.com/kroszborg/bridge/blob/main/SECURITY.md).

## License

The Bridge server, dashboard and Android app are licensed under [AGPL-3.0](https://github.com/kroszborg/bridge/blob/main/LICENSE). Client SDKs
are MIT-licensed so you can embed them anywhere.