Bridge documentation

Bridge is open-source infrastructure for SMS and phone verification. Your application calls one API; Bridge sends the message through an Android phone you own, or through an SMS provider (MSG91, Twilio, Vonage or Plivo), and follows it to the carrier's delivery report.

Your application -- POST /v1/messages --> Bridge --> Android phone + SIM --> SMS
                                            |
                                            +--> or MSG91 / Twilio / Vonage / Plivo

Every message gets a timeline (queued, sending, sent, delivered or failed), retries, and signed webhooks for delivery reports and incoming SMS. On top of that sit Verify for one-time passwords, broadcasts, scheduled messages, and opt-outs, auto-replies and forwarding.

This documentation covers Bridge 1.0, the first stable release, both hosted and self-hosted. The changelog lists what each release contains.

Hosted or self-hostedCopy Anchor Link

Both run the same code and expose the same API.

Quick startCopy Anchor Link

1. Get an API key. In the dashboard, open API keys and create one. A bk_test_ key uses the full API but never sends a real SMS, so you can build against it first; a bk_live_ key sends.
2. Pair a phone. Install the Android app, open Phones → Pair device in the dashboard and scan the code with the app, or sign in to your account in the app and tap Pair this phone. No phone? Add an SMS provider instead.
3. Send a message.

export BRIDGE_URL="https://api.bridge.kroszborg.co"   # or your own server, e.g. http://localhost:8080
export BRIDGE_API_KEY="bk_test_..."

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

The response is 202 Accepted with the message in status queued. Follow it in the dashboard under Messages, or with GET /v1/messages/{id}.

From TypeScript, use the SDK (npm install @kroszborg/bridge):

import { Bridge } from '@kroszborg/bridge';

const bridge = new Bridge({
  apiKey: process.env.BRIDGE_API_KEY,
  baseUrl: process.env.BRIDGE_URL,
});

const msg = await bridge.messages.send({ to: '+919876543210', message: 'Your order has shipped.' });
const final = await bridge.messages.waitFor(msg.id); // delivered, or failed with a reason

From a terminal, use the CLI: bridgectl send +919876543210 "Hello" --wait.

Where to go nextCopy Anchor Link