Telegram

LAST UPDATED: OCTOBER 7, 2025

Overview

Telegram offers users an optional end-to-end encrypted messaging feature so that no one can access the data.

D3 SOAR is providing REST operations to function with Telegram.

Telegram is available for use in:

Known Limitations

• Bots cannot view messages sent by other bots.

• For webhook-related limitations, refer to I'm having problems with Webhooks.

• For message-related limitations, refer to Broadcasting to Users

Connection

To connect to Telegram from D3 SOAR, follow this part to collect the required information below:

Configuring Telegram to Work with D3 SOAR

1. Begin a conversation with BotFather.

   

   1. Navigate to this link.

   2. Click the START BOT button.

   3. Log in when prompted.

2. Send the /newbot command to BotFather to create a new bot.

   

3. Follow the prompts and copy the token provided at the end.

   

   Refer to sub-step 2 under step 3i in Configuring D3 SOAR to Work with Telegram.

Configuring D3 SOAR to Work with Telegram

1. Log in to D3 SOAR.

2. Find the Telegram integration.

   

   1. Navigate to Configuration on the top header menu.

   2. Click on the Integration icon on the left sidebar.

   3. Type Telegram in the search box to find the integration, then click it to select it.

   4. Click on the + Connection button on the right side of the Connections section. A new connection window will appear.

3. Configure the following fields to create a connection to Telegram.

   

   1. Connection Name: The desired name for the connection.

   2. Site: The site on which to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.

   3. Recipient site for events from connections Shared to Internal Sites: This field is displayed when Share to Internal Sites is selected for the Site field, allowing selection of the internal site for deploying the integration connection.

   4. Agent Name (Optional): The proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.

   5. Description (Optional): The description for the connection.

   6. Tenant (Optional): When configuring the connection from a master tenant site, users can choose the specific tenant sites with which to share the connection. Once this setting is enabled, users can filter and select the desired tenant sites from the dropdowns to share the connection.

      

   7. Configure User Permissions: Defines which users have access to the connection.

   8. Active: The checkbox that enables the connection to be used when selected.

   9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.

      

      1. Input the Server URL. The default value is https://api.telegram.org.

      2. Input the API Token from Telegram. This is referring to the bot token. Refer to step 3 in Configuring Telegram to Work with D3 SOAR.

   10. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Refer to the password vault connection guide if needed.

   11. Connection Health Check: Periodically checks the connection status by scheduling the Test Connection command at the specified interval (in minutes). Available only for active connections, this feature also allows configuring email notifications for failed attempts.

4. Test the connection.

   

   1. Click on the Test Connection button to verify credentials and connectivity. A success alert displays Passed with a green checkmark. If the connection fails, review the parameters and retry.

   2. Click OK to close the alert window.

   3. Click + Add to create and add the configured connection.

Configuring for Fetch Event

For this integration, the Fetch Event command supports only the webhook method. Events are ingested automatically from bot updates at the specified URL when the webhook is configured with the Create Webhook command. Scheduled data ingestion is not available with this command.

1. Follow these steps to add an API Key (or use an existing key) for data ingestion.

2. Copy the Request URL, Header Key, and Header Value, then append the Header Key and Value as query parameters to construct a URL that looks like the following: https://company/VSOC/api/Data/Telegram/Security%20Operations/CreateEvents?d3key=123456789

   

3. Paste the constructed URL into the Webhook URL parameter of the Create Webhook command, then execute it.

   

4. Send a test message in Telegram to the authenticated bot and verify that the event is ingested in vSOC.

   

Commands

Telegram includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command function, users can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the Telegram API, refer to the Telegram API reference.

READER NOTE

Fetch Event and Get Updates are mutually exclusive. Get Updates cannot be run while a webhook is configured for Fetch Event, and updates retrieved by one command are not available to the other. Refer to Getting updates for more information.

Create Webhook

The vSOC webhook URL to receive incoming updates through an outgoing webhook. This command must execute successfully to enable event ingestion into vSOC through the Fetch Event command (webhook only).

Input

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Fetch Event

Ingests Telegram updates as D3 events in real time when the authenticated bot receives messages, commands, or files in direct or group chats. Updates are delivered through the webhook set using the Create Webhook command. Scheduled data ingestion is not available for this command. Refer to Configuring for Fetch Event for more information.

Input

N/A

Output

To view the sample output data for all commands, refer to this article.

Fetch Event Field Mapping

See Field Mappings.

The Telegram system integration includes pre-configured field mappings for the default event source.

The Default Event Source is the default system-provided set of field mappings applied when the fetch event command is executed. It includes a Main Event JSON Path, which is the JSONPath expression that points to the base array of event objects. The source field path continues from this array to locate the required data.

The Main Event JSON Path can be viewed by clicking on the Edit Event Source button.

• Main Event JSON Path: $

  The root object represents the event, and the key update_id denotes the Document ID field. As such, the full JSONPath expression to extract the Document ID is $.update_id.

The pre-configured field mappings are detailed below:

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Get Bot

Retrieves basic information on the authenticated bot.

Input

N/A

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Get Updates

Retrieves updates (i.e., messages, commands, or files) from direct or group chats for the authenticated bot. This command cannot be used if a webhook is already configured. Run the Remove Webhook command before executing this command.

Input

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Remove Webhook

Removes the previously configured outgoing webhook.

Input

N/A

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Send Message

Sends a text message to the specified Telegram user, group chat, or public channel. The authenticated bot must be an admin to send messages in a channel.

READER NOTE

Chat ID is a required parameter to run this command.

• Run the Fetch Event or Get Updates command to obtain the Chat ID. Chat IDs for direct and group chats can be found in the raw data at:

  • $.message.chat.id for Fetch Event

  • $.result[*].message.chat.id for Get Updates

• Users can obtain the channel username in the following steps:

  

  1. Open the desired public channel.

  2. Click the icon.

  3. Select the View Channel Info option.

  4. Copy the public channel link without the t.me/ prefix. The remaining portion is the channel username.

  Ensure to add an @ symbol to the copied username before entering it in the Chat ID parameter (i.e., @analystchannel).

Input

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Test Connection

Allows users to perform a health check on an integration connection. Users can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.