Skip to content

Notifications Guide

Xeepy can send notifications through multiple channels to keep you informed about your X/Twitter activity, alerts, and automation results.

Overview

  • :material-discord:{ .lg .middle } Discord

    Webhook notifications to Discord channels

  • Telegram

    Bot messages to Telegram chats

  • Email

    SMTP email notifications

  • Webhooks

    Custom HTTP webhook integrations

  • Console

    Terminal output for local monitoring

Quick Start

from xeepy.notifications import DiscordNotifier

# Create notifier
discord = DiscordNotifier(
    webhook_url="https://discord.com/api/webhooks/..."
)

# Send a message
await discord.send("🚀 Xeepy automation started!")

Discord Notifications

Setup

  1. Create a webhook in your Discord server:
  2. Server Settings → Integrations → Webhooks → New Webhook

  3. Copy the webhook URL

  4. Use in Xeepy:

from xeepy.notifications import DiscordNotifier

discord = DiscordNotifier(
    webhook_url="https://discord.com/api/webhooks/123/abc..."
)

Send Messages

# Simple message
await discord.send("Hello from Xeepy!")

# With formatting
await discord.send("""
**Daily Report** 📊

✅ Followers: 12,456 (+23)
❌ Unfollowers: 5
💬 Engagement: 2.3%
""")

Send Rich Embeds

await discord.send_embed({
    "title": "📊 Daily Analytics Report",
    "color": 0x1DA1F2,  # Twitter blue
    "fields": [
        {"name": "Followers", "value": "12,456 (+23)", "inline": True},
        {"name": "Engagement", "value": "2.3%", "inline": True},
        {"name": "Top Tweet", "value": "My latest thread got 500 likes!", "inline": False}
    ],
    "footer": {"text": "Generated by Xeepy"},
    "timestamp": datetime.now().isoformat()
})

With Images

await discord.send_embed({
    "title": "Growth Chart",
    "image": {"url": "https://your-chart-url.png"}
})

# Or upload file
await discord.send_file("reports/growth_chart.png", "This week's growth")

Telegram Notifications

Setup

  1. Create a bot via @BotFather
  2. Get your chat ID (message @userinfobot)
from xeepy.notifications import TelegramNotifier

telegram = TelegramNotifier(
    bot_token="123456:ABC-DEF...",
    chat_id="your_chat_id"
)

Send Messages

# Simple message
await telegram.send("🔔 New follower: @username")

# With Markdown formatting
await telegram.send("""
*Daily Report* 📊

✅ Followers: `12,456` (+23)
❌ Unfollowers: `5`
💬 Engagement: `2.3%`
""", parse_mode="Markdown")

# With HTML
await telegram.send(
    "<b>Alert!</b> Lost 10 followers in the last hour",
    parse_mode="HTML"
)

Send to Groups

# For group chats, use the group chat ID
telegram = TelegramNotifier(
    bot_token="...",
    chat_id="-100123456789"  # Group IDs are negative
)

Interactive Buttons

await telegram.send_with_buttons(
    "New mention detected! How should I respond?",
    buttons=[
        [{"text": "👍 Like", "callback_data": "like"}],
        [{"text": "💬 Reply", "callback_data": "reply"}],
        [{"text": "🚫 Ignore", "callback_data": "ignore"}]
    ]
)

Email Notifications

Setup

from xeepy.notifications import EmailNotifier

email = EmailNotifier(
    smtp_host="smtp.gmail.com",
    smtp_port=587,
    username="your-email@gmail.com",
    password="your-app-password",  # Use app password for Gmail
    from_email="your-email@gmail.com"
)

Send Emails

# Simple email
await email.send(
    to="recipient@example.com",
    subject="Xeepy Daily Report",
    body="Your daily stats are ready..."
)

# HTML email
await email.send(
    to="recipient@example.com",
    subject="📊 Weekly Analytics",
    html="""
    <h1>Weekly Report</h1>
    <p>Followers: <strong>12,456</strong> (+150)</p>
    <p>Engagement Rate: <strong>2.3%</strong></p>
    """
)

# With attachments
await email.send(
    to="recipient@example.com",
    subject="Monthly Report",
    body="See attached report.",
    attachments=["reports/monthly_report.pdf"]
)

Multiple Recipients

await email.send(
    to=["user1@example.com", "user2@example.com"],
    cc=["manager@example.com"],
    subject="Team Report",
    body="Weekly metrics..."
)

Webhook Notifications

Generic Webhook

from xeepy.notifications import WebhookNotifier

webhook = WebhookNotifier(
    url="https://your-api.com/webhook",
    headers={"Authorization": "Bearer token123"}
)

await webhook.send({
    "event": "unfollower_detected",
    "data": {
        "username": "unfollowed_user",
        "timestamp": datetime.now().isoformat()
    }
})

Slack Integration

