About this plugin
This plugin lets you send Contact Form 7 messages to Telegram chats via a bot. Setup takes just a few steps:
- Create a Telegram bot ( how to ).
- Create a bot in the plugin UI.
- Paste the bot token into the bot form (PHP constants also available).
- Create a bridge in the plugin UI. A bridge links Contact Form 7 forms, a Telegram bot, and one or more Telegram recipients.
- Keep the Contact Form 7 → CF7 Telegram settings page open while sending the bot’s displayed /cf7tg_start@BotName command as a new standalone message. The page checks Telegram for new recipients. To add a group, first add the bot to the group, then send the command there. To add a forum topic, send it inside that topic. The @BotName suffix addresses the correct bot when Telegram group privacy mode is enabled. The short /cf7tg_start command is still supported when Telegram delivers it to the bot; editing an existing message does not register a recipient.
- Approve or decline the subscription requests that appear on the settings page.
- Configure the bridge: choose which forms it handles and which Telegram recipients should receive those messages. After approving a topic, select it in each desired bridge; approving it alone does not assign it to bridges. Create at least one bridge to run the integration, and add more when different forms should send messages to different sets of Telegram recipients.
The integration is configured correctly when the bot panel is highlighted in blue and the bridge panel is highlighted in green.
Read-only Abilities API
9 or newer, three read-only abilities expose saved configuration and sanitized recent log events without sending to Telegram: cf7-telegram/get-configuration, cf7-telegram/diagnose-form, and cf7-telegram/get-recent-errors. Older WordPress versions continue to deliver forms without the Abilities API. A logged-in user needs the existing CF7 Telegram settings capability to read configuration or diagnose a form, plus permission to read each involved form, bridge, bot, and recipient.
Lists omit objects the user cannot read and count only visible items; diagnosis rejects a form when any existing object in its bounded route graph is hidden. Reading the shared log additionally requires manage_options; both capabilities are required. Anonymous users cannot run these abilities.
In PHP, after WordPress has initialized:
wp_get_ability( 'cf7-telegram/get-configuration' )->execute( [ 'resource' => 'forms', 'page' => 1, 'per_page' => 50 ] ); wp_get_ability( 'cf7-telegram/diagnose-form' )->execute( [ 'form_id' => 123 ] ); wp_get_ability( 'cf7-telegram/get-recent-errors' )->execute( [ 'since' => 1761782400, 'until' => 1761868800, 'limit' => 20 ] );
For authenticated REST clients, use GET with a JSON-encoded input query parameter. WordPress Application Passwords or normal cookie and REST nonce authentication work; the plugin adds no separate credential:
input=%7B%22since%22%3A1761782400%2C%22until%22%3A1761868800%2C%22limit%22%3A20%2C%22before_id%22%3A456%7D
The resource is forms, bridges, bots, or recipients. Results use schema version 1 and pages of up to 100 visible items, ordered by WordPress ID. Recipient IDs are local WordPress IDs; a forum topic keeps its distinct message_thread_id.
Bot token presence and cached online/offline status are saved-state observations only.
Recent errors accepts inclusive Unix UTC since and until bounds (default: the past 24 hours), min_level 0–3 (default: 1), and limit 1–100 (default: 20). Pages are ordered by descending log ID. Pass the returned next_before_id as before_id with the same time bounds to get the next page; null means there are no more matching rows.
The example cursor 456 is illustrative. The response reports the current retention days and max_rows, including overrides from WPCF7TG_LOG_RETENTION_DAYS, WPCF7TG_LOG_MAX_ROWS, cf7tg/logRetentionDays, and cf7tg/logMaxRows. Reads do not prune the log.
history_complete is always false: the shared log omits successes and may have lost older entries to retention. Events are telegram_delivery_failed, bot_unreachable, bot_token_missing, bridge_bot_missing, or other. Some bot-unavailable entries have level 0 and require min_level: 0; the default level 1 is not a complete error list.
Unknown or malformed old entries have generic messages, and no raw log data is exposed.
The optional official WordPress MCP Adapter exposes these abilities through its default server. With that separate plugin installed, a local MCP client can run wp mcp-adapter serve --server=mcp-adapter-default-server --user=admin using STDIO. Discover the abilities with mcp-adapter-discover-abilities, inspect their schemas with mcp-adapter-get-ability-info, then call mcp-adapter-execute-ability with {"ability_name":"cf7-telegram/diagnose-form","parameters":{"form_id":123}}.
The server applies the WordPress user’s permissions. The adapter is not required for PHP or REST use; this plugin does not include an MCP server.
Diagnosis is static: ready means the saved route has eligible active recipients, partial means eligible and broken paths coexist, and blocked means no eligible path remains. cached_bot_offline is only a warning. delivery_verified is always false: diagnosis does not contact Telegram, submit a CF7 form, prove that a message arrived, change configuration, or repair a route.
Existing form delivery remains the way to test end-to-end behavior.
Hooks and constants
Filter wpcf7tg_skip_tg
Use it to skip sending a Telegram message.
Filter wpcf7tg_markdown
Use it to customize the allowed Markdown tags.
Filter wpcf7tg_sendMessage( $args, $chat_id, $mode )
Use it to customize Telegram sendMessage arguments for each recipient and message chunk.
Action wpcf7tg_message_sent( $args, $submission )
Runs after each Telegram delivery attempt. A Telegram failure does not abort the Contact Form 7 submission.
Action wpcf7tg_messages_sent( $list, $output, $mode, $submission )
Runs after all configured recipients have been attempted.
Constant WPCF7TG_LOG_RETENTION_DAYS and filter cf7tg/logRetentionDays
Set the log retention period in days. The default is 30; set it to 0 to disable age-based pruning.
Constant WPCF7TG_LOG_MAX_ROWS and filter cf7tg/logMaxRows
Set the maximum number of newest log rows to retain. The default is 10000.
Constants WPCF7TG_PING_INTERVAL and WPCF7TG_UPDATES_INTERVAL
Set the offline bot status retry interval and the online Telegram update polling interval in milliseconds. The defaults are 5000 and 12000 respectively.
This plugin uses API Telegram and sends remote HTTP requests to Telegram servers to deliver notifications.