Telegram Premium Business Bots: Reply on Behalf

Setup

Actor	Action
Bot owner	@BotFather → Bot Settings → Business Mode → enable, configure default rights
End user (Premium)	Settings → Telegram Business → Chatbots → enter bot @username, grant BusinessBotRights
Telegram → bot	Sends updateBotBusinessConnect with connection_id

The connection_id persists until the user revokes, disables, or changes the bot's rights — at which point a new updateBotBusinessConnect arrives (possibly with disabled: true).

Update Stream

In addition to the regular Update types, business-connected bots receive:

Update	When	Key fields
business_connection	Connected / rights changed / disabled	id, user (owner), can_reply, is_enabled
business_message	Customer wrote to owner	business_connection_id, regular Message fields
edited_business_message	Customer edited a message	same as above
deleted_business_messages	Customer deleted messages	business_connection_id, chat, message_ids

Sending on Behalf

Most send/edit methods accept an optional business_connection_id parameter. When set, the API routes the action through the owner's account:

sendMessage(business_connection_id="abc123", chat_id=..., text=..., reply_markup=...)

The resulting Message has via_business_connection: true and via_bot_id set. To the customer, the indicator is barely visible (small "via bot" hint on long-press); functionally it looks like a 1:1 chat with the owner.

Schema Changes (incorporate into Phase 1)

The handler routing plan introduces tg_user_current_handlers and tg_user_navigation_states. Both should include business_connection_id from the start to avoid a future migration:

create table tg_user_current_handlers (
  bot_id                 int  not null references tg_bots(id) on delete cascade,
  business_connection_id text not null default '',  -- '' = regular bot mode
  user_id                int  not null,
  value                  text not null default '',
  updated_at             datetime not null default current_timestamp,
  primary key (bot_id, business_connection_id, user_id)
);

create table tg_user_navigation_states (
  bot_id                 int  not null references tg_bots(id) on delete cascade,
  business_connection_id text not null default '',
  user_id                int  not null,
  value                  text not null default '{}',
  updated_at             datetime not null default current_timestamp,
  primary key (bot_id, business_connection_id, user_id)
);

New table for tracking active business connections per bot:

create table tg_business_connections (
  connection_id text primary key,                    -- from updateBotBusinessConnect
  bot_id        int  not null references tg_bots(id) on delete cascade,
  owner_user_id int  not null,                       -- Telegram user ID of Premium owner
  rights        text not null default '{}',          -- JSON snapshot of BusinessBotRights
  is_enabled    boolean not null default true,
  connected_at  datetime not null default current_timestamp,
  updated_at    datetime not null default current_timestamp
);

Optional bot-level flag:

alter table tg_bots add column business_mode boolean not null default false;

Dispatcher Routing

cmd/server/telegram.go extracts (bot_id, business_connection_id, user_id) from any update type:

func extractBusinessConnectionID(update tgbotapi.Update) string {
    switch {
    case update.BusinessMessage != nil:
        return update.BusinessMessage.BusinessConnectionID
    case update.EditedBusinessMessage != nil:
        return update.EditedBusinessMessage.BusinessConnectionID
    case update.DeletedBusinessMessages != nil:
        return update.DeletedBusinessMessages.BusinessConnectionID
    case update.BusinessConnection != nil:
        return update.BusinessConnection.ID
    case update.CallbackQuery != nil && update.CallbackQuery.Message != nil:
        return update.CallbackQuery.Message.BusinessConnectionID
    }
    return ""
}

Handlers (handletgupdate, handletgnavigationupdate) receive business_connection_id via the request context and pass it through every Send / Edit call.

Reply Helper

A thin wrapper on Send that auto-injects BusinessConnectionID:

func (a *app) SendForUser(ctx context.Context, businessConnectionID string, msg tgbotapi.Chattable) (tgbotapi.Message, error) {
    if businessConnectionID != "" {
        if base, ok := msg.(tgbotapi.BaseChatMessage); ok {
            base.BusinessConnectionID = businessConnectionID
        }
    }
    return a.tg.Send(msg)
}

Two Contexts, One Bot

Context	Visible to	Purpose
Business chat (business_connection_id set)	Owner + customer	Customer-facing UI: navigation, forms, payments, replies
Bot DM (@trip2g_dev4_bot ↔ owner)	Owner only	Owner-facing admin UI: search, full inbox, agent suggestions, escalation controls

The same person (@rnbwkpr) lives in both at once. In tg_user_current_handlers, this is naturally (bot_id, business_connection_id, user_id) — empty business_connection_id for the DM, the connection id for business chats.

Bridging the Two: /start bizChat<chat_id> Deep-Link

Telegram itself generates t.me/<bot>?start=bizChat<chat_id> when the owner taps a "Manage" button inside a business chat. The owner's client switches to the bot DM and the bot receives a /start bizChat<chat_id> payload — letting the bot show owner-only controls for that specific customer chat.

The same mechanism works in reverse: the bot can attach buttons with url=t.me/<bot>?start=<context> to a message in the business chat. Tapping moves the owner into the DM with full context; the customer just sees the owner tapped something. No alert, no leakage.

Options for "Owner-Only" Hints

Mechanism	Owner-only?	Notes
Send message to bot DM with owner	Yes	Standard pattern. Use for search results, suggested replies, agent activity
url=t.me/bot?start=<ctx> button in business chat	Tap routes only the owner	Clean handoff; customer sees a button press but no content
answerCallbackQuery(show_alert=true)	Only the tapper	Anyone in the chat could tap; not strictly owner-only
editMessageReplyMarkup (change buttons)	All participants see the change	Not private
Telegram "Saved Messages" of the owner	Yes (visible only to owner)	Bot API cannot write there
Telegram drafts	Yes (visible only to owner)	Bot API does not expose drafts

Recommended Pattern

• Keep customer-facing surfaces (nav, forms, payments) inside the business chat
• Move all owner controls (search, inbox triage, agent override, analytics) into the bot DM
• Add at most one bridge button in business chats (url=t.me/bot?start=...) when the owner needs to invoke something private from a customer thread; everything else lives in the DM permanently

This also matches Telegram's own UX: their built-in chatbot integrations expose a small "Manage" affordance in business chats that funnels everything into the bot DM.