from xeepy.notifications import SlackNotifier

slack = SlackNotifier(
    webhook_url="https://hooks.slack.com/services/..."
)

await slack.send("New follower milestone: 10,000! 🎉")

# Rich message
await slack.send_block({
    "blocks": [
        {
            "type": "header",
            "text": {"type": "plain_text", "text": "📊 Daily Report"}
        },
        {
            "type": "section",
            "fields": [
                {"type": "mrkdwn", "text": "*Followers:*\n12,456"},
                {"type": "mrkdwn", "text": "*Change:*\n+23"}
            ]
        }
    ]
})

Zapier/IFTTT Integration

# Zapier webhook
zapier = WebhookNotifier(
    url="https://hooks.zapier.com/hooks/catch/..."
)

await zapier.send({
    "trigger": "new_follower_milestone",
    "followers": 10000
})

# IFTTT webhook
ifttt = WebhookNotifier(
    url="https://maker.ifttt.com/trigger/xeepy_event/with/key/..."
)

await ifttt.send({
    "value1": "10000",
    "value2": "follower milestone"
})

Notification Manager

Manage multiple notification channels:

from xeepy.notifications import NotificationManager

# Create manager
notifications = NotificationManager()

# Add channels
notifications.add_channel("discord", DiscordNotifier(webhook_url="..."))
notifications.add_channel("telegram", TelegramNotifier(token="...", chat_id="..."))
notifications.add_channel("email", EmailNotifier(...))

# Send to all channels
await notifications.broadcast("🚀 Important announcement!")

# Send to specific channels
await notifications.send(
    message="Daily report ready",
    channels=["discord", "email"]
)

Priority-Based Routing

# Configure priority routing
notifications.configure_routing({
    "critical": ["telegram", "email", "discord"],
    "warning": ["discord", "telegram"],
    "info": ["discord"],
    "debug": ["console"]
})

# Send with priority
await notifications.send("Server error!", priority="critical")
await notifications.send("New follower!", priority="info")

Integration with Xeepy

Automatic Notifications

from xeepy import Xeepy
from xeepy.notifications import DiscordNotifier

async with Xeepy() as x:
    # Set up notifications
    x.notifications.add(DiscordNotifier(webhook_url="..."))

    # Enable automatic notifications
    x.notifications.on_error = True        # Notify on errors
    x.notifications.on_milestone = True    # Follower milestones
    x.notifications.on_unfollower = True   # When someone unfollows

    # Run operations - notifications happen automatically
    await x.unfollow.non_followers(max_unfollows=50)

Event-Based Notifications

async with Xeepy() as x:
    discord = DiscordNotifier(webhook_url="...")

    # Register event handlers
    @x.events.on("unfollower")
    async def on_unfollower(user):
        await discord.send(f"😢 @{user.username} unfollowed you")

    @x.events.on("new_follower")
    async def on_new_follower(user):
        await discord.send(f"🎉 New follower: @{user.username}")

    @x.events.on("milestone")
    async def on_milestone(count):
        await discord.send(f"🏆 Milestone reached: {count:,} followers!")

    # Start monitoring
    await x.monitor.start()

Configuration

Environment Variables

# Discord
export DISCORD_WEBHOOK="https://discord.com/api/webhooks/..."

# Telegram
export TELEGRAM_BOT_TOKEN="123456:ABC..."
export TELEGRAM_CHAT_ID="123456789"

# Email
export SMTP_HOST="smtp.gmail.com"
export SMTP_PORT="587"
export SMTP_USER="you@gmail.com"
export SMTP_PASSWORD="app-password"

Config File

# xeepy.toml
[xeepy.notifications]
enabled = true

[xeepy.notifications.discord]
webhook_url = "${DISCORD_WEBHOOK}"
username = "Xeepy Bot"
avatar_url = "https://..."

[xeepy.notifications.telegram]
bot_token = "${TELEGRAM_BOT_TOKEN}"
chat_id = "${TELEGRAM_CHAT_ID}"

[xeepy.notifications.email]
smtp_host = "smtp.gmail.com"
smtp_port = 587
username = "${SMTP_USER}"
password = "${SMTP_PASSWORD}"
from_email = "xeepy@yourdomain.com"
default_to = "you@example.com"

CLI Commands

# Test notifications
xeepy notify test --channel discord --message "Test message"

# Send notification
xeepy notify send "Hello!" --channels discord,telegram

# Configure notifications
xeepy notify setup discord
xeepy notify setup telegram
xeepy notify setup email

Best Practices

  1. Don't over-notify - Only alert on important events
  2. Use appropriate channels - Critical alerts to multiple channels
  3. Include context - Add relevant data to messages
  4. Test your setup - Verify notifications work before relying on them
  5. Secure credentials - Use environment variables for tokens
  6. Rate limit - Don't spam notification channels