> For the complete documentation index, see [llms.txt](https://kb.craftformswp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kb.craftformswp.com/documentation/form-building/general-settings/integrations/telegram.md). # Telegram CraftForms can send a Telegram message every time a form is submitted. The message lands in your own chat, a group or a channel, with the visitor's answers and buttons under it: **Open entry** opens the submission in your WordPress admin, and you can add buttons such as **WhatsApp** or **Telegram** that start a chat with the visitor in one tap. It works with your own Telegram bot. You make the bot in Telegram in two minutes, paste its token into CraftForms once, and add a **Telegram** action to any form or flow. Nothing goes through our servers. ![The Telegram action in a form's Submit Actions, with a chat ticked and the message and buttons below](https://97821998-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM2yV1foUgoGHBC66VBDw%2Fuploads%2FuOhiwSshs6c6JgA5216m%2Ftelegram--telegram-action.jpg?alt=media) ### What you need * **CraftForms (free)**, version 2.3 or later. The Telegram integration is in the free version. * A Telegram account, on your phone or computer. * An administrator or shop manager account to set up the connection. Form editors can then pick it in their forms. ### Step 1: Create your bot 1. In Telegram, open a chat with **@BotFather** (the official bot for making bots, with a blue tick). 2. Send `/newbot`. 3. Give the bot a name (shown in chats, e.g. "Bright Kitchens Website") and a username that ends in `bot` (e.g. `brightkitchens_site_bot`). 4. BotFather answers with a **token**, a long code like `123456789:AA…`. Copy it. Treat it like a password: anyone with the token can send messages as your bot. ### Step 2: Let the bot write to your chat A Telegram bot can't start a conversation. It can only write to chats that know it: | Where you want the messages | What to do | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Your own chat** | Open your bot in Telegram and send it anything ("hi" is fine). | | **A group** (you and your team) | Add the bot to the group, then send a message in the group. | | **A channel** | Add the bot to the channel as an **administrator** (it needs permission to post), then post something in the channel. | Do this before you pick the chat in CraftForms (step 4). If the bot hasn't heard from a chat, that chat isn't in the list. ### Step 3: Connect the bot to CraftForms 1. Go to **CraftForms → Settings** and open the **Integrations** tab. 2. On the **Telegram** card, click **Connect** (or **Add another** if you already have a bot connected). 3. **Name**: a name you'll recognise in the form editor, e.g. "Office Telegram". 4. **Bot token**: paste the token from BotFather. 5. Click **Save & test**. ![The Connect Telegram dialog with Name and Bot token](https://97821998-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM2yV1foUgoGHBC66VBDw%2Fuploads%2F1oQ7OpAqM5EiLaUP66Cv%2Ftelegram--connect-telegram.jpg?alt=media) CraftForms checks the token with Telegram and shows **Connected to @yourbot.** The connection appears in the table below the cards with the status **Verified**. Use **Test** to check it again, **Edit** to change it and **Delete** to remove it. ![The Telegram card and the connections table with a Verified Telegram connection](https://97821998-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM2yV1foUgoGHBC66VBDw%2Fuploads%2FNz5pUxn3cwQxPLw87fC7%2Ftelegram--integrations-connections.jpg?alt=media) The token is encrypted in your database and never shown again in full. When you edit the connection, leave the token empty to keep the current one. Form editors can choose the connection but can't see the token. **Two bots?** Add one connection per bot, for example one for the shop and one for bookings. ### Step 4: Add the Telegram action to a form 1. Open your form (**CraftForms → Forms → Edit**). 2. In the right sidebar, open **Submit Actions** and click **Add Action**. 3. Type *telegram* in the search box (or look under **Chat & SMS**) and choose **Telegram**. 4. Fill in the settings below and click **Save**. 5. Save the form. | Setting | What it does | | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Connection** | The bot to send with. It shows **Verified** when the connection works. **Manage connections ↗** opens Settings → Integrations in a new tab; click the reload icon next to the list when you come back. | | **Chats** | Tick the chats to send to. You can tick several: each gets the same message. The list shows each chat's name and its kind, *(person)*, *(group)* or *(channel)*. Missing one? Write to the bot from that chat (step 2), then click the reload icon next to **Chats**. | | **Message** | The text of the message, with merge tags. Default: `New request from {{email.name}}` and, below it, `{{all_fields.text}}` (every answer, one per line). Click the tags icon to insert a field. | | **Buttons** | Buttons under the message, one per line as \`Label | | **Send silently (no sound)** | The message arrives without a notification sound. Handy for a busy group. | | **Run after the visitor's response is sent (recommended)** | On by default. The visitor sees your confirmation straight away and doesn't wait for Telegram. | | **Required (abort on failure)** | Off by default. When on, a failed message stops the remaining actions and shows the error to the visitor. Leave it off for notifications. | | **Context prefix** | Lets later actions use the result, e.g. `{{telegram.message_id}}`. You can leave it as it is. | | **Run only if** | Send only when a choice field has a certain value, e.g. only when "Subject" is *Request a Quote*. See [Run only if: conditional submit actions](/documentation/form-building/create-form/form-settings-post-context/submit-actions/run-only-if-conditional-actions.md). | There's no field mapping for Telegram: the message is everything that's sent. #### Writing the message The message is plain text. Merge tags are replaced with the visitor's answers, and links in the text are clickable in Telegram. For example: ``` New enquiry from {{email.name}} ({{email.subject}}) Phone: {{email.phone}} {{email.message}} ``` * `{{email.}}` is one answer, e.g. `{{email.phone}}`. For a choice field you get the label the visitor saw ("Request a Quote"), not its value. See [Dynamic Tags and Variables](/documentation/form-building/create-form/dynamic-tags-and-variables.md). * `{{all_fields.text}}` is every answer as `Label: answer` lines. * `{{submission.id}}` is the submission's number. It is filled only when the form has a **Save Submission** action above the Telegram action. * HTML is removed, so a visitor typing `` or `_` can't break the message. * A message longer than Telegram's 4,096 characters is sent as several messages, cut at a line break. The buttons go under the last one. #### Buttons Write one button per line, with the label, a `|`, and the link: ``` Open entry | {{site.url}}/wp-admin/admin.php?page=craftforms_submissions&submission={{submission.id}} WhatsApp | https://wa.me/{{email.phone}} Telegram | https://t.me/{{email.phone}} ``` * **Open entry** opens **Submissions** in your admin with that entry's details open (you need to be logged in). It needs a **Save Submission** action above the Telegram action. * **WhatsApp** and **Telegram** links with a phone number are cleaned for you: `https://wa.me/+44 7700 900123` becomes `https://wa.me/447700900123`. So `{{email.phone}}` works as the visitor typed it. * Telegram only accepts web links (`https://…`, `http://…`) and `tg://` links in buttons. A line with any other link, such as `mailto:` or `tel:`, is left out. Put an email address or phone number in the message text instead. * Labels longer than 64 characters are shortened. Lines without a `|` are ignored. ### In a flow With CraftForms PRO, **Telegram** is also a step in [Flows](/documentation/form-building/flows.md), including flows that start from WooCommerce orders. Use it after a **Wait** step for a reminder ("Emma wrote an hour ago, still no answer?"), or after a **Notion** step with `{{notion.url}}` in the message so the team can open the new Notion page from Telegram. ### Check what was sent Every message shows up in **Settings → Integrations → Activity** with the status **Sent**, **Failed**, **Skipped** or **Retrying**, the form and the reason for any failure. A failed message can be sent again with **Retry now** when the cause was temporary (Telegram was down or asked to slow down). With CraftForms PRO, temporary failures are retried automatically. | Message in Activity | What to do | | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | | *Telegram refused the bot token. Paste it again under Settings → Integrations.* | The token is wrong or was revoked in BotFather. Edit the connection and paste the current token. | | *The bot can't write to this chat: write to the bot from it first, or add the bot to the group.* | The bot was never in that chat. Do step 2 for it. | | *The bot was blocked or removed from this chat.* | Someone blocked the bot or removed it from the group, or it lost its admin rights in the channel. Add it back. | | *Choose a chat in the action.* | No chat is ticked in the action. | ### Good to know * **Your bot, your data.** Messages go straight from your site to Telegram's servers with your bot's token. CraftForms has no relay in between, and no Telegram account of ours is involved. * **Messages only go one way.** The bot posts; it doesn't read replies or act on them. Reply to the visitor with the WhatsApp or Telegram button, or by email. * **The chat list remembers.** Telegram only keeps a bot's recent messages for 24 hours. CraftForms keeps every chat it has found on the connection, so a quiet group doesn't drop out of the list the next day. * **A channel needs the bot as an admin.** Until it is, the channel doesn't appear in the list, and sending fails. * **Visitor answers end up in Telegram.** Send to chats only people who should see them are in, and say in your privacy notice that enquiries are forwarded to Telegram. ### FAQ **Is the Telegram integration free?** Yes. The connection, the action, buttons and **Retry now** are in the free version. Automatic retries and Telegram steps in Flows are part of PRO. **Can I send one submission to several chats?** Yes. Tick several chats in the action, or add a second Telegram action with its own chats and **Run only if** condition, e.g. bookings to one group, complaints to another. **Can I type a chat ID?** No. Pick from the list. A chat appears there after it has sent your bot a message, or after the bot was added to it. **Will a WhatsApp button work with any phone number format?** Mostly. CraftForms keeps only the digits, so `+44 7700 900123`, `07700 900123` and `(0)7700-900123` all become a link. WhatsApp needs the international form, so use the [Phone field](/documentation/form-building/create-form/blocks/phone-field.md), which saves numbers with the country code. **Do I need a Telegram Business or paid account?** No. Bots are free in Telegram.