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" }
    textToSpeech { false }
    webhookUrl { "https://discord.com/api/webhooks/..." } // override the user's configured webhook
    embed {
        title { "Order Complete" }
        description { "Order #12345 was processed." }
        url { "https://example.com/orders/12345" }
        color { "#00FF00" }                          // hex string or integer
        timestamp { "2024-01-31T12:00:00Z" }         // ISO 8601
        field {
            name = "Item"
            value = "Product Name"
            inline = true
        }
        footer { text { "Sent by MyScript" } }
        author { name { "MyScript" } }
        image { url { "https://example.com/image.png" } }
        thumbnail { url { "https://example.com/thumb.png" } }
    }
}

Call embed { … } more than once to attach multiple embeds, and field { … } more than once to add multiple fields to an embed. Discord's own limits apply and are validated before sending: at most 25 fields per embed, and at most 6000 characters across an embed's title, description, footer text, author name, and field names and values.

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 }
    replyToMessageId { 42 }
}

text is required — building a Telegram message without it throws.

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 }                        // defaults to true
}

subject and body are required — building an email message without either throws.

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).