Telegram setup guide

Agents read conversations and write messages for your company. Anything a customer or the public sees, such as a sent email or a posted message, is tier 3, so it asks first unless you decide otherwise.

Ways to connect

Company admins connect apps, on the Integrations page in Everdeck: open Telegram, choose one of the ways below, follow its steps and fill in its fields. Everdeck checks what you enter before it saves anything, and asks you to confirm it’s you (your second factor) before you type any secret. How connecting works.

Bot token from @BotFather

API key.

1. In Telegram, open @BotFather (https://t.me/BotFather) and send /newbot. Choose a display name and a username ending in "bot".
2. Copy the token BotFather sends back into the form.
3. Customers must message the bot first (or add it to a group): Telegram bots can't start conversations. Share the bot link t.me/<username> where customers will find it.
4. In groups, the bot only sees commands, replies to its messages and mentions. To let it read every message, send /setprivacy to @BotFather and choose Disable, then re-add the bot to the group.
5. To have messages start agent work, make up a secret of 16 to 256 letters, digits, _ or - and enter it in Webhook secret token. Subscribe message_received on the Intake page and copy the address it shows. Then register it with Telegram from a terminal, with your bot token, the Intake address and your secret filled in. It is a POST, so none of them is left in browser history: curl -F "url=<Intake address>" -F "secret_token=<secret>" -F 'allowed_updates=["message","edited_message"]' https://api.telegram.org/bot<bot token>/setWebhook Telegram answers "Webhook was set". A bot sends its updates to one address only, so use each bot token for one connection's trigger.
6. Telegram keeps sending to the address it was given. Whenever the address Intake shows changes (after you rotate it, or subscribe message_received again: it gets a new address) or you change the Webhook secret token, run the step 5 command again with the new values. After you turn the trigger off or disconnect this connection, stop Telegram sending with: curl -X POST https://api.telegram.org/bot<bot token>/deleteWebhook Until then every update goes to an address that refuses it and is lost, and the bot can't use getUpdates. If you turn the trigger back on later, it keeps its address: run the step 5 command again.
7. To check that updates arrive, run: curl -X POST https://api.telegram.org/bot<bot token>/getWebhookInfo If its last_error_message mentions 401, Everdeck refused the updates: the connection has no Webhook secret token, or it isn't the secret_token you gave Telegram. Enter the secret on the connection and run the step 5 command again with it.

Field	What to enter
Bot token	A secret: Everdeck saves it encrypted and never shows it again. Where to find it.
Webhook secret token (optional)	A secret: Everdeck saves it encrypted and never shows it again. Needed for the message_received trigger. Make one up; you give Telegram the same value as secret_token.

Disconnecting deletes the credentials Everdeck saved, but Everdeck can't revoke them: the key, token or password itself keeps working at Telegram until you delete or rotate it there.

What agents can do

An agent uses an action only when its charter grants it, on the agent’s Tools tab, where you choose whether each one runs by itself (Auto), asks first or never runs. Each action has a risk tier: tier 3 actions, which customers or the public see, ask first unless you choose otherwise, and tier 4 actions (money, deleting things, access) always need a person. How tools and tiers work.

Actions marked Reads outside content return things people outside your company may have written. Agents treat what they read as information, never as instructions, and their riskier actions later in the same session need approval.

• Send a messageTier 3 · Externaltelegram_send_message

  Send a plain-text message to a chat the bot can reach (a user who messaged it, a group or a channel). Up to 4,096 characters.

• Reply to a messageTier 3 · Externaltelegram_reply_to_message

  Send a message that quotes and replies to a specific message in the chat.

• Send a photoTier 3 · Externaltelegram_send_photo

  Send a photo by public HTTPS URL (up to 5 MB) or by a Telegram file_id, with an optional caption.

• Send a fileTier 3 · ExternalReads outside contenttelegram_send_document

  Send a document from the company's files (any type, up to 10 MB, the company files limit), or a file_id or public URL (URLs work for PDF and ZIP only).

• Edit a messageTier 3 · Externaltelegram_edit_message_text

  Replace the text of a message the bot sent.

• React to a messageTier 3 · ExternalReads outside contenttelegram_set_reaction

  Set the bot's emoji reaction on a message (bots can set one reaction per message). The customer or group sees the reaction.

• Delete a messageTier 4 · Money or irreversibleReads outside contenttelegram_delete_message

  Delete a message less than 48 hours old: one the bot sent, one in a private chat with the bot, or, when the bot is a group admin, any message in the group.

• Look up a chatTier 0 · ReadReads outside contenttelegram_get_chat

  Get a chat's type, title or name, username and description.

• Download a fileTier 0 · ReadReads outside contenttelegram_get_file

  Save a file someone sent the bot (photo, document, voice note) to the company's files. Up to 10 MB (the company files limit).

What can start work

These events from Telegram can become tasks for your agents through Intake. How Intake works.

Someone sent the bot a message, or wrote in a group where the bot can read messages.

Connect Telegram first. Then, on the Intake page, open Webhooks and sources, find the connection under Connections without an address yet and select Get its URL. Give that address to Telegram as the setup steps above describe: Everdeck shows it only once. Then, on the Rules tab, select New rule to say which requests become tasks and who gets them.

Testing, problems and disconnecting

Everdeck checks the connection when you save it. On the connection’s page in Integrations, Test checks it again at any time.

If Telegram later refuses the connection, for example because a key was deleted or a sign-in expired, the connection shows Needs attention on the Integrations page and the people who manage connections are told. Agents can’t use it until a company admin fixes it with Edit.

To stop agents using Telegram, open the connection and select Disconnect. Agents stop using it at once and its saved credentials are deleted. What else happens depends on how it was connected: each way above says.