Telegram

Connect your app

1. Open Settings → Apps → your app → Integrations → Telegram.

2. Open @BotFather in Telegram and send /newbot. Create a dedicated bot for this app and paste its token into AppNorth. Select Save bot and register webhook. One bot can connect to only one AppNorth app; registering this webhook replaces any existing webhook for that bot.

3. Create a private team group, enable Topics, add the bot, and make it an administrator with permission to manage topics. Keep customer conversations in a group restricted to your support team.

4. Send a message in the group. AppNorth detects groups from my_chat_member and message updates. Select Refresh groups, choose the detected group, and save it. Detection alone never starts forwarding conversations.

5. Start a new conversation from your app. AppNorth creates a topic named after the reporter and app, then posts the initial message with available device, OS and app-version details and a dashboard link. Missing details are labelled unavailable.

The setup instructions can be copied in English or Spanish. Existing conversations are not backfilled. New user messages, ordinary team replies and status changes are forwarded. Internal notes, images and interactive chat cards are not forwarded as media or cards.

Reply and resolve

Reply with text inside the topic. Group administrators and the group creator can reply as Team. Bot messages, anonymous sender_chat messages, service messages and unsupported commands are ignored. Only open conversations accept replies.

Send /resolve (or /resolve@your_bot_username) in the topic to resolve the conversation in AppNorth. In a normal group without Topics, reply directly to an AppNorth conversation message; replies to imported team messages also work. To resolve there, reply /resolve to one of those messages. The message-to-conversation mapping prevents unrelated group messages entering the chat.

An AppNorth owner/admin can optionally map a Telegram user to an existing organization member with a same-origin authenticated PUT /api/integrations/telegram/connection?projectId=APP_ID:

{
  "action": "member",
  "telegramUserId": "TELEGRAM_NUMERIC_ID",
  "userId": "APPNORTH_MEMBER_USER_ID"
}

Mapped users must still belong to the Telegram group and the AppNorth organization. Their replies are attributed to that member; unmapped users must be Telegram administrators. There is no email or username-based automatic identity linking.

Hosting

• Apply migration 0042_telegram after the preceding migrations.

• Configure APPNORTH_CREDENTIALS_KEY using the same versioned AES-256-GCM keyring as App Store Connect credentials. Bot tokens and webhook secrets are sealed with organization/app-specific associated data.

• Set NEXT_PUBLIC_APP_URL to the public HTTPS origin. Telegram sends updates to /api/integrations/telegram/webhook/[integrationId]. Every update must pass the X-Telegram-Bot-Api-Secret-Token check.

• Run the existing cron scheduler with CRON_SECRET and APPNORTH_APP_URL. Its telegram job calls GET /api/internal/telegram every minute to drain outbound work. It does not poll Telegram for inbound messages. You can run one pass with node scripts/cron.mjs telegram.

The transactional outbox captures chat/report creation, replies and status changes in the same tenant transaction. Inbound update IDs and reply keys suppress repeated deliveries. Outbound operations persist topic creation and each message chunk separately; rate limits and transient errors retain pending work with backoff. Telegram’s Bot API has no client idempotency key for topic creation or sends: if Telegram accepts an operation but its response or the subsequent database commit is lost, a retry can produce a duplicate topic/message. AppNorth does not promise exactly-once external delivery.

Disconnect and troubleshoot

Disconnect before changing the bot or group. Disconnecting revokes the local integration and removes pending work and mappings; existing Telegram messages remain. AppNorth attempts to delete the webhook, but local revocation succeeds even if Telegram is unavailable. Reconnecting starts with new conversations.

If no group appears, save the bot again to retry webhook registration, verify the public HTTPS URL is reachable, add the bot to the group and send a new message. If sending fails, check administrator and topic-management permissions. Delivery and inbound replies pause when the workspace loses paid access. Provider errors shown in the UI are generic and never include credentials.