AWS Chatbot is now Amazon Q Developer. [Learn more](service-rename.md)

# Custom actions using Amazon Q Developer in chat applications
<a name="custom-actions"></a>

Custom actions are preconfigured buttons you add to custom and default notifications. These actions allow you to automate commonly used DevOps processes and incident response tasks. When you create a custom action, you configure your action button to run either a CLI command, a Lambda function, or an SSM Automation runbook. Action targets can be paramaterized by using the parameters available in your notification metadata. You can use custom actions to retrieve telemetry information, run runbooks, and notify team members. When an issue arises, you can take action directly from your notifications. Custom actions are available in Amazon Q Developer in chat applications configurations for Microsoft Teams and Slack.

 No additional permissions are needed to configure or run custom actions. When your channel members choose the custom action button, the action target is invoked using the configured IAM permissions in your channel configuration. 

**Topics**
+ [Creating a custom action using Amazon Q Developer in chat applications](creating-custom-actions.md)
+ [Sample use cases](sample-custom-action.md)

# Creating a custom action using Amazon Q Developer in chat applications
<a name="creating-custom-actions"></a>

 You can create custom actions using AWS CLI commands, Automation runbooks and Lambda functions in your account, or by using the [Amazon Q Developer in chat applications in chat applications API](https://docs.aws.amazon.com/chatbot/latest/APIReference/Welcome.html). AWS CLI command Shortcuts function similarly to [Command aliases](creating-aliases.md). 

------
#### [ Automation action ]

**To create an Automation action**

1. Choose the vertical ellipsis button (**⋮**) on the bottom of a notification in your chat channel.

1. In **Manage actions**, choose **Create**.

1.  Enter a custom action name. This name is a unique identifier for your custom action. 

1.  Enter a name for your custom action button. This name is shown on a button on your notification. This name should be 20 characters or less and can incorporate emojis. 

1. For **Custom action type**, select **Automation runbook action**.

1. Choose **Next**.

1. Select an AWS account.

1. Select a Region.
**Note**  
The available Automation runbooks are populated from this account and Region.

1. Select an Automation runbook owner. This value defaults to **Owned by me**.
**Note**  
You can filter runbooks by owner. For more information about owner types, see [Editing an existing Systems Manager automation document](https://docs.aws.amazon.com/cloud9/latest/user-guide/systems-manager-automation-docs.html#systems-manager-open) in the *AWS Cloud9 User Guide*.

1. Choose **Load Automation runbooks**.

1.  In **Define Automation runbook**, select an Automation runbook. 

1.  Enter your input parameters. 
**Note**  
We expose predefined variables from your custom notifications as useable variables.

1.  (Optional) Add more variables by choosing **\$1 Add more variables**. 

1.  Choose **Next**. 

1.  (Optional) Add additional display criteria: 

   1. Select a variable.

   1. Select a condition.

   1. Choose **Add**.

1. Choose **Save**.

When you run a runbook, you're prompted to select the IAM role used to run it. You can select from assumable roles in the account configured with your chat channel. If you don't select a role, the runbook runs using your channel role.

------
#### [ CLI action ]

**To create an AWS CLI command action**

1. Choose the vertical ellipsis button (**⋮**) on the bottom of a notification in your chat channel.

1. In **Manage actions**, choose **Create**.

1.  Enter a custom action name. This name is a unique identifier for your custom action. 

1.  Enter a name for your custom action button. This name is shown on a button on your notification. This name should be 20 characters or less and can incorporate emojis. 

1. For **Custom action type**, select **CLI action**.

1.  Enter a command. 
**Note**  
We expose predefined variables from your custom notifications as useable variables.

1.  (Optional) Add more variables by choosing **\$1 Add more variables**. 

1.  Choose **Next**. 

1.  (Optional) Add additional display criteria: 

   1. Select a variable.

   1. Select a condition.

   1. Choose **Add**.

1. Choose **Save**.

------
#### [ Lambda action ]

**To create a Lambda action**

1. Choose the vertical ellipsis button (**⋮**) on the bottom of a notification in your chat channel.

1. In **Manage actions**, choose **Create**.

1.  Enter a custom action name. This name is a unique identifier for your custom action. 

1.  Enter a name for your custom action button. This name is shown on a button on your notification. This name should be 20 characters or less and can incorporate emojis. 

1. For **Custom action type**, select **Lambda action**.

1. Choose **Next**.

1. Select an AWS account.

1. Select a Region.
**Note**  
The available Lambda functions are populated from this account and Region.

1. Choose **Load Lambdas**.

1.  In **Define Lambda Function**, select a Lambda function. 

1.  Enter your payload. 
**Note**  
We expose predefined variables from your custom notifications as useable variables.

1.  (Optional) Add more variables by choosing **\$1 Add more variables**. 

1.  Choose **Next**. 

1.  (Optional) Add additional display criteria: 

   1. Select a variable.

   1. Select a condition.

   1. Choose **Add**.

1. Choose **Save**.

------

# Sample use cases
<a name="sample-custom-action"></a>

This page includes examples of functional use cases for custom actions that you can leverage for your specific needs.

## Custom notifications metadata
<a name="custom-notifs-metadata"></a>

 You can use custom notifications to specify metadata for your custom actions. Custom actions display this information as variables that you define in the payload. Before you run a custom action, you're shown a complete summary of that action and its payload. In the following example, a custom notification for allow listing an IP address contains an IP address as metadata: 

```
{
    "version": "1.0",
    "source": "custom",
    "content": {
        "title": "IP Address Allowlist Request",
        "description": "We have received a request to allows list an IP address from 'sample@sample.com'."
    },
    "metadata": {
        "additionalContext": {
            "IPAddress": "192.168.0.1"
        }
    }
}
```

 If you create a custom action based on this notification, `{"message": "I'ved allow listed IP address: $IPAddress"}` is shown as an available notification variable that you can use in your payload. For example, the following Lambda action payload displays the message and the IP address variable. 

```
{"message": "I'ved allow listed IP address: $IPAddress"}
```

## Recent Amazon CloudWatch Logs errors
<a name="cw-errors"></a>

 The following example shows how you can use custom actions to display recent errors from an Amazon CloudWatch Logs group in your channel from an Amazon CloudWatch Logs notification.

 The following Lambda function returns a list of the most common Amazon CloudWatch Logs errors: 

```
import boto3
from collections import Counter
import json
import datetime

def extract_message(value):
  if value.startswith('{'):
    try:
      structured_message = json.loads(value)

      return structured_message.get('message', value)
    except Exception:
      pass
  
  return value

def take_ellipsis(value, length):
  if len(value) <= length:
    return value
  else:
    return value[:length - 1] + '…'

def lambda_handler(event, context):
  log_group_name = event['logGroup']
  lookback_minutes = int(event.get('minutes', 60))
  filter = event.get('filter', 'ERROR')
  limit = int(event.get('limit', 10))

  logs_client = boto3.client('logs')

  now = datetime.datetime.now()
  offset = now - datetime.timedelta(minutes=lookback_minutes)
  print(offset)
  start_time = int(offset.timestamp() * 1000)
  end_time = int(now.timestamp() * 1000)

  response = logs_client.filter_log_events(
    logGroupName=log_group_name,
    startTime=start_time,
    endTime=end_time,
    filterPattern=filter
  )
  
  messages = [extract_message(event['message']) for event in response['events']]
  
  message_counts = Counter(messages)

  top_messages = message_counts.most_common(limit)

  if top_messages:
    formatted_messages = [
      f'{index + 1}. `{take_ellipsis(message[0], 100)}` ({message[1]} occurrences)' for index, error in enumerate(top_messages)
    ]
    message_summary = '\n'.join(formatted_messages)

    return f'*Most common errors in `{log_group_name}` within the last hour*\n\n' + message_summary
  else:
    return f'Found no errors matching filter within the last {lookback_minutes} minutes in {log_group_name}'
```

 You can create a Lambda action that invokes this Lambda function and view errors for specific log groups by choosing this function while creating your action and entering the following as the payload: 

```
{
    "logGroup": "$LogGroup"
}
```