Custom notifications using Amazon Q Developer in chat applications

You can customize messages for your application events or customize default AWS service notifications in Amazon Q Developer 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 @Amazon Q preferences in your chat channel.

Topics

• Generating custom notifications

• Event schema

• Custom notification content guidelines

• Testing a custom notification using Amazon Q Developer in chat applications

• Sample custom notifications

• OpenAPI schema

Generating custom notifications

You can generate custom notifications from Lambda functions, your applications, or by using Amazon EventBridge input transformers to modify existing EventBridge events into an Amazon Q Developer 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 Amazon Q Developer configuration. Custom notifications use the same Amazon Simple Notification Service-based mechanisms as Amazon Q Developer default notifications delivered in your chat channels. There are no additional costs to use custom notifications.

Event schema

Amazon Q Developer 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, Amazon Q Developer 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.

Custom notification content guidelines

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 Amazon Q Developer.” to differentiate them from default notifications.

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:test
              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