Nakama
Telegram

Telegram

Nakama can run as a Telegram bot so you can chat with the same agent from your phone, desktop Telegram, or a shared group.

The mental model is simple:

  • Telegram is a channel for Nakama
  • The bridge talks to the same Nakama server as the web app
  • Pairing links a real Telegram user to your Nakama access

What Telegram supports

With Telegram enabled, users can:

  • chat with a Nakama profile in a private chat
  • use the bot in Telegram groups
  • receive outbound webhook notifications in a group or topic
  • switch org and profile with commands
  • send text, photos, voice notes, and supported documents
  • receive Markdown-style rich replies when Telegram accepts the formatting

Step 1: Create a bot with BotFather

Every Telegram setup starts with a bot token from @BotFather.

  1. Open Telegram and search for @BotFather
  2. Send /newbot
  3. Choose a display name
  4. Choose a username that ends with bot
  5. Copy the bot token

Keep the token secret. Anyone with the token can control your Telegram bot.

Step 2: Save Telegram settings in Nakama

Open Integrations → Telegram in the Nakama web app, then:

  1. Paste the bot token
  2. Choose the default Nakama profile for Telegram replies
  3. Save

Paste the bot token from @BotFather on Integrations → Telegram

When you save for the first time, Nakama can generate a pairing code for linking your Telegram account.

Step 3: Enable audio transcription for voice chat

Telegram voice notes and audio files are turned into text before they are sent to the agent.

To enable that:

  1. Open Settings in the Nakama web app
  2. Add an OpenAI provider in LLM providers if you have not added one yet
  3. In Audio transcription model, choose an OpenAI model such as Whisper
  4. Wait for the Saved confirmation

If no OpenAI provider is connected, the audio transcription setting stays unavailable. Without this setting, text chat still works, but Telegram audio messages will not be transcribed for the agent.

Choose an OpenAI audio transcription model under Settings

Step 4: Pair your Telegram account

Pairing is required so random Telegram users cannot talk to your internal Nakama bot.

  1. Copy the pairing code from Integrations → Telegram
  2. Start a private chat with your bot
  3. Send the pairing code as a normal text message

After a successful match, that Telegram user is linked and the pairing code is cleared.

Generate a pairing code, then message it to your bot in Telegram

Why pairing exists

The bot token only connects Nakama to Telegram.

Pairing connects your Telegram user account to Nakama permissions.

That means Nakama can:

  • identify which Telegram user is talking
  • allow private chat safely
  • apply the right org and profile access

Step 5: Start the Telegram bridge

For local development, start it from the repo root:

bun run dev:telegram

The bridge uses long polling and forwards Telegram messages to your Nakama server.

If the Nakama server is not already running, the bridge will try to start it.

For production, start the Telegram bridge worker from the Integrations page in the Nakama web app instead of using the dev command.

Optional: Direct allowlist instead of pairing

Nakama also supports allowlisting Telegram user IDs directly.

This is useful when you want to pre-authorize specific users without the one-time pairing flow.

To add users from the dashboard:

  1. Open Integrations → Telegram
  2. In Allowed users, click Manage
  3. Paste a numeric Telegram user ID and click Add

To paste raw Telegram update JSON instead:

  1. Open Integrations → Telegram
  2. In Allowed users, click Manage
  3. Click Import JSON
  4. Paste the raw Telegram update JSON
  5. Click Add user

Use the Telegram user's from.id, not their @username. When you paste raw JSON, Nakama reads message.from.id and shows the username when it is present.

For example, in this Telegram update payload:

{
  "from": {
    "id": 213193924,
    "username": "ahmadrosid"
  }
}

The allowed user ID is:

213193924

You can also configure allowed users through TELEGRAM_ALLOWED_USER_IDS for environment-based deployments.

Step 6: Configure Telegram privacy mode for groups

Telegram bots start with Group Privacy enabled. This is the most common reason a bot seems fine in private chat but not in groups.

If you want mention-based group usage to work reliably:

  1. Open @BotFather
  2. Open your bot settings
  3. Disable Group Privacy
  4. Remove the bot from the Telegram group
  5. Add it back again

That re-add step matters because Telegram may keep the old delivery behavior for bots already in the group.

Configuration notes

Nakama stores Telegram bridge settings under its local config directory.

Important values include:

  • bot token
  • default Telegram profile
  • pairing code
  • paired user IDs
  • allowed user IDs from the dashboard allowlist

Environment-based setup is also supported. The main env var is:

TELEGRAM_BOT_TOKEN

Nakama also supports:

TELEGRAM_ALLOWED_USER_IDS
NAKAMA_TELEGRAM_PROFILE_ID

Next steps

CLI

Use Nakama from the terminal — interactive chat and slash commands.

Chat behavior & commands

How the Nakama Telegram bot behaves in private chats, groups, and topics — plus the commands and message types it supports.

On this page

What Telegram supportsStep 1: Create a bot with BotFatherStep 2: Save Telegram settings in NakamaStep 3: Enable audio transcription for voice chatStep 4: Pair your Telegram accountWhy pairing existsStep 5: Start the Telegram bridgeOptional: Direct allowlist instead of pairingStep 6: Configure Telegram privacy mode for groupsConfiguration notesNext steps