Working with chat channels in Incident Manager - Incident Manager
Set up an AWS Chatbot clientConfiguring SNS permissionsEncrypting Amazon SNS topics used by Incident ManagerInteracting through chatBest practices

Working with chat channels in Incident Manager

A key feature of AWS Systems Manager Incident Manager is the ability to directly communicate through chat channels during an incident. During an incident, Incident Manager pushes incident updates and notifications directly to the chat channel to keep all responders informed. Responders can update and interact with the incident directly from the chat channel by using chat commands. For more information about AWS Chatbot, see AWS Chatbot Administrator Guide.

Set up an AWS Chatbot client

Incident Manager uses AWS Chatbot clients to connect responders in Amazon Chime or Slack. Add AWS Chatbot client to a response plan to notify the chat room that an incident started.

Configure an AWS Chatbot client.

  1. Open the AWS Chatbot console, and in the left navigation bar, choose Configured clients.

  2. Choose Configure new client.

  3. Choose Amazon Chime or Slack.

Slack

  1. Choose your workspace from the dropdown list on the top right.

    1. If you're not already signed in to a workspace, choose Sign in to a workspace.

  2. To grant AWS Chatbot permission to access your Slack workspace, choose Allow.

  3. Choose Configure new channel.

  4. Switch to Slack and add the AWS Chatbot app.

    1. In the Slack navigation bar, choose More and then choose Apps.

    2. Search for and choose AWS Chatbot. aws now appears in your Apps list in the navigation bar.

    3. Invite AWS Chatbot to your channel: /invite @AWS

  5. Switch to the Configure Slack channel page and enter an identifiable configuration name.

  6. Optional– If you would like logging on this channel, Select Logging.

  7. For the channel type, choose public or private. Channels might take some time to populate because AWS Chatbot fetches all channels available in the workspace.

    • For public channels, use the search bar to choose your public channel.

    • For private channels, navigate to your channel within Slack and right-click the channel name. Choose Copy link, then enter the link in the Private Channel ID field on the AWS Chatbot configuration page.

  8. Choose Create an IAM role using a template, and enter a role name.

  9. For policy templates, choose AWS Systems Manager Incident Manager permissions.

  10. In the Notifications section, choose the Region for your first SNS topic.

  11. Choose the SNS topics you would like to notify during an incident. To learn more about SNS topics, see Amazon SNS.

    Note

    Incident Manager requires SNS topics to send notifications to your chat channels.

Amazon Chime
Note

Chat commands aren't supported on Amazon Chime.

  1. Enter an identifiable Configuration name.

  2. Open the Amazon Chime desktop client, then open the chat room you want.

  3. Choose the gear icon in the upper-right corner, and then choose Manage webhooks and bots.

  4. In the Manage incoming webhooks and bots dialog box, choose Add webhook, type a name for the webhook, and then choose Create.

  5. Verify the webhook you created is listed, and choose Copy URL to copy the webhook URL to your clipboard.

  6. On the Configure Amazon Chime webhook page, paste this copied webhook into the Webhook URL field.

  7. Provide a brief description to identify the chat room and purpose.

  8. You can optionally turn on logging for this chat room.

  9. Choose Create an IAM role using a template.

  10. Enter a Role name.

  11. For Policy templates, choose AWS Systems Manager Incident Manager permissions.

  12. In the Notifications section, choose the Region for your first SNS topic.

  13. Choose any number of SNS topics you would like to notify during an incident. To learn more about SNS topics, see Amazon SNS.

    Note

    Incident Manager requires SNS topics to send notifications to your chat channels.

You can now add this AWS Chatbot client to an Incident Manager response plan. To learn more about setting up response plans, see Working with response plans in Incident Manager.

Using SNS topics with Incident Manager incurs the costs of SNS. For more information, see Amazon SNS pricing.

Configuring SNS permissions

Before you can use the AWS Chatbot client during an incident, update the access policy of the related Amazon SNS topics.

  1. Navigate to the Amazon SNS console and choose Topics from the navigation panel.

  2. Select the Amazon SNS topic related to the AWS Chatbot client you set up in the previous section.

  3. Choose Edit.

  4. Expand the Access policy section and add the following statement to the policy's Statement array.

         {
      "Sid": "IncidentManagerSNSPublishingPermissions",
      "Effect": "Allow",
      "Principal": {
        "Service": "ssm-incidents.amazonaws.com"
      },
      "Action": "SNS:Publish",
      "Resource": "arn:aws:sns:us-east-1:111122223333:example_SNS_topic",
      "Condition": {
        "StringEqualsIfExists": {
          "AWS:SourceAccount": "111122223333"
         }
       }
     }
    Important

    The AWS service ssm-incidents.amazonaws.com must have permissions to publish to the chat channel's SNS topic. Without permissions to publish to the SNS topic, Incident Manager won't be able to publish notifications to your chat channel.

  5. Replace the Resource value "arn:aws:sns:us-east-1:111122223333:example_SNS_topic" with your Amazon SNS topic ARN.

  6. Replace the AWS:SourceAccount value "111122223333" with your AWS account ID.

  7. Choose Save changes.

Use the previous steps to update each SNS topic related to the configure AWS Chatbot client.

Encrypting Amazon SNS topics used by Incident Manager

You can encrypt Amazon SNS topics used by Incident Manager by using an AWS Key Management Service (AWS KMS) Customer Managed Key (CMK). For more information, see Creating keys in the AWS Key Management Service Developer Guide.

To configure Incident Manager with the required kms:GenerateDataKey and kms:Decrypt permissions, see Enable compatibility between event sources from AWS services and encrypted topics in the Amazon Simple Notification Service Developer Guide.

Interacting through chat

Incident Manager enables responders to interact with incidents directly from the chat channel. Chat commands are only available in Slack chat channel. These are some common commands:

To use any of the preceding commands from an active incident's chat channel, use the following format. Replace <CLI Command> with any of the preceding commands and its appropriate fields. 

@aws ssm-incidents <CLI Command>
@aws ssm-contacts <CLI Command>

Best practices

Best practices to keep in mind when configuring your chat channels using AWS Chatbot.

  • AWS Chatbot enabled Slack channels inherit the permissions of the IAM role used to configure AWS Chatbot. This enables responders in an AWS Chatbot enabled Slack channel to call any allow-listed action; such as Incident Manager APIs and retrieving metrics graphs.

  • Maintain principal of least permission, practice security standards, and regularly review membership of your AWS Chatbot enabled chat channels.