​

Channels

Before anyone can authorize anything, this environment needs a channel connection — the provider identity a recipient actually sees in their chat. There are three, and the right one depends on who is being messaged.

None of these falls back to another. A connection is one environment’s choice, so test and live never share an identity, a subscriber, or a credential — and nothing silently sends as WhooshBang because your own bot had a bad day.

The shared WhooshBang bot is a supported option, not a stepping stone. It is the right answer for a large class of real use, and there is no plan to retire it. It is simply not your brand, which is why the other two exist.

wb project create already made the first of these for you. To choose a different one:

npx wb connection create --mode customer_byok --credential-stdin < token.txt

The command selects the only shared identity on offer when there is one, names the connection after the mode, and routes it — because somebody creating a connection means to send through it. --no-route opts out.

Through the API, list what this deployment offers, then create one:

curl --silent --show-error \
  --header "Authorization: Bearer $WHOOSHBANG_CREDENTIAL" \
  "https://api.whooshbang.com/v1/projects/$PROJECT_ID/environments/$ENVIRONMENT_ID/connection-providers"

const providers = await whooshBang.listConnectionProviders(
  projectId,
  environmentId,
);
const whooshBangIdentity = providers.items[0]?.shared_identities[0];

const connection = await whooshBang.createChannelConnection(
  projectId,
  environmentId,
  {
    mode: "whooshbang_shared",
    display_name: "Test sender",
    shared_identity_id: whooshBangIdentity.id,
  },
  { idempotencyKey: "quickstart-connection-1" },
);

For a bot you already own, send mode: "customer_byok" with its token in credential. It is write-only: sealed on arrival, never echoed by any later read, and absent from every connection record. For a bot Telegram creates for you, send mode: "customer_managed" with a suggested username; the response comes back pending with a setup.handoff_url for a person to open in Telegram.

​

Routing

A connection nothing routes to is configured and inert. It delivers nothing, and a subscriber cannot authorize against it either. If your sends are accepted and nothing ever arrives, this is almost always why.

The command line routes for you, and the first connection in an environment routes itself. Through the API you attach it yourself:

const routes = await whooshBang.listNotifierConnections(
  projectId,
  environmentId,
);

The first connection in an environment whose default notifier has no route at all is attached for you, so a fresh setup works immediately. Every later connection lands unrouted on purpose — promoting it automatically would put a different bot in front of subscribers who consented to the first one. Promote one deliberately:

await whooshBang.attachNotifierConnection(projectId, environmentId, {
  notifier_id: environment.default_notifier.id,
  connection_id: connection.id,
});

Promoting demotes the previous default in the same transaction. Subscribers who authorized the old connection keep that consent and stop receiving until it is default again; consent is never moved between identities.