Notification Component

The Notification component allows your script to send notifications to the user. This includes standard desktop notifications as well as messages to external services like Discord, Telegram, and Email.

Usage

When implementing your script's onStart, execute, or onFinish methods, you can access the Notification component through the provided ComponentProvider.

The notification DSL function is used to construct the notification object, which is then sent using the sendNotification method.

import com.cereal.sdk.component.notification.notification

suspend fun execute(provider: ComponentProvider) {
    val notificationComponent = provider.notification()

    // Create a notification using the DSL
    val myNotification = notification("Your order has been successfully processed") {
        // Optional title for desktop notification
        title { "Purchase Complete" }

        // Optional Discord message
        discordMessage {
            content { "Order #12345 has been processed." }
            // You can also add embeds, username, avatarUrl, etc.
        }

        // Optional Telegram message
        telegramMessage {
            text { "Order #12345 processed." }
            chatId { "your-chat-id" }
        }

        // Optional Email message
        emailMessage {
            subject { "Order processed" }
            body { "Order #12345 has been successfully processed." }
            to { "[email protected]" }
        }
    }

    // Send the notification
    notificationComponent.sendNotification(myNotification)
}

Supported Channels

The Notification component supports the following channels:

• Desktop Notification: Displays a system-level notification to the user.
• Discord: Sends a message to a configured Discord webhook.
• Telegram: Sends a message to a configured Telegram bot/chat.
• Email: Sends an email to a configured address.

Note: The user must configure the respective external services (Discord Webhook URL, Telegram Bot Token/Chat ID, Email settings) in the Cereal application settings for these channels to work.

Discord DSL

discordMessage {
    content { "Your message text" }
    username { "MyScript Bot" }
    avatarUrl { "https://example.com/avatar.png" }
    webhookUrl { "https://discord.com/api/webhooks/..." } // override the user's configured webhook
    embed {
        title { "Order Complete" }
        description { "Order #12345 was processed." }
        color { "#00FF00" }
        field {
            name = "Item"
            value = "Product Name"
            inline = true
        }
    }
}

Telegram DSL

telegramMessage {
    text { "Your message text" }           // required
    chatId { "your-chat-id" }              // override the user's configured chat ID
    botToken { "your-bot-token" }          // override the user's configured bot token
    parseMode { TelegramParseMode.HTML }   // HTML, MARKDOWN, or MARKDOWN_V2
    disableNotification { false }
    disableWebPagePreview { true }
}

Email DSL

emailMessage {
    subject { "Alert" }                    // required
    body { "Message body text" }           // required
    to { "[email protected]" }
    from { "[email protected]" }
    smtpHost { "smtp.example.com" }
    smtpPort { 587 }
    username { "smtp-user" }
    password { "smtp-password" }
    useTls { true }
}

Important Considerations

• Best Effort Delivery: Users can disable notifications globally or for specific channels. There is no guarantee that the user will receive or see the notification.
• Urgency: Desktop notifications attract immediate attention. Use them only for important events.
• Logging: For general status updates or debugging information, use the Logger component instead.

Best Practices

Notifications are most appropriate for:

• Time-sensitive actions requiring user input.
• Completion of long-running processes.
• Critical errors that require immediate attention.
• Important status updates (e.g., successful purchases).