You can customize messages for your application events or customize default AWS service notifications in AWS Chatbot using custom notifications.
By customizing notification content, you can promptly receive important application updates with relevant contextual information in your chat channels. This increases visibility for your team and facilitates quicker responses. You can also thread custom notifications
using the threadId
parameter shown in Parameter details. Threaded notifications help you organize notification updates by grouping them in a thread in your chat channel.
Note
To thread notifications, your channel preferences must allow sending notification updates in a thread. You can update your channel preferences by entering @aws preferences
in your chat channel.
You can generate custom notifications from Lambda functions, your applications, or by using Amazon EventBridge input transformers to modify existing EventBridge events into an AWS Chatbot compatible format. If using EventBridge, you map the Amazon SNS topic to the EventBridge rule target and map the topic to a channel used in your AWS Chatbot configuration. Custom notifications use the same Amazon Simple Notification Service-based mechanisms as AWS Chatbot default notifications delivered in your chat channels. There are no additional costs to use custom notifications.
Topics
Event schema
AWS Chatbot custom notifications must use the following event format:
{
"version": String,
"source": String,
"id": String,
"content": {
"textType": String,
"title": String,
"description": String,
"nextSteps": [ String, String, ... ],
"keywords": [ String, String, ... ]
},
"metadata": {
"threadId": String,
"summary": String,
"eventType": String,
"relatedResources": [ String, String, ... ],
"additionalContext" : {
"customerProvidedKey1": String,
"customerProvidedKey2": String
...
}
}
}
Parameter details
Parameter | Required | Description |
---|---|---|
|
Yes |
Must be |
|
Yes |
Must be |
|
No |
Unique event identifier. |
|
No |
Only |
|
No |
Supports markdown content, including emojis and Slack @mentions using user IDs, for example @userID. Maximum length is 250 characters. |
|
Yes |
Makes up the message content of your notification. Supports markdown content, including emojis and Slack @mentions using user IDs, for example @userID. Maximum length is 8,000 characters. |
|
No |
Used to communicate next step recommendations. Rendered as a bulleted list and supports markdown. Each individual step in the |
|
No |
Used to communicate event tags and categories. Rendered as an inline list of tags. Each individual keyword in the |
|
No |
Additional metadata about the event. |
|
No |
Used to thread messages in Slack and Microsoft Teams. Custom notifications with the same threadId value are grouped together. |
|
No |
Displays a summary on the top-level message when notifications are threaded. |
|
No |
Specifies the type of event for the custom notification (future release). |
|
No |
An array of strings describing resources related to the custom notification (future release). |
|
No |
A String-to-String dictionary used to provide additional information about your custom notification. |
Note
-
eventType
andrelatedResources
will be available in a future release. -
@mentions for Microsoft Teams aren't currently supported.
Sample custom notifications
Minimalist custom notification
The following custom notification example creates a simple notification that contains only mandatory schema parameters when published to an Amazon SNS topic.
{
"version": "1.0",
"source": "custom",
"content": {
"description": ":warning: EC2 auto scaling refresh failed for ASG *OrderProcessorServiceASG*! \ncc: @SRE-Team"
}
}
Complex custom notification
The following custom notification example creates a complex notification when published to an Amazon SNS topic.
{
"version": "1.0",
"source": "custom",
"id": "c-weihfjdsf",
"content": {
"textType": "client-markdown",
"title": ":warning: Banana Order processing is down!",
"description": "Banana Order processor application is no longer processing orders. OnCall team has beeen paged.",
"nextSteps": [
"Refer to <http://www.example.com|*diagnosis* runbook>",
"@googlie: Page Jane if error persists over 30 minutes",
"Check if instance i-04d231f25c18592ea needs to receive an AMI rehydration"
],
"keywords": [
"BananaOrderIntake",
"Critical",
"SRE"
]
},
"metadata": {
"threadId": "OrderProcessing-1",
"summary": "Order Processing Update",
"eventType": "BananaOrderAppEvent",
"relatedResources": [
"i-04d231f25c18592ea",
"i-0c8c31affab6078fb"
],
"additionalContext": {
"priority": "critical"
}
}
}
OpenAPI schema
If you use OpenAPI, you can use the following OpenAPI schema to generate custom notification resources for use in source code.
openapi: 3.0.0
info:
title: Custom Notifications Payload Schema
version: 1.0.0
components:
schemas:
CustomNotifications:
type: object
required:
- version
- source
- content
properties:
version:
type: string
description: Must be "1.0"
enum:
- "1.0"
source:
type: string
description: Must be "custom"
enum:
- "custom"
id:
type: string
description: Unique event identifier
content:
type: object
required:
- description
properties:
textType:
type: string
description: Only "client-markdown" textType is currently supported. When textType=client-markdown, AWS Chatbot renders notifications in the target chat platform's markdown. For example, "Example text 123" in Slack notification content would be formatted using Slack's markdown style.
enum:
- "client-markdown"
title:
type: string
description: Supports markdown content, including emojis and @mentions.
description:
type: string
description: Makes up the message content of your notification. Supports markdown content, including emojis and @mentions.
nextSteps:
type: array
description: Used to communicate next step recommendations. Rendered as a bulleted list and supports markdown.
items:
type: string
keywords:
type: array
description: Used to communicate event tags and categories. Rendered as an inline list of tags.
items:
type: string
metadata:
type: object
properties:
threadId:
type: string
description: Used for threading messages for chat clients that support it. Custom notifications with the same threadId value will be grouped together.
summary:
type: string
description: Used for displaying a summary on the top-level message when notifications are threaded.
eventType:
type: string
description: Specifies the type of event for the custom notification. (Future release)
relatedResources:
type: array
description: An array of strings describing resources related to the custom notification. (Future release)
items:
type: string
additionalContext:
type: object
description: A String-to-String dictionary customers can use to provide additional information about their custom notification.
additionalProperties:
type: string