Custom notifications - AWS Chatbot

Custom notifications

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.

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.

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

version

Yes

Must be 1.0.

source

Yes

Must be custom.

id

No

Unique event identifier.

textType

No

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.

title

No

Supports markdown content, including emojis and Slack @mentions using user IDs, for example @userID.

Maximum length is 250 characters.

description

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.

nextSteps

No

Used to communicate next step recommendations. Rendered as a bulleted list and supports markdown.

Each individual step in the nextSteps list has a maximum length of 350 characters.

keywords

No

Used to communicate event tags and categories. Rendered as an inline list of tags.

Each individual keyword in the keywords list has a maximum length of 75 characters.

metadata

No

Additional metadata about the event.

threadId

No

Used to thread messages in Slack and Microsoft Teams. Custom notifications with the same threadId value are grouped together.

summary

No

Displays a summary on the top-level message when notifications are threaded.

eventType

No

Specifies the type of event for the custom notification (future release).

relatedResources

No

An array of strings describing resources related to the custom notification (future release).

additionalContext

No

A String-to-String dictionary used to provide additional information about your custom notification.

Note
  • eventType and relatedResources will be available in a future release.

  • @mentions for Microsoft Teams aren't currently supported.

Creating notification content

Content created for custom notifications should utilize chat client specific syntax. For example, if you want text in your custom notification in Slack to be bold, use Slack markdown. For more information on Slack and Microsoft Teams markdown, see Format your messages and Use Markdown formatting in Microsoft Teams respectively.

You can add chat platform compatible emojis in your custom notifications. You can also tag team members using @mentions in your custom notifications for Slack. Tagged team members are notified when the custom notification is delivered to the chat channel. To tag a team member in Slack, use their user ID. For example, <@userID>. Tagging team members in Microsoft Teams isn't currently supported.

Note

All custom notifications contain the footer “📬 Custom notification delivered by AWS Chatbot.” to differentiate them from default notifications.

Sending a custom notification

You can create custom notification content and post the message to the Amazon SNS topic used in your AWS Chatbot configuration. AWS Chatbot monitors the Amazon SNS topic and sends the custom notification to your configured channel.

Note

You can also customize notifications generated by Amazon EventBridge by using AWS Chatbot's event schema in Input transformers. For more information, see Tutorial: Use input transformer to customize what Amazon EventBridge passes to the event target in the EventBridge User Guide.

To send a custom notification to a chat channel
  1. Open the Amazon SNS console.

  2. Select the topic used in your AWS Chatbot configuration.

  3. Choose Edit.

  4. Ensure your topic is standard.

  5. Choose Save changes.

  6. Choose Publish message.

  7. In Message body, enter a JSON object using the custom notifications event schema.

  8. Choose Publish message.

  9. View your custom notification in your chat channel.

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