**End of support notice**: On February 20, 2026, AWS will end support for the Amazon Chime service. After February 20, 2026, you will no longer be able to access the Amazon Chime console or Amazon Chime application resources. For more information, visit the [blog post](https://aws.amazon.com/blogs/messaging-and-targeting/update-on-support-for-amazon-chime/). **Note:** This does not impact the availability of the [Amazon Chime SDK service](https://aws.amazon.com/chime/chime-sdk/). # Using chatbots with Amazon Chime If you administer an Amazon Chime Enterprise account, you can create up to 10 chatbots for integration with Amazon Chime. Chatbots can only be used in chat rooms created by members of your account. Only chat room administrators can add chatbots to a chat room. After a chatbot is added to a chat room, members of the chat room can interact with the bot using commands provided by the bot creator. For more information, see [Using chatbots](https://docs.aws.amazon.com/chime/latest/ug/chat-bots.html) in the *Amazon Chime User Guide*. You can also use the Amazon Chime API operation to enable or stop chatbots for your Amazon Chime account. For more information, see [Update chatbots](update-bots.md). **Note** You can't delete chatbots. To stop a chatbot from being used in your account, use the Amazon Chime [UpdateBot](https://docs.aws.amazon.com/chime/latest/APIReference/API_UpdateBot.html) API operation in the *Amazon Chime API Reference*. When you stop a chatbot, chat room administrators can remove it from a chat room, but they cannot add it to a chat room. Users who @mention a stopped chatbot in a chat room receive an error message. ## Prerequisites Before you start the procedure to integrate chatbots with Amazon Chime, complete the following prerequisites: + Create a chatbot. + Create the outbound endpoint for Amazon Chime to send events to your bot. Choose from an AWS Lambda function ARN or an HTTPS endpoint. For more information about Lambda, see the *[AWS Lambda Developer Guide](https://docs.aws.amazon.com/lambda/latest/dg/)*. ## DNS best practices for HTTPS endpoints We recommend the following best practices when assigning DNS for your HTTPS endpoint: + Use a DNS subdomain that is dedicated to the bot endpoint. + Use only A-records to point to the bot endpoint. + Protect your DNS servers and DNS registrar account to prevent domain hijacking. + Use publicly valid TLS intermediate certificates that are dedicated to the bot endpoint. + Cryptographically verify the bot message signature before acting on a bot message. After creating your chatbot, use the AWS Command Line Interface (AWS CLI) or the Amazon Chime API operation to complete the tasks described in the following sections. **Topics** + [Step 1: Integrate a chatbot with Amazon Chime](integrate-bots.md) + [Step 2: Configure the outbound endpoint for an Amazon Chime chatbot](config-endpoints.md) + [Step 3: Add the chatbot to an Amazon Chime chat room](add-bots.md) + [Authenticate chatbot requests](auth-bots.md) + [Update chatbots](update-bots.md) # Step 1: Integrate a chatbot with Amazon Chime After you complete the [prerequisites](use-bots.md#bots-prereqs), integrate your chatbot with Amazon Chime using the AWS CLI or Amazon Chime API. **Note** These procedures create a name and email address for your chatbot. Chatbot names and email addresses cannot be changed after creation. ## AWS CLI **To integrate a chatbot using the AWS CLI** 1. To integrate your chatbot with Amazon Chime, use the **create-bot** command in the AWS CLI. ``` aws chime create-bot --account-id 12a3456b-7c89-012d-3456-78901e23fg45 --display-name exampleBot --domain example.com ``` 1. Enter a chatbot display name of up to 55 alphanumeric or special characters (such as \$1, -, %). 1. Enter the registered domain name for your Amazon Chime Enterprise account. 1. Amazon Chime returns a response that includes the bot ID. ``` "Bot": { "CreatedTimestamp": "timeStamp", "DisplayName": "exampleBot", "Disabled": exampleBotFlag, "UserId": "1ab2345c-67de-8901-f23g-45h678901j2k", "BotId": "botId", "UpdatedTimestamp": "timeStamp", "BotType": "ChatBot", "SecurityToken": "securityToken", "BotEmail": "displayName-chimebot@example.com" } ``` 1. Copy and save the bot ID and bot email address to use in the following procedures. ## Amazon Chime API **To integrate a chatbot using the Amazon Chime API** 1. To integrate your chatbot with Amazon Chime, use the [CreateBot](https://docs.aws.amazon.com/chime/latest/APIReference/API_CreateBot.html) API operation in the *Amazon Chime API Reference*. 1. Enter a chatbot display name of up to 55 alphanumeric or special characters (such as \$1, -, %). 1. Enter the registered domain name for your Amazon Chime Enterprise account. 1. Amazon Chime returns a response that includes the bot ID. Copy and save the bot ID and email address. The bot email address looks like this: `exampleBot-chimebot@example.com`. ## AWS SDK for Java The following sample code demonstrates how to integrate a chatbot using the AWS SDK for Java. ``` CreateBotRequest createBotRequest = new CreateBotRequest() .withAccountId("chimeAccountId") .withDisplayName("exampleBot") .withDomain("example.com"); chime.createBot(createBotRequest); ``` Amazon Chime returns a response that includes the bot ID. Copy and save the bot ID and email address. The bot email address looks like this: `exampleBot-chimebot@example.com`. # Step 2: Configure the outbound endpoint for an Amazon Chime chatbot After you create a chatbot ID for your Amazon Chime Enterprise account, configure your outbound endpoint for Amazon Chime to use to send messages to your bot. The outbound endpoint can be an AWS Lambda function ARN or an HTTPS endpoint that you created as part of the [prerequisites](use-bots.md#bots-prereqs). For more information about Lambda, see the *[AWS Lambda Developer Guide](https://docs.aws.amazon.com/lambda/latest/dg/)*. **Note** If the outbound HTTPS endpoint for your bot is not configured or is empty, chat room administrators cannot add the bot to a chat room. Also, chat room users cannot interact with the bot. ## AWS CLI To configure an outbound endpoint for your chatbot, use the **put-events-configuration** command in the AWS CLI. Configure a Lambda function ARN or an outbound HTTPS endpoint. ------ #### [ Lambda ARN ] ``` aws chime put-events-configuration --account-id 12a3456b-7c89-012d-3456-78901e23fg45 --bot-id botId --lambda-function-arn arn:aws:lambda:us-east-1:111122223333:function:function-name ``` ------ #### [ HTTPS endpoint ] ``` aws chime put-events-configuration --account-id 12a3456b-7c89-012d-3456-78901e23fg45 --bot-id botId --outbound-events-https-endpoint https://example.com:8000 ``` ------ Amazon Chime responds with the bot ID and HTTPS endpoint. ``` { "EventsConfiguration": { "BotId": "BotId", "OutboundEventsHTTPSEndpoint": "https://example.com:8000" } } ``` ## Amazon Chime API To configure the outbound endpoint for your chatbot, use the Amazon Chime [PutEventsConfiguration](https://docs.aws.amazon.com/chime/latest/APIReference/API_PutEventsConfiguration.html) API operation in the *Amazon Chime API Reference*. Configure either a Lambda function ARN or an outbound HTTPS endpoint. + **If you configure a Lambda function ARN** – Amazon Chime calls Lambda to add permission to allow the Amazon Chime administrator's AWS account to invoke the provided Lambda function ARN. This is followed by a dry run invocation to verify that Amazon Chime has permission to invoke the function. If adding permissions fails, or if the dry run invocation fails, then the `PutEventsConfiguration` request returns an HTTP 4xx error. + **If you configure an outbound HTTPS endpoint** – Amazon Chime verifies your endpoint by sending an HTTP Post request with a Challenge JSON payload to the outbound HTTPS endpoint that you provided in the previous step. Your outbound HTTPS endpoint must respond by echoing back the Challenge parameter in JSON format. The following examples show the request and a valid response. ------ #### [ Request ] ``` HTTPS POST JSON Payload: { "Challenge":"00000000000000000000", "EventType" : "HTTPSEndpointVerification" } ``` ------ #### [ Response ] ``` HTTP/1.1 200 OK Content-type: application/json { "Challenge":"00000000000000000000" } ``` ------ If the challenge handshake fails, then the `PutEventsConfiguration` request returns an HTTP 4xx error. ## AWS SDK for Java The following sample code demonstrates how to configure an endpoint using the AWS SDK for Java. ``` PutEventsConfigurationRequest putEventsConfigurationRequest = new PutEventsConfigurationRequest() .withAccountId("chimeAccountId") .withBotId("botId") .withOutboundEventsHTTPSEndpoint("https://www.example.com") .withLambdaFunctionArn("arn:aws:lambda:region:account-id:function:function-name"); chime.putEventsConfiguration(putEventsConfigurationRequest): ``` # Step 3: Add the chatbot to an Amazon Chime chat room Only a chat room administrator can add a chatbot to a chat room. They use the chatbot email address created in [Step 1](integrate-bots.md). **To add a chatbot to a chat room** 1. Open the Amazon Chime desktop client or web application. 1. Choose the gear icon in the upper-right corner, and choose **Manage webhooks and bots**. 1. Choose **Add bot**. 1. For **Email address**, enter the bot email address. 1. Choose **Add**. The bot name appears in the chat room roster. If there are additional actions necessary to add a chatbot to a chat room, provide the actions to the chat room administrator. After the chatbot is added to the chat room, provide the chatbot commands to your chat room users. One way to do this is to program your chatbot to send command help to the chat room when it receives the chat room invite. AWS also recommends creating a help command for your chatbot users to use. # Authenticate chatbot requests You can authenticate requests sent to your chatbot from an Amazon Chime chat room. To do this, compute a signature based on the request. Then, validate that the computed signature matches the one on the request header. Amazon Chime uses the HMAC SHA256 hash to generate the signature. If your chatbot is configured for Amazon Chime using an outbound HTTPS endpoint, use the following authentication steps. **To validate a signed request from Amazon Chime for a chatbot with a outbound HTTPS endpoint configured** 1. Get the **Chime-Signature** header from the HTTP request. 1. Get the **Chime-Request-Timestamp** header and the **body** of the request. Then, use a vertical bar as the delimiter between the two elements to form a string. 1. Use the **SecurityToken** from the CreateBot response as the initial key of **HMAC\$1SHA\$1256**, and hash the string that you created in step 2. 1. Encode the hashed byte with Base64 encoder to a signature string. 1. Compare this computed signature to the one in the **Chime-Signature** header. The following code sample demonstrates how to generate a signature using Java. ``` private final String DELIMITER = "|"; private final String HMAC_SHA_256 = "HmacSHA256"; private String generateSignature(String securityToken, String requestTime, String requestBody) { try { final Mac mac = Mac.getInstance(HMAC_SHA_256); SecretKeySpec key = new SecretKeySpec(securityToken.getBytes(UTF_8), HMAC_SHA_256); mac.init(key); String data = requestTime + DELIMITER + requestBody; byte[] rawHmac = mac.doFinal(data.getBytes(UTF_8)); return Base64.getEncoder().encodeToString(rawHmac); } catch (Exception e) { throw e; } } ``` The outbound HTTPS endpoint must respond to the Amazon Chime request with `200 OK` within 2 seconds. Otherwise, the request fails. If the outbound HTTPS endpoint is unavailable after 2 seconds, possibly because of a Connection or Read timeout, , or if Amazon Chime receives a 5xx response code, Amazon Chime retries the request two times. The first retry is sent 200 milliseconds after the initial request fails. The second retry is sent 400 milliseconds after the previous retry fails. If the outbound HTTPS endpoint is still unavailable after the second retry, the request fails. **Note** The **Chime-Request-Timestamp** changes each time the request is retried. If your chatbot is configured for Amazon Chime using a Lambda function ARN, use the following authentication steps. **To validate a signed request from Amazon Chime for a chatbot with a Lambda function ARN configured** 1. Get the **Chime-Signature** and **Chime-Request-Timestamp** from the Lambda request **ClientContext**, in Base64 encoded JSON format. ``` { "Chime-Signature" : "1234567890", "Chime-Request-Timestamp" : "2019-04-04T21:30:43.181Z" } ``` 1. Get the **body** of the request from the request payload. 1. Use the **SecurityToken** from the `CreateBot` response as the initial key of **HMAC\$1SHA\$1256**, and hash the string that you created. 1. Encode the hashed byte with Base64 encoder to a signature string. 1. Compare this computed signature to the one in the **Chime-Signature** header. If a `com.amazonaws.SdkClientException` occurs during the Lambda invocation, Amazon Chime retries the request two times. # Update chatbots As the Amazon Chime account administrator, you can use the Amazon Chime API with the AWS SDK or AWS CLI to view your chatbot details. You can also enable or stop your chatbots from being used in your account. You can also regenerate security tokens for your chatbot. For more information, see the following topics in the *Amazon Chime API Reference*: + [GetBot](https://docs.aws.amazon.com/chime/latest/APIReference/API_GetBot.html) – Gets your chatbot details, such as bot email address and bot type. + [UpdateBot](https://docs.aws.amazon.com/chime/latest/APIReference/API_UpdateBot.html) – Enables or stops a chatbot from being used in your account. + [RegenerateSecurityToken](https://docs.aws.amazon.com/chime/latest/APIReference/API_RegenerateSecurityToken.html) – Regenerates the security token for your chatbot. You can also change the `PutEventsConfiguration` for your chatbot. For example, if your chatbot was initially configured to use an outbound HTTPS endpoint, you can delete the previous events configuration and put a new events configuration for a Lambda function ARN. For more information, see the following topics in the *Amazon Chime API Reference*: + [DeleteEventsConfiguration](https://docs.aws.amazon.com/chime/latest/APIReference/API_DeleteEventsConfiguration.html) + [PutEventsConfiguration](https://docs.aws.amazon.com/chime/latest/APIReference/API_PutEventsConfiguration.html)