Telegram Bot Integration

The HARi bot, @custol_bot, looks up your records from a private Telegram chat and answers as you. Connect it from My Profile. /search and /stats show only what your role already lets you see. Sending /start on its own does not connect the chat, and a message with no command does not run a search. Pushing CRM events into Telegram, further down this page, is separate and does not use this bot.

How do I connect a chat?

1. Open the account menu and choose Profile. The page is titled My Profile.
2. On the Telegram card, click Connect Telegram.
3. Open the link. It works for 10 minutes, and only once. That connects the private chat to this workspace.

The steps, the screenshot and what an expired link says are in How to connect the Telegram bot.

Connecting starts in HARi rather than in Telegram, because Telegram only ever tells the bot a chat number and never a name. The one-time link from your account is what says which HARi account the chat belongs to. Typing /start with no link does not do that. The bot tells you to go back to My Profile and choose Connect Telegram.

Commands

Four commands, in a connected private chat.

Search

/search Acme

Finds records you can see and returns up to five, each with a link that opens it in HARi. The search is the same one HARi uses, under your own permissions. A record your role cannot open does not appear. Leads and opportunities are not a special case: they show up only when you can already see them, the same as any other record. A message with no slash is not a search. The bot answers Unknown command. Type /help to see what I can do.

Stats

/stats

How many records of each type you can see, named the way your workspace names them. If you renamed Contacts to Members, the bot says Members. The counts narrow with your access the same way the figures in the app do.

Stop

/stop

Disconnects the chat. The bot replies Disconnected. and stops recognising you. It stays in your Telegram list; it just no longer knows who is typing.

Help

/help

Lists the commands above.

What the bot can read

Only what you can read. Every message checks who the chat belongs to and what that person is allowed to see. A record held by a team you are not on stays out of /search and out of /stats. See permissions and security.

One Telegram chat is connected to one workspace at a time. This account keeps one connected chat: opening a new link replaces it. Connecting the same chat from a second workspace moves it.

If your account is deactivated, the next message is told the chat is not connected. Leaving the workspace disconnects the chat. A suspended workspace does not answer with records.

Outbound notifications via workflows

This does not involve the HARi bot. In Settings → Workflows, a workflow’s Call webhook (URL) action posts to any address you give it, including the Telegram Bot API:

• When a deal is closed-won then webhook to Telegram with “Deal won: {{ name }} for {{ amount }}”
• When a task is overdue then webhook to Telegram with the assignee’s chat ID
• When a contact’s score exceeds 50 then webhook to a sales-manager Telegram channel

What you need first

The bot these rules post to is yours, not HARi’s — @custol_bot cannot be used this way. Create one by sending /newbot to @BotFather, which “will ask you for a name and username, then generate an authentication token for your new bot” (Telegram). Keep that token private; Telegram warns it “can be used by anyone to control your bot”.

The token goes in the action’s URL field. Telegram’s requests “need to be presented in this form: https://api.telegram.org/bot<token>/METHOD_NAME” (Telegram Bot API), and the Payload (JSON or template) field carries the message, including the ID of the chat you are sending to.

Finding that chat ID is the awkward part: Telegram publishes no general lookup for it, and its documentation describes only specific ways a bot can be handed one. Consult Telegram’s bot documentation for the method that fits your case rather than guessing at an ID.

Rate limits

Telegram rate-limits bots, so keep high-volume rules off this path: “For bulk notifications, bots are not able to broadcast more than about 30 messages per second” (Telegram Bot FAQ), and no more than 20 messages a minute into any one group. For reaching a list of people on a schedule, email is the right tool.

Security

• Private chats only. A group chat receives no reply, even one the bot has been added to.
• Nothing before a connection. A chat that is not connected is told only that it is not connected. It cannot reach any record, count or name.
• Signed messages only. HARi registers the bot with a secret that Telegram returns in a header on every message, and refuses anything that arrives without it. Telegram’s Bot API documentation states the purpose directly: “The header is useful to ensure that the request comes from a webhook set by you” (Telegram Bot API).