OFFICIAL SETUP GUIDE

Connect Telegram to HubSpot

This public guide covers installation, bot configuration, the first end-to-end test, and what users experience after the integration is live. Most setups take about 15 minutes.

HubSpot

You need permission to install apps in the HubSpot portal you want to connect.

A Telegram account is enough to create a free bot with @BotFather.

Inbox mode

Support inbox routing requires a HubSpot plan that grants custom-channel access. Outbound-only bots do not require an inbox.

INSTALLATION

Five steps from install to first message

Install and connect HubSpot

From the HubSpot Marketplace listing, select Install app. You can also create an account at telegram.resonatehq.com and select Connect HubSpot. Choose the portal you administer, review the requested permissions, and approve the connection. You will return to the Setup dashboard.

Create a Telegram bot

In Telegram, open the verified @BotFather account and send /newbot. Choose a display name and a username ending in bot. Copy the token BotFather returns. Keep this token private; anyone with it can control the bot.

Add the bot from the Setup dashboard

Under Your bots, choose what the bot is for. Select Support to route incoming chats to a HubSpot Inbox or Help Desk, or Outbound only for notifications and workflow sends without an inbox. Select an inbox when prompted, paste the BotFather token, and connect the bot.

Add the Telegram CRM cards

Open a Contact record in HubSpot and select Customize → Customize record page. Select Add cards, search for Telegram, add the Telegram card, and save. Repeat on Deal, Company, Ticket, or Project records to add the Telegram Group card for shared client groups.

Run a complete test

Open the bot link from the dashboard, press Start in Telegram, and send a message. For a Support bot, confirm that the message appears in the selected HubSpot inbox and that a reply from HubSpot reaches Telegram. For outbound messaging, use the built-in workflow-action tester or add a Telegram action to a HubSpot workflow.

What happens after setup

New Telegram chats are matched to an existing HubSpot contact or create one.
Support conversations appear in HubSpot Inbox or Help Desk.
Replies and supported attachments travel between HubSpot and Telegram.
Workflow actions can send text, buttons, photos, files, group posts, and team alerts.
CRM cards show connection status, personal invite links, recent messages, and group controls.

Plan-dependent features

Outbound bot sends and direct CRM-card sends work without a HubSpot inbox.
Inbox and Help Desk routing requires HubSpot custom-channel access.
Workflow actions require a HubSpot edition that includes workflows.
Projects support appears only when the connected portal grants Projects access.
Replying as a personal Telegram account requires Telegram Premium.

Troubleshooting

The bot cannot read group messages

In @BotFather, open Bot Settings → Group Privacy and turn privacy off for this bot.

The app cannot add an inbox channel

Connect the bot as Outbound only, or use a HubSpot portal with custom-channel access and reconnect HubSpot to grant those optional permissions.

A workflow cannot message a contact

The contact must first start the bot and link that Telegram chat to the same CRM record. Use the invite link or QR shown on the Telegram contact card.

Need help?

Email support@resonatehq.com and include your HubSpot portal ID and the bot username. Never send a bot token.