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.

Open Telegram and search for @BotFather
Send /newbot
Choose a display name
Choose a username that ends with bot
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:

Paste the bot token
Choose the default Nakama profile for Telegram replies
Save

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:

Open Settings in the Nakama web app
Add an OpenAI provider in LLM providers if you have not added one yet
In Audio transcription model, choose an OpenAI model such as Whisper
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.

Step 4: Pair your Telegram account

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

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

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

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:

bash

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:

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

To paste raw Telegram update JSON instead:

Open Integrations → Telegram
In Allowed users, click Manage
Click Import JSON
Paste the raw Telegram update JSON
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:

json

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

The allowed user ID is:

text

213193924

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

Private chat behavior

Private chat is the simplest mode.

Once paired or allowlisted:

normal messages go to the Nakama agent
the bot keeps a Telegram chat session
Telegram commands work immediately

If an unlinked user opens the bot, Nakama asks for the pairing code instead of sending the message to the agent.

Group chat behavior

Nakama supports Telegram groups, but it is intentionally conservative about when it replies.

In a group, the bot responds only when the message is:

a slash command like /status
a reply to one of the bot's messages
a direct mention like @your_bot_name hello

This keeps group chats usable without making the bot noisy.

Group topics and profiles

In Telegram supergroup topics, each topic can use its own Nakama profile.

/profile inside a topic changes only that topic
new topics use the default Telegram profile until you switch them
/profile in the main group chat changes the group-level profile
/org stays group-level, so switch org first if a topic needs a profile from another org

Outbound notifications to Telegram

Nakama can also send simple text notifications into Telegram.

This is separate from the normal chat bridge. Instead of waiting for a Telegram user to message the bot first, another app can call a Nakama webhook and Nakama will post the message into a configured Telegram chat.

This is useful for things like:

new payment notifications
failed job alerts
deploy finished messages
support or sales event notifications

How it works

Open Integrations
In Notification destinations, create a new destination
Choose a name
Paste the Telegram topic link, such as https://t.me/c/3734526664/147
Save and copy the generated webhook URL and API key

Each destination belongs to one org and points to one Telegram target. Nakama extracts the Telegram Chat ID and Topic ID from the link and sends the message directly into that topic thread.

Webhook payload

Nakama keeps the webhook contract intentionally small.

Send a POST request with JSON like this:

json

{
  "title": "Payment received",
  "body": "Order #INV-1042 paid by Acme Co.",
  "level": "success"
}

body is required. title is optional. level is optional and can be info, success, warning, or error.

Nakama formats that into a short Telegram text message and sends it to the configured chat or topic.

Design note

In v1, Nakama does not accept arbitrary templating or custom Telegram payloads from external apps.

That is intentional:

the webhook stays stable and easy to validate
external apps only need to send simple notification text
the destination model can later support Slack or Discord with the same webhook shape

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:

Open @BotFather
Open your bot settings
Disable Group Privacy
Remove the bot from the Telegram group
Add it back again

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

Telegram commands

These commands are available in Telegram:

Command	What it does
`/start`	Welcome and help
`/help`	Show command help
`/stop`	Stop the current in-progress reply
`/clear`	Clear chat history
`/compact`	Compact conversation history
`/new`	Start a new conversation
`/org`	Choose or switch organization
`/profile`	Choose or switch profile
`/status`	Show server and model status

Supported message types

Telegram can send more than plain text into Nakama.

Supported inputs include:

text messages
photos
voice notes and audio messages
supported documents such as pdf, docx, txt, and csv

Small supported documents are downloaded and forwarded into the Nakama chat flow. Voice notes and audio messages are first transcribed with the configured OpenAI audio transcription model. Unsupported media gets a friendly rejection message instead of silently failing.

Rich Markdown replies

Agents can reply in normal Markdown-style text. Nakama converts a safe subset into Telegram rich formatting.

Supported formatting includes:

**bold**
*italic*
__underline__
inline code
fenced code blocks
headings
simple links

If Telegram rejects the rich rendering, Nakama falls back to plain text.

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:

text

TELEGRAM_BOT_TOKEN

Nakama also supports:

text

TELEGRAM_ALLOWED_USER_IDS
NAKAMA_TELEGRAM_PROFILE_ID

Notification destinations for groups and topics

From Integrations → Notifications, Nakama can create Telegram webhook destinations for a group or a forum topic.

If you already have a topic share link such as:

text

https://t.me/c/3734526664/147

you can derive the form values directly:

Telegram chat ID: prefix the number after /c/ with -100 → -1003734526664
Telegram topic ID: use the last path segment → 147

This matches what Telegram Bot API returns in:

message.chat.id
message.message_thread_id

If you prefer the API method, send a fresh message in the target topic and call:

text

https://api.telegram.org/bot<BOT_TOKEN>/getUpdates

Then copy message.chat.id and message.message_thread_id from the matching update.

Troubleshooting

The bot does not answer at all

Check these first:

The bot token is saved correctly
bun run dev:telegram is running
The Nakama server is running
The Telegram user is paired or allowlisted

Private chat works but group chat does not

Usually one of these is true:

Group Privacy is still enabled
the bot was added before Group Privacy was changed
the bot was not removed and re-added
the message was not a command, reply, or direct mention

Mentions do not work in groups

Check these:

Disable Group Privacy in @BotFather
Remove the bot from the group and add it again
Make sure only one Telegram bridge worker is running

Telegram says the chat is not linked

This usually means:

the user never sent the pairing code
the pairing code expired or was replaced
the message was sent in a group instead of a private chat

Generate a new pairing code from Integrations → Telegram and send it to the bot in a private chat.

Telegram ​

What Telegram supports ​

Step 1: Create a bot with BotFather ​

Step 2: Save Telegram settings in Nakama ​

Step 3: Enable audio transcription for voice chat ​

Step 4: Pair your Telegram account ​

Why pairing exists ​

Step 5: Start the Telegram bridge ​

Optional: Direct allowlist instead of pairing ​

Private chat behavior ​

Group chat behavior ​

Group topics and profiles ​

Outbound notifications to Telegram ​

How it works ​

Webhook payload ​

Design note ​

Step 6: Configure Telegram privacy mode for groups ​

Telegram commands ​

Supported message types ​

Rich Markdown replies ​

Configuration notes ​

Notification destinations for groups and topics ​

Troubleshooting ​

The bot does not answer at all ​

Private chat works but group chat does not ​

Mentions do not work in groups ​

Telegram says the chat is not linked ​

Next steps ​

What Telegram supports

Step 1: Create a bot with BotFather

Step 2: Save Telegram settings in Nakama

Step 3: Enable audio transcription for voice chat

Step 4: Pair your Telegram account

Why pairing exists

Step 5: Start the Telegram bridge

Optional: Direct allowlist instead of pairing

Private chat behavior

Group chat behavior

Group topics and profiles

Outbound notifications to Telegram

How it works

Webhook payload

Design note

Step 6: Configure Telegram privacy mode for groups

Telegram commands

Supported message types

Rich Markdown replies

Configuration notes

Notification destinations for groups and topics

Troubleshooting

The bot does not answer at all

Private chat works but group chat does not

Mentions do not work in groups

Telegram says the chat is not linked

Next steps