Telegram Bot — Splunk SOAR App

1. Overview

The Telegram Bot app for Splunk SOAR enables SOC teams to interact with Telegram directly from SOAR playbooks. It supports sending alerts, managing groups, running polls, interactive Q&A with analysts, banning malicious users, and retrieving chat history — all via the Telegram Bot API.

Use Cases

SOC Alerting: Send formatted security alerts with severity levels and IOC details to a Telegram SOC channel
Analyst Interaction: Ask questions with inline buttons and wait for analyst response (approval workflows)
Incident Communication: Forward evidence, screenshots, and documents to stakeholders
Group Management: Create incident-specific groups, manage members, set topics
Phishing Response: Ban reported accounts, delete malicious messages
Polling: Run quick team polls for incident triage decisions

2. Prerequisites

Python Dependencies (auto-installed)

Package	Purpose
requests	HTTP calls to Telegram Bot API

System Dependencies

None — the app uses only pure Python packages and the Telegram Bot API over HTTPS.

Telegram Bot Setup

Open Telegram and message @BotFather
Send /newbot and follow the prompts to create a bot
Copy the API Token (format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
Add the bot to your target group/channel and make it admin if you need group management features
To get a Chat ID, send a message to the bot, then visit: https://api.telegram.org/bot<TOKEN>/getUpdates

3. App Installation

Go to SOAR UI → Apps → Install App
Upload telegram_bot_v1.0.0.tar
Wait for installation to complete (pip dependencies are installed automatically)
Create a new Asset:
- Asset Name: e.g. telegram_soc_bot
- Bot Token: paste the token from BotFather
- Default Chat ID (optional): your SOC channel chat ID
- Timeout: 30 (default)
Click Test Connectivity — should show Connected as @your_bot_name

4. Test Connectivity

Success Output

Validating Bot Token via getMe...
Connected as @your_bot_name (ID: 123456789)
Test Connectivity Passed — Bot: @your_bot_name

Common Errors

Error	Cause	Fix
`401: Unauthorized`	Invalid bot token	Check token in BotFather
`Cannot connect to Telegram API`	Firewall blocking `api.telegram.org`	Allow HTTPS to `api.telegram.org:443`
`Request timed out`	Network issue or proxy	Increase timeout or check proxy settings

5. Actions

send message

Send a text message to any chat/group/channel.

Parameter	Type	Required	Description
chat_id	string	Yes	Target chat ID or @username
message	string	Yes	Message text
parse_mode	string	No	`MarkdownV2`, `HTML`, or empty
disable_notification	boolean	No	Send silently
reply_to_message_id	numeric	No	Message ID to reply to

send document

Send a file from the SOAR Vault.

Parameter	Type	Required	Description
chat_id	string	Yes	Target chat ID
vault_id	string	Yes	SOAR Vault ID
caption	string	No	File caption
parse_mode	string	No	Caption formatting

send photo

Send an image from the SOAR Vault.

Parameter	Type	Required	Description
chat_id	string	Yes	Target chat ID
vault_id	string	Yes	SOAR Vault ID of the image
caption	string	No	Photo caption

get messages

Retrieve recent messages via getUpdates.

Parameter	Type	Required	Description
chat_id	string	No	Filter by chat ID
limit	numeric	No	Max messages (1-100, default 10)
offset	numeric	No	Update offset for pagination

create group

Create a new supergroup and invite members.

Parameter	Type	Required	Description
title	string	Yes	Group name
user_ids	string	Yes	Comma-separated user IDs

get chat info

Get detailed information about a chat.

Parameter	Type	Required	Description
chat_id	string	Yes	Chat ID or @username

get chat members

Get the member count of a chat.

Parameter	Type	Required	Description
chat_id	string	Yes	Chat ID or @username

send poll

Send a poll or quiz to a chat.

Parameter	Type	Required	Description
chat_id	string	Yes	Target chat ID
question	string	Yes	Poll question
options	string	Yes	Comma-separated options (2-10)
is_anonymous	boolean	No	Anonymous poll (default: true)
poll_type	string	No	`regular` or `quiz`
correct_option_id	numeric	No	Correct answer index (quiz only)
allows_multiple_answers	boolean	No	Multiple selections allowed

delete message

Delete a message from a chat.

Parameter	Type	Required	Description
chat_id	string	Yes	Chat ID
message_id	numeric	Yes	Message to delete

edit message

Edit a message sent by the bot.

Parameter	Type	Required	Description
chat_id	string	Yes	Chat ID
message_id	numeric	Yes	Message to edit
new_text	string	Yes	New message text
parse_mode	string	No	Formatting

forward message

Forward a message between chats.

Parameter	Type	Required	Description
from_chat_id	string	Yes	Source chat
to_chat_id	string	Yes	Destination chat
message_id	numeric	Yes	Message to forward

pin message

Pin a message in a chat.

Parameter	Type	Required	Description
chat_id	string	Yes	Chat ID
message_id	numeric	Yes	Message to pin
disable_notification	boolean	No	Pin silently

unpin message

Unpin a message or all pinned messages.

Parameter	Type	Required	Description
chat_id	string	Yes	Chat ID
message_id	numeric	No	Specific message (empty = unpin all)

set chat title

Change the title of a group/channel.

Parameter	Type	Required	Description
chat_id	string	Yes	Chat ID
title	string	Yes	New title (1-128 chars)

set chat description

Change the description of a group/channel.

Parameter	Type	Required	Description
chat_id	string	Yes	Chat ID
description	string	No	New description (empty to remove)

ban user

Ban a user from a group/channel.

Parameter	Type	Required	Description
chat_id	string	Yes	Chat ID
user_id	numeric	Yes	User to ban
until_date	numeric	No	Unix timestamp (0 = permanent)
revoke_messages	boolean	No	Delete user's messages

unban user

Unban a previously banned user.

Parameter	Type	Required	Description
chat_id	string	Yes	Chat ID
user_id	numeric	Yes	User to unban

get webhook info

Get current webhook configuration.

No parameters required.

set webhook

Set or remove the webhook URL.

Parameter	Type	Required	Description
url	string	No	HTTPS webhook URL (empty to remove)
allowed_updates	string	No	Comma-separated update types

send alert

Send a formatted security alert with severity and IOC details.

Parameter	Type	Required	Description
chat_id	string	No	Target chat (uses default if empty)
severity	string	Yes	critical, high, medium, low, informational
title	string	Yes	Alert headline
description	string	Yes	Alert details
ioc_type	string	No	ip, domain, hash, url, email, other
ioc_value	string	No	The IOC value
source	string	No	Source system name

ask question

Send a question with inline buttons and wait for response.

Parameter	Type	Required	Description
chat_id	string	Yes	Target chat
question	string	Yes	Question text
options	string	Yes	Comma-separated answer options
timeout_seconds	numeric	No	Wait timeout (default: 300s)

get user info

Get profile info for a chat member.

Parameter	Type	Required	Description
chat_id	string	Yes	Chat where user is member
user_id	numeric	Yes	User ID

leave chat

Make the bot leave a group/channel.

Parameter	Type	Required	Description
chat_id	string	Yes	Chat to leave

create invite link

Create an invite link for a group/channel.

Parameter	Type	Required	Description
chat_id	string	Yes	Chat ID
name	string	No	Link label
expire_date	numeric	No	Unix timestamp for expiry
member_limit	numeric	No	Max joins (1-99999)

6. Widget Display

The get messages action includes a custom widget for the Investigation panel.

Activation

Open an event → Investigation tab
Click Manage Widgets (gear icon)
Find Telegram Bot → toggle On
Click Save Layout

7. Local Testing

SSH into the SOAR appliance and create a test file:

cat > /tmp/test_send_message.json << 'EOF'
{
  "identifier": "send_message",
  "asset_id": "1",
  "parameters": [{
    "chat_id": "-1001234567890",
    "message": "Test from SOAR",
    "parse_mode": ""
  }],
  "config": {
    "bot_token": "YOUR_BOT_TOKEN_HERE"
  }
}
EOF

cd /opt/phantom/apps/telegram_bot_*/
phenv python3 telegram_bot_connector.py /tmp/test_send_message.json

8. Troubleshooting

Problem	Solution
`401: Unauthorized`	Regenerate token with BotFather
`400: Bad Request: chat not found`	Bot is not a member of the chat — add it first
`403: Forbidden: bot was blocked by the user`	User blocked the bot — they must unblock
`403: Forbidden: bot is not a member`	Add bot to the group/channel
`429: Too Many Requests`	Rate limited — reduce frequency or add delay
Widget not showing	Activate via Manage Widgets → Telegram Bot → On
`ask question` times out	Increase timeout_seconds or check that user clicks inline buttons
Files not sending	Verify vault_id is valid via `vault list` CLI

9. Firewall Requirements

The SOAR appliance must allow outbound HTTPS (TCP 443) to:

api.telegram.org

10. Changelog

Version	Date	Changes
1.0.0	2025-02-25	Initial release — 24 actions

Name		Name	Last commit message	Last commit date
.gitignore		.gitignore
README.md		README.md
__init__.py		__init__.py
telegram_bot.json		telegram_bot.json
telegram_bot.svg		telegram_bot.svg
telegram_bot_connector.py		telegram_bot_connector.py
telegram_bot_dark.svg		telegram_bot_dark.svg
telegram_bot_utils.py		telegram_bot_utils.py
telegram_bot_view.html		telegram_bot_view.html
telegram_bot_view.py		telegram_bot_view.py

Latest commit

History

Folders and files

Repository files navigation