Telegram

Link a Telegram chat to your hlix Workspace with a one-time code, then talk to the chat agent from your phone.

Connect a Telegram chat to work with your Hlix agent from your phone. Link it with a one-time code, then send requests using your Workspace’s projects, models and tools.

What it does

Link a direct chat with one tap or connect a group with /link <code>.
Send requests and receive the agent’s replies in the chat.
Include up to ten recent messages as conversation context.
Read long answers across ordered messages and see typing activity while the agent works.

Messages are recorded in the audit log as integration.channel.dispatched, with the Telegram user’s ID and name.

Prerequisites

A Hlix Workspace and the owner or admin role

Link a chat

Generate a code in the dashboard under Integrations → Telegram, or directly:

curl -X POST https://server.hlix.ai/v1/api/integrations/telegram/link-code \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID" \
  -H "Authorization: Bearer $HLIX_API_KEY"

{
  "code": "K7M2PQ9XTVA3JHNR4B0C",
  "expiresAt": "2026-08-09T12:15:00.000Z",
  "command": "/link K7M2PQ9XTVA3JHNR4B0C",
  "botUsername": "hlix_bot"
}

Use the displayed code within 15 minutes. Generate a fresh code for each chat.

Tap the link. The dashboard shows an Open in Telegram link beside the code, built from the same response:
```
https://t.me/hlix_bot?start=K7M2PQ9XTVA3JHNR4B0C
```
https://t.me/<botUsername>?start=<code> — Telegram opens the chat and sends /start <code> for you. No manual code entry is needed for a direct chat.

Or send the command yourself, which is what a group needs — a t.me deep link opens a direct chat, so paste the command into the group the bot has joined instead:
```
/link K7M2PQ9XTVA3JHNR4B0C
```
Both methods use the same single-use code. Dashes, spaces and lower case are accepted.

Confirm. The bot replies:

This chat is now linked to your hlix workspace. Ask me anything — I can list projects, create tasks and run cycles.

Talk to it. Anything that is not a command goes to the chat agent.

Commands

Use /start, /help and /link to manage the connection. Other non-command messages go to the chat agent.

Command	What it does
`/start`	Says whether this chat is connected, and how to connect it if not. Telegram sends this itself the first time someone opens the bot
`/start <code>`	Links the chat using a code; sent automatically by the one-tap link
`/help`	The same, plus what the agent can do for a connected chat
`/link <code>`	Redeems a link code and binds this chat. The typed form, and the only one that works in a group

Use /help in a direct chat to see the bot’s commands.

Who can act through a linked chat

Everyone in the linked chat can use the Workspace’s agent tools, including creating tasks and running cycles. Access follows chat membership, including anyone you add later. Disconnect the chat when its members should no longer have this access.

Security

Hlix verifies Telegram requests and uses the chat connection to select your Workspace.

If it does not respond

Chat is not linked: generate a code under Integrations → Telegram and send /link <code> in that chat.
Invalid or expired code: generate a fresh one. Each code works once and expires after 15 minutes.
Chat already linked elsewhere: disconnect it from the other Hlix Workspace before linking it here.
One-tap link did not connect: use the complete ?start=<code> link, or send /link <code> manually.
Permission error creating a code: use an account with the owner or admin role.
No bot reply: confirm the chat is linked, then send /start. Contact support if it still does not respond.