Core Forms
Get Core Forms

Telegram Integration

Send form notifications to a personal chat, group, channel, or forum topic through your own Telegram bot.

Action type: telegram

Connect your bot

  1. Open @BotFather in Telegram and create a bot with /newbot.
  2. Copy its token. In Core Forms, open your form's Actions tab and add Send to Telegram.
  3. Paste the token into Bot token. Tokens are masked; use Show token only when you need to check it.
  4. Select Verify bot. Core Forms displays the connected bot's username. Verification does not send a message or prove that the bot can post to a particular destination.

Bot verification, chat discovery and test sending require a site administrator. A configured action can run normally on submission without an administrator being present.

Choose a destination

  • Personal chat: Open your bot and press Start, then select Find chats in Core Forms. Choose your chat from the results. A personal @username is not a replacement for the numeric chat ID.
  • Group: Add the bot to the group and send /start@YourBotUsername. Select Find chats, then choose the group. Group IDs are usually negative numbers.
  • Public channel: Add the bot as an administrator with permission to post. Enter @yourchannel directly, or select it from discovery if a recent channel update is available.
  • Private channel: Add the bot with posting permission and enter the numeric chat ID. Recent channel updates may also make it available through Find chats.
  • Forum topic: Select a discovered topic, or enter its Topic ID alongside the chat ID. Leave Topic ID empty for the default destination.

Discovery reads up to 100 pending updates and returns only destination labels and IDs to the editor. It does not acknowledge updates, change update subscriptions, or send a message. It cannot list every historical chat. If the list is empty, send a fresh command to the bot and try again, or enter the destination manually.

If the bot already has a webhook, Core Forms leaves it intact and asks you to enter the ID manually or use a separate bot. Another application receiving updates may also prevent chat discovery. See Telegram's update-delivery rules.

Write the message

Leave Message empty to include the form title and all submitted fields. For a custom message, use the field picker or variables:

<b>New inquiry</b>
Name: [NAME]
Email: [EMAIL]
Message: [MESSAGE]
  • HTML formatting accepts Telegram-supported markup, including <b>, <i>, <code> and <a>. Submitted values and system-variable replacements are escaped as text, so an ampersand or < in a submitted answer does not break your formatting.
  • Plain text sends the authored characters literally, including any tags you type.
  • [all:label] inserts all submitted fields with labels. Field names must match the form you are editing.
  • Existing actions without an explicit format continue to use HTML.
  • Messages must contain 1–4,096 characters after formatting. Shorten the template or select fewer fields if the rendered message exceeds the limit. Core Forms does not silently truncate it or split it into multiple messages.

The Telegram sendMessage reference describes the destination, topic and formatting parameters.

Send a test

  1. Open Test Telegram message in the action card.
  2. Review Test field values (JSON). Use Use form field samples to populate synthetic values for this form.
  3. Select Send test message. This sends a real message to the configured destination using the current, unsaved settings.
  4. Check the Telegram chat and the result shown in Core Forms.
  5. Save the form to keep the configuration.

Verify bot and Find chats are setup checks; only Send test message sends sample content. Automated development tests use mocked transport and do not establish delivery to a real chat.

Settings reference

Setting Required Behavior
Bot token Yes Token from BotFather; masked in the editor
Chat ID or channel username Yes Numeric chat ID or public destination @username
Topic ID No Positive forum-topic identifier
Message format Yes HTML formatting by default, or Plain text
Message No Empty sends the title and all fields
Run in the background No Uses the shared queue when submissions are saved

Troubleshooting

  • Token rejected: Copy the current token from BotFather. Never paste a full Bot API URL into the token field.
  • Chat not found: Press Start in the personal bot chat, add the bot to the destination, and verify the numeric ID or channel username.
  • Bot cannot post: Unblock the bot or grant the required group/channel posting permission.
  • Formatting error: Check your authored HTML tags or choose Plain text.
  • Topic not found: Check Topic ID, select a discovered topic, or leave the field empty.
  • Group upgraded to a supergroup: Core Forms follows Telegram's replacement chat ID once. After Telegram confirms the send, it updates the matching saved destination without replacing other action settings. If the retry still fails, check the bot's membership and permissions.
  • Rate limited: Wait before retrying. Retryable action failures preserve Telegram's retry delay for the shared retry system when the action has a stored submission.
  • Connection/server error: Check the server's access to api.telegram.org. Requests time out after 15 seconds.

Errors shown in the action log or setup tools do not include the bot token or raw provider response body. A setup check does not save your form; use Save Form after making changes.