Amazon Chime

(1)

Amazon Chime

Developer Guide

(2)

Amazon Chime: Developer Guide

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

What is Amazon Chime?

Amazon Chime is a communications service that transforms online meetings with an application that is secure and comprehensive. Amazon Chime works across your devices so that you can stay connected.

You can use Amazon Chime for online meetings, video conferencing, calls, and chat. You can also share content inside and outside of your organization. Amazon Chime helps you to work productively from anywhere.

Developers can use Amazon Chime with the AWS SDK or AWS Command Line Interface (AWS CLI) to perform such tasks as managing users, or integrating webhooks and chat bots with Amazon Chime. They can also use the Amazon Chime SDK to build real-time media applications that can send and receive audio and video and allow content sharing. For detailed information about Amazon Chime API actions, see the Amazon Chime API Reference.

Amazon Chime permissions are controlled using AWS Identity and Access Management (IAM). For more information, see Identity and access management for Amazon Chime in the Amazon Chime Administrator Guide.

Pricing

Amazon Chime provides usage-based pricing. You pay only for the users with Pro permissions that host meetings, and only on the days that those meetings are hosted. For more information, see Amazon Chime pricing.

Resources

The following related resources can help you as you work with this service.

• Classes & Workshops – Links to role-based and specialty courses, in addition to self-paced labs to help sharpen your AWS skills and gain practical experience.

• AWS Developer Tools – Links to developer tools, SDKs, IDE toolkits, and command line tools for developing and managing AWS applications.

• AWS Whitepapers – Links to a comprehensive list of technical AWS whitepapers, covering topics such as architecture, security, and economics and authored by AWS Solutions Architects or other technical experts.

• AWS Support Center – The hub for creating and managing your AWS Support cases. Also includes links to other helpful resources, such as forums, technical FAQs, service health status, and AWS Trusted Advisor.

• AWS Support – The primary webpage for information about AWS Support, a one-on-one, fast- response support channel to help you build and run applications in the cloud.

• Contact Us – A central contact point for inquiries concerning AWS billing, account, events, abuse, and other issues.

• AWS Site Terms – Detailed information about our copyright and trademark; your account, license, and site access; and other topics.

(8)

User management

Extending the Amazon Chime desktop client

Developers can extend the capabilities of the Amazon Chime desktop client by adding chat bots, proxy phone sessions, and webhooks. Chat bots enable users to perform tasks such as querying internal systems for information. Proxy phone sessions allow users to call and send texts without revealing their phone numbers. Webhooks can automatically send messages to chat rooms. For example, a webhook can send meeting reminders to a team, along with a link to the meeting.

Topics

• User management (p. 2)

• Integrating chatbots into the Amazon Chime desktop client (p. 3)

• Proxy phone sessions (p. 11)

• Webhooks for Amazon Chime (p. 12)

User management

The following code snippets can help developers manage Amazon Chime users. All of the examples in this topic use Java.

Content

• Invite multiple users (p. 2)

• Download user list (p. 2)

• Log out multiple users (p. 3)

• Update user personal PINs (p. 3)

Invite multiple users

The following example shows how to invite multiple users to an Amazon Chime Team account.

List<String> emails = new ArrayList<>();

emails.add("[email protected]");

InviteUsersRequest inviteUsersRequest = new InviteUsersRequest() .withAccountId("chimeAccountId")

.withUserEmailList(emails);

chime.inviteUsers(inviteUsersRequest);

Download user list

The following example shows how to download a list of users associated with your Amazon Chime administrative account in .csv format.

BufferedWriter writer = Files.newBufferedWriter(Paths.get("/path/to/csv"));

CSVPrinter printer = new CSVPrinter(writer, CSVFormat.DEFAULT.withHeader("userId", "email"));

ListUsersRequest listUsersRequest = new ListUsersRequest()

(9)

Log out multiple users

.withAccountId(accountId) .withMaxResults(1);

boolean done = false;

while (!done) {

ListUsersResult listUsersResult = chime.listUsers(listUsersRequest);

for (User user: listUsersResult.getUsers()) {

printer.printRecord(user.getUserId(), user.getPrimaryEmail());

}

if (listUsersResult.getNextToken() == null) { done = true;

}

listUsersRequest = new ListUsersRequest() .withAccountId(accountId)

.withNextToken(listUsersResult.getNextToken());

}

printer.close();

Log out multiple users

The following example shows how to log out multiple users from your Amazon Chime administrative account.

ListUsersRequest listUsersRequest = new ListUsersRequest() .withAccountId("chimeAccountId");

ListUsersResult listUsersResult = chime.listUsers(listUsersRequest);

for (User user: listUsersResult.getUsers()) {

LogoutUserRequest logoutUserRequest = new LogoutUserRequest() .withAccountId(user.getAccountId())

.withUserId(user.getUserId());

chime.logoutUser(logoutUserRequest);

}

Update user personal PINs

The following example shows how to reset the personal meeting PIN for a speciﬁed Amazon Chime user.

ResetPersonalPINRequest request = new ResetPersonalPINRequest() .withAccountId("chimeAccountId")

.withUserId("userId");

ResetPersonalPINResult result = chime.resetPersonalPIN(request);

User user = result.getUser();

user.getPersonalPIN()

Integrating chatbots into the Amazon Chime desktop client

Developers can use the AWS Command Line Interface (AWS CLI), Amazon Chime API, or AWS SDK to integrate chatbots with Amazon Chime. Chatbots let you use the power of Amazon Lex, AWS Lambda,

(10)

Use chatbots with Amazon Chime

and other AWS services to streamline common tasks with intelligent conversational interfaces that are accessible to users in Amazon Chime chat rooms.

If you're an Amazon Chime Enterprise account administrator, you can use chatbots to allow users to perform such tasks as:

• Querying their internal systems for information.

• Automating tasks.

• Receiving notiﬁcations for critical issues.

• Creating support tickets.

For more information about Amazon Chime Enterprise accounts, see Managing your Amazon Chime accounts in the Amazon Chime Administrator Guide.

If you administer an Amazon Chime Enterprise account, you can create up to 10 chatbots for integration with Amazon Chime. Chatbots can be used only 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 in the Amazon Chime User Guide.

Linux and macOS users can build a sample custom chatbot. For more information, see Build custom chatbots for Amazon Chime.

Content

• Use chatbots with Amazon Chime (p. 4)

• Amazon Chime events sent to chatbots (p. 10)

Use 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 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 (p. 10).

NoteChatbots cannot be deleted. To stop a chatbot from being used in your account, use the Amazon Chime UpdateBot 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.

(11)

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 certiﬁcates 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.

Tasks

• Step 1: Integrate a chatbot with Amazon Chime (p. 5)

• Step 2: Conﬁgure the outbound endpoint for an Amazon Chime chatbot (p. 6)

• Step 3: Add the chatbot to an Amazon Chime chat room (p. 8)

• Authenticate chatbot requests (p. 8)

• Update chatbots (p. 10)

Step 1: Integrate a chatbot with Amazon Chime

After you complete the prerequisites (p. 4), integrate your chatbot with Amazon Chime using the AWS CLI or Amazon Chime API.

NoteThese 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 --displayname exampleBot --domain example.com

a. Enter a chatbot display name of up to 55 alphanumeric or special characters (such as +, -, %).

b. Enter the registered domain name for your Amazon Chime Enterprise account.

2. 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": "[email protected]"

(12)

}

3. 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 API operation in the Amazon Chime API Reference.

a. Enter a chatbot display name of up to 55 alphanumeric or special characters (such as +, -, %).

b. Enter the registered domain name for your Amazon Chime Enterprise account.

2. 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: [email protected].

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: [email protected].

Step 2: Conﬁgure the outbound endpoint for an Amazon Chime chatbot

After you create a chatbot ID for your Amazon Chime Enterprise account, conﬁgure 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 (p. 4).

For more information about Lambda, see the AWS Lambda Developer Guide.

NoteIf the outbound HTTPS endpoint for your bot is not conﬁgured 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

(13)

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 API operation in the Amazon Chime API Reference. Configure either a Lambda function ARN or an outbound HTTPS endpoint.

• If you conﬁgure 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 conﬁgure an outbound HTTPS endpoint – Amazon Chime veriﬁes 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.

(14)

AWS SDK for Java

The following sample code demonstrates how to conﬁgure 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 (p. 5).

To add a chatbot to a chat room

1. Open the Amazon Chime desktop client or web application.

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

3. Choose Add bot.

4. For Email address, enter the bot email address.

5. 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 conﬁgured 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 conﬁgured

1. Get the Chime-Signature header from the HTTP request.

2. 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.

3. Use the SecurityToken from the CreateBot response as the initial key of HMAC_SHA_256, and hash the string that you created in step 2.

4. Encode the hashed byte with Base64 encoder to a signature string.

5. Compare this computed signature to the one in the Chime-Signature header.

The following code sample demonstrates how to generate a signature using Java.

(15)

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 ﬁrst 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.

NoteThe Chime-Request-Timestamp changes each time the request is retried.

If your chatbot is conﬁgured 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 conﬁgured

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"

}

2. Get the body of the request from the request payload.

3. Use the SecurityToken from the CreateBot response as the initial key of HMAC_SHA_256, and hash the string that you created.

4. Encode the hashed byte with Base64 encoder to a signature string.

5. 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.

(16)

Amazon Chime events sent to chatbots

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 – Gets your chatbot details, such as bot email address and bot type.

• UpdateBot – Enables or stops a chatbot from being used in your account.

• RegenerateSecurityToken – 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:

• DeleteEventsConﬁguration

• PutEventsConﬁguration

Amazon Chime events sent to chatbots

The following events are sent to your chatbot from Amazon Chime:

• Invite – Sent when your chatbot is added to an Amazon Chime chat room

• Mention – Sent when a user in a chat room @mentions your chatbot

• Remove – Sent when your chatbot is removed from an Amazon Chime chat room

The following examples show the JSON payload sent to your chatbot for each of these events.

Example : Invite event

{

"Sender": {

"SenderId": "[email protected]", "SenderIdType": "EmailId"

}, "Discussion": {

"DiscussionId": "abcdef12-g34h-56i7-j8kl-mn9opqr012st", "DiscussionType": "Room"

}, "EventType": "Invite", "InboundHttpsEndpoint": {

"EndpointType": "Persistent", "Url": "https://

hooks.a.chime.aws/incomingwebhooks/a1b2c34d-5678-90e1-f23g-h45i67j8901k?

token=ABCDefGHiJK1LMnoP2Q3RST4uvwxYZAbC56DeFghIJkLM7N8OP9QRsTuV0WXYZABcdefgHiJ"

},

"EventTimestamp": "2019-04-04T21:27:52.736Z"

}

(17)

Proxy phone sessions

Example : Mention event

{

"Sender": {

}, "Discussion": {

}, "EventType": "Mention", "InboundHttpsEndpoint": {

"EndpointType": "ShortLived", "Url": "https://

hooks.a.chime.aws/incomingwebhooks/a1b2c34d-5678-90e1-f23g-h45i67j8901k?

token=ABCDefGHiJK1LMnoP2Q3RST4uvwxYZAbC56DeFghIJkLM7N8OP9QRsTuV0WXYZABcdefgHiJ"

},

"EventTimestamp": "2019-04-04T21:30:43.181Z",

"Message": "@[email protected] Hello Chatbot"

}

NoteThe InboundHttpsEndpoint URL for a Mention event expires 2 minutes after it is sent.

Example : Remove event

{

"Sender": {

}, "Discussion": {

}, "EventType": "Remove",

"EventTimestamp": "2019-04-04T21:27:29.626Z"

}

Proxy phone sessions

Developers can use the AWS Command Line Interface (AWS CLI), Amazon Chime API, or AWS SDK to create proxy phone sessions for use with Amazon Chime Voice Connectors. Proxy phone sessions allow participants to call or send text messages to each other without revealing private phone numbers.

Creating proxy phone sessions requires the following:

• The ability to program.

• An AWS account.

• An AWS Identity and Access Management (IAM) role that grants permission to access the Amazon Chime API actions used to create proxy phone sessions, such as the following:

• chime:CreateProxySession

(18)

Webhooks

• chime:DeleteProxySession

• chime:DeleteVoiceConnectorProxy

• chime:GetProxySession

• chime:GetVoiceConnectorProxy

• chime:ListProxySessions

• chime:PutVoiceConnectorProxy

• chime:UpdateProxySession

For more information, see Amazon Chime identity-based policies in the Amazon Chime Administrator Guide.

• An Amazon Chime Voice Connector created by an Amazon Chime account administrator. For more information, see Managing Amazon Chime Voice Connectors in the Amazon Chime Administrator Guide.

The following procedure demonstrates how to create a proxy phone session.

To create a proxy phone session

1. Use the PutVoiceConnectorProxy action in the Amazon Chime API Reference to conﬁgure the Amazon Chime Voice Connector for the proxy phone session.

2. Use the CreateProxySession action in the Amazon Chime API Reference to create the proxy phone session.

For more information about the available Amazon Chime API actions for proxy phone sessions, see the Amazon Chime API Reference.

Webhooks for Amazon Chime

Webhooks allow web applications to communicate with each other in real time. Typically, webhooks send notiﬁcations when an action occurs. For example, say you run an online shopping site. Webhooks can notify you when a customer adds items to a shopping cart, pays for an order, or sends a comment.

Webhooks don't need as much programming as traditional applications, and they don't use as much processing power. Without a webhook, a program has to to poll for data frequently in order to get it in real time. With a webhook, the sending application posts the data immediately.

Incoming webhooks that you create can programmatically send messages to Amazon Chime chat rooms.

For example, a webhook can notify a customer service team about the creation of a new high-priority ticket, and add a link to the ticket in the chat room.

Webhooks messages can be formatted with markdown and can include emojis. HTTP links and email addresses render as active links. Messages can also include @All and @Present annotations to alert all members and present members of a chat room, respectively. To directly @mention a chat room participant, use their alias or full email address. For example, @alias or @[email protected].

Webhooks can only be part of a chat room and can't be shared. Amazon Chime chat room administrators can add up to 10 webhooks for each chat room.

After you create a webhook, you can integrate it with an Amazon Chime chat room, as shown in the following procedure.

To integrate a webhook with a chat room

1. Get the webhook URL from the chat room administrator. For more information, see Adding webhooks to chat rooms in the Amazon Chime User Guide.

(19)

Troubleshooting webhook errors

2. Use the webhook URL in the script or application that you created to send messages to the chat room:

a. The URL accepts an HTTP POST request.

b. Amazon Chime webhooks accept a JSON payload with a single key Content. The following is a sample curl command with a sample payload:

curl -X POST "<Insert your webhook URL here>" -H "Content-Type:application/json"

--data '{"Content":"Message Body emoji test: :) :+1: link test: http://sample.com email test: [email protected] All member callout: @All All Present member callout: @Present"}'

The following is a sample PowerShell command for Windows users:

Invoke-WebRequest -Uri '<Insert your webhook URL here>' -Method 'Post' -ContentType 'application/JSON' -Body '{"Content":"Message Body emoji test: :) :+1: link test:

http://sample.com email test: [email protected] All member callout: @All All Present member callout: @Present"}'

After the external program sends the HTTP POST to the webhook URL, the server validates that the webhook is valid and has an assigned chat room. The webhook appears in the chat room roster with a webhook icon next to its name. Chat room messages sent by the webhook appear in the chat room under the webhook name followed by (Webhook).

NoteCORS is not currently enabled for webhooks.

Troubleshooting webhook errors

The following is a list of webhook-related errors:

• The incoming webhook rate limit for each webhook is 1 TPS per chat room. Throttling results in an HTTP 429 error.

• Messages posted by a webhook must be 4 KB or less. A bigger message payload results in an HTTP 413 error.

• Messages posted by a webhook with @All and @Present annotations work only for chat rooms with 50 or fewer members. More than 50 members results in an HTTP 400 error.

• If the webhook URL is regenerated, using the old URL results in an HTTP 404 error.

• If the webhook in a room is deleted, using the old URL results in an HTTP 404 error.

• Invalid webhook URLs result in HTTP 403 errors.

• If the service is unavailable, the user receives an HTTP 503 error in the response.

(20)

Amazon Chime SDK prerequisites

Using the Amazon Chime SDK

You use the Amazon Chime SDK to build real-time media applications that can send and receive audio and video and allow content sharing. The Amazon Chime SDK works independently of any Amazon Chime administrator accounts, and it does not aﬀect meetings hosted on Amazon Chime. Instead, the Amazon Chime SDK provides builder tools that you use to build your own meeting applications.

Topics

• Amazon Chime SDK prerequisites (p. 14)

• Amazon Chime SDK concepts (p. 14)

• Amazon Chime SDK architecture (p. 15)

• Amazon Chime SDK quotas (p. 16)

• Amazon Chime SDK system requirements (p. 16)

• Available regions (p. 17)

• Integrating with a client library (p. 20)

• SIP integration using an Amazon Chime Voice Connector (p. 20)

• Amazon Chime SDK event notiﬁcations (p. 22)

Amazon Chime SDK prerequisites

Using the Amazon Chime SDK requires the following:

• The ability to program.

• An AWS account.

• An IAM role with a policy that grants permission to access Amazon Chime API actions used by the Amazon Chime SDK, such as the AWS managed AmazonChimeSDK policy. For more information, see How Amazon Chime works with IAM and Allow users to access Amazon Chime SDK actions in the Amazon Chime Administrator Guide.

• For the majority of use cases, you also need the following:

• A server application – Manages meeting and attendee resources, and serves those resources to the client application. The server application is created in the AWS account and must have access to the IAM role mentioned previously.

• A client application – Receives meeting and attendee information from the server application, and uses that information to make media connections.

Amazon Chime SDK concepts

The following terminology and concepts are central to understanding how to use the Amazon Chime SDK.

meeting

An ephemeral resource identiﬁed by a unique MeetingId. The MeetingId is placed onto a group of media services that host the active meeting.

media service group

The group of media services that hosts an active meeting.

(21)

Amazon Chime SDK architecture

media placement

A set of regionalized URLs that represents a media service group. Attendees connect to the media service group with their clients to send and receive real-time audio and video, and share their screens.

attendee

A meeting participant that is identiﬁed by a unique AttendeeId. Attendees may freely join and leave meetings using a client application built with an Amazon Chime SDK client library.

join token

A unique token assigned to each attendee. Attendees use the join token to authenticate with the media service group.

Amazon Chime SDK architecture

The following list describes how the diﬀerent components of the Amazon Chime SDK architecture work together to support meetings and attendees, audio, video, and content sharing.

Meetings and attendees

When the server application creates an Amazon Chime SDK meeting, the meeting is assigned to a region-speciﬁc media service. The hosts in the service are responsible for securely transferring real-time media between attendee clients. Each created attendee is assigned a unique join token, an opaque secret key that your server application must securely transfer to the client authorized to join the meeting on behalf of an attendee. Each client uses a join token to authenticate with the media service group. Clients use a combination of secure WebSockets and Datagram Transport Layer Security (DTLS) to securely signal the media service group, and to send and receive media to and from other attendees through the media service group.

Audio

The media service mixes audio together from each attendee and sends the mix to each recipient, after subtracting their own audio from the mix. The Amazon Chime SDKs sample audio at the highest rate supported by the device and browser, up to a maximum of 48kHz. We use the Opus codec to encode audio, with a default bitrate of 32kbps, which can be increased to up to 128kbps stereo and 64kbps mono.

Video

The media service acts as a Selective Forwarding Unit (SFU) using a publish and subscribe model.

Each attendee can publish one video source, up to a total of 25 simultaneous videos per meeting.

The Amazon Chime SDK for JavaScript supports video resolutions up to 1280x720 at 30 frames per second without simulcast, and 15 frames per second with simulcast. The Amazon Chime SDK for iOS and Android support video resolutions up to 1280x720 and 15 frames per second, however the actual framerate and resolution is automatically managed by the Amazon Chime SDK.

When active, video simulcast sends each video stream in two diﬀerent resolutions and bitrates.

Clients which are bandwidth constrained automatically subscribe to the lower bitrate stream. Video encoding and decoding uses hardware acceleration where available to improve performance.

Data messages

In addition to audio and video content, meeting attendees can send each other real-time data messages of up to 2 KB each. Developers can use messages to implement custom meeting features such as whiteboarding, chat, real-time emoji reactions, and application-speciﬁc ﬂoor control signaling.

(22)

Amazon Chime SDK quotas

Content sharing

The client application can share audio and video content, such as screen captures or media ﬁles.

Content sharing supports pre-recorded content video up to 1280x720 at 15 frames per second, and audio up to 48kHz at 64kbps. Screen capture for content sharing is supported up to 15 frames per second, but may be limited by the capabilities of the device and browser.

Amazon Chime SDK quotas

Resource Quota Adjustable

Active Meetings 250 Yes

Attendees per meeting 250 No

Audio streams per meeting 250 No

Video tiles per meeting 25 Yes

Content shares per meeting 2 No

API Rate 10 requests per second (RPS)

with a burst of 20 RPS. Yes

Amazon Chime SDK system requirements

The following system requirements apply to applications created with the Amazon Chime SDK.

Supported browsers, Amazon Chime SDK for JavaScript

Operating system Browser Supported versions Notes

Mozilla Firefox 75 and later

Google Chrome 78 and later

Chromium-based Edge 79 and later Chromium-based

Electron 7 and later With Chrome version 78

and later.

Windows

Opera 66 and later

Mozilla Firefox 75 and later

Google Chrome 78 and later

Chromium-based Edge 79 and later Chromium-based

Electron

Safari 12 and later

macOS

Opera 66 and later

(23)

Available regions

Operating system Browser Supported versions Notes

Mozilla Firefox 10.0 and later Audio and video only, no content sharing.

Google Chrome 78 and later Audio and video only, no content sharing.

Safari 12.0 and later Audio and video only,

no content sharing.

iOS

WKWebView 14.3 and later Audio and video only,

no content sharing.

Google Chrome 10.0 and later Audio and video only, no content sharing.

Samsung 12 and later Audio and video only,

no content sharing.

Android

Chromium WebView 5.0 and later Audio and video only, no content sharing.

Ubuntu LTS 16.04 and

later Google Chrome 78 and later

Amazon Chime SDK for iOS

• iOS version 10.0 and later

Amazon Chime SDK for Android

• Android OS version 5.0 and later, ARM and ARM64 architecture

Available regions

The following tables list the features of the Amazon Chime SDK service and the AWS regions that provide each service.

NoteRegions marked with an asterisk (*) must be enabled in your AWS account. For more information, refer to Enabling a Region in the AWS General Reference.

Meeting Regions

Amazon Chime SDK meetings have control regions and media regions. A control region provides the API endpoint used to create, update and delete meetings. Media regions host the actual meetings.

A control region can create a meeting in any media region in the same AWS partition. However, you can only update a meeting in the control region used to create the meeting.

The following table lists the Regions that provde control, media, or both.

AWS Region Meeting control Meeting media

Africa (Cape Town) (af-south-1)* Yes

(24)

Media pipeline Regions

AWS Region Meeting control Meeting media

Asia Paciﬁc (Mumbai) (ap-

south-1) Yes

Asia Paciﬁc (Seoul) (ap-

northeast-2) Yes

Asia Paciﬁc (Singapore) (ap-

southeast-1) Yes Yes

Asia Paciﬁc (Sydney) (ap-

southeast-2) Yes

Asia Paciﬁc (Tokyo) (ap-

northeast-1) Yes

Canada (Central) (ca-central-1) Yes

Europe (Frankfurt) (eu-central-1) Yes Yes

Europe (Ireland) (eu-west-1) Yes

Europe (London) (eu-west-2) Yes

Europe (Milan) (eu-south-1)* Yes

Europe (Paris) (eu-west-3) Yes

Europe (Stockholm) (eu-north-1) Yes

South America (São Paulo) (sa-

east-1) Yes

US East (Ohio) (us-east-2) Yes

US East (N. Virginia) (us-east-1) Yes Yes

US West (N. California) (us-

west-1) Yes

US West (Oregon) (us-west-2) Yes Yes

GovCloud (US-East) (us-gov-

east-1) Yes Yes

GovCloud (US-West) (us-gov-

west-1) Yes Yes

NoteTo create a meeting in an AWS GovCloud (US) Region, you must use a control region in GovCloud. Also, control regions in GovCloud can only make meetings in AWS GovCloud (US) Regions.

Media pipeline Regions

Amazon Chime SDK media pipelines have control regions and data regions. The control region exposes the media pipeline API endpoint, and the data region is where the media pipelines are run.

(25)

Media pipeline Regions

You can use the control region to create a media pipeline in any data region. The media pipeline can join a meeting in any meeting media region. The media pipeline can only access Amazon S3 within its data region.

AWS Region Control Data S3

Africa (Cape Town) (af-

south-1)* Yes Local

Asia Paciﬁc (Mumbai)

(ap-south-1) Yes Local

Asia Paciﬁc (Seoul) (ap-

northeast-2) Yes Local

Asia Paciﬁc (Singapore)

(ap-southeast-1) Yes Local

Asia Paciﬁc (Sydney)

(ap-southeast-2) Yes Local

Asia Paciﬁc (Tokyo) (ap-

northeast-1) Yes Local

Canada (Central) (ca-

central-1) Yes Local

Europe (Frankfurt) (eu-

central-1) Yes Local

Europe (Ireland) (eu-

west-1) Yes Local

Europe (London) (eu-

west-2) Yes Local

Europe (Milan) (eu-

south-1)* Yes Local

Europe (Paris) (eu-

west-3) Yes Local

Europe (Stockholm)

(eu-north-1) Yes Local

South America (São

Paulo) (sa-east-1) Yes Local

US East (Ohio) (us-

east-2) Yes Local

US East (N. Virginia)

(us-east-1) Yes Yes Local

US West (N. California)

(us-west-1) Yes Local

US West (Oregon) (us-

west-2) Yes Local

(26)

Public Switched Telephone Network (PSTN) Regions

Amazon Chime SDK PSTN features have control regions and media regions. The control regions expose the API endpoints. The data regions connect Amazon Chime Voice Connectors with the PSTN, and they also run SIP media applications.

AWS Region Control Media

US West (Oregon) (us-west-2) Yes

Messaging Regions

Amazon Chime SDK messaging has control regions and data regions. The control region exposes the messaging API endpoint, and the data region stores the messages. If you use Amazon Kinesis to stream messaging data, Amazon S3 to store attachments, or AWS Lambda functions for channel ﬂows, they should reside in the control region.

AWS Region Control Media

Integrating with a client library

Before you can build real-time meeting clients with the Amazon Chime SDK, you must integrate your client application with an Amazon Chime SDK client library. The following client libraries are available:

• Amazon Chime SDK client library for JavaScript (NPM) – A JavaScript library with TypeScript type deﬁnitions that helps you build Amazon Chime SDK applications in WebRTC-enabled browsers.

• Amazon Chime SDK client library for iOS – A Swift library that helps you build Amazon Chime SDK applications on supported iOS devices.

• Amazon Chime SDK client library for Android – A Kotlin library that helps you build Amazon Chime SDK applications on supported Android devices.

To learn how to integrate your client application with the Amazon Chime SDK, see the actions in the client library README.md. Use the demos to learn how to build speciﬁc media components for your application.

SIP integration using an Amazon Chime Voice Connector

Integrate your SIP-compatible voice infrastructure with an Amazon Chime Voice Connector to make SIP voice calls. You must have an IP Private Branch Exchange (PBX), Session Border Controller (SBC), or other voice infrastructure with internet access that supports Session Initiation Protocol (SIP). For more information, see Before you begin in the Amazon Chime Administrator Guide.

(27)

SIP integration

To integrate your voice infrastructure with an Amazon Chime Voice Connector

1. Create an Amazon Chime Voice Connector under your AWS account. For more information, see Creating an Amazon Chime Voice Connector in the Amazon Chime Administrator Guide.

2. Edit your Amazon Chime Voice Connector settings to allow calling from your voice infrastructure to AWS. For more information, see Editing Amazon Chime Voice Connector settings in the Amazon Chime Administrator Guide.

a. For Termination settings, select Enabled.

b. For Allowlist, choose New.

c. Enter the CIDR notations of the IP addresses for your internal SIP infrastructure. This allows your infrastructure to access the Amazon Chime Voice Connector. For example, to allow traﬃc from IP address 10.24.34.0, allowlist the CIDR notation 10.24.34.0/32.

d. Choose Add.

e. For Calling plan, select the country or countries to add to your calling plan.

f. Edit any other settings as needed, and choose Save.

3. In the Amazon Chime console, under Voice connectors, view the Outbound host name for your Amazon Chime Voice Connector. For example,

abcdef1ghij2klmno3pqr4.voiceconnector.chime.aws.

4. To join a meeting using the Amazon Chime SDK, use a SIP URI to make a SIP request to the

Outbound host name of your Amazon Chime Voice Connector. Use phone number +17035550122 in the SIP URI. Set the transport parameter to use the TLS protocol. Finally, use the unique join token generated by calling the CreateAttendee API action. For more information, see the following example.

Example Example: SIP request

The following example shows the contents of a SIP URI used to make a SIP request to an Amazon Chime Voice Connector.

sip:[email protected];transport=tls;X-chime- join-token=join-token

The following example shows a sample SIP INVITE message to join an Amazon Chime SDK meeting.

INVITE sip:[email protected];transport=tls;X- chime-join-token=join-token SIP/2.0

Via: SIP/2.0/TLS IPaddress:12345;rport;branch=branch;alias Max-Forwards: 70

From: sip:+12065550100@IPaddress;tag=tag

To: sip:[email protected];X-chime-join- token=join-token

Contact: <sip:+12065550100@IPaddress:54321;transport=TLS;ob>

Call-ID: a1234567-89b0-1c2d-e34f-5gh678j9k2lm CSeq: 6214 INVITE

Allow: PRACK, INVITE, ACK, BYE, CANCEL, UPDATE, INFO, SUBSCRIBE, NOTIFY, REFER, MESSAGE, OPTIONS

Supported: replaces, 100rel, timer, norefersub Session-Expires: 1800

Min-SE: 90

Content-Type: application/sdp Content-Length: 991

v=0o=- 3775321410 3775321410 IN IP4 IPaddress s=pjmedia

b=AS:117

(28)

Amazon Chime SDK event notiﬁcations

t=0 0 a=X-nat:0

m=audio 4000 RTP/SAVP 0 3 8 9 125 101 c=IN IP4 IPaddress

b=TIAS:96000

a=rtcp:4001 IN IP4 IPaddress a=sendrecv

a=rtpmap:0 PCMU/8000 a=rtpmap:3 GSM/8000 a=rtpmap:8 PCMA/8000 a=rtpmap:9 G722/8000 a=rtpmap:125 opus/48000/2 a=fmtp:125 useinbandfec=1

a=rtpmap:101 telephone-event/8000 a=fmtp:101 0-16

a=crypto:1 AEAD_AES_256_GCM inline:EXAMPLE a=crypto:2 AEAD_AES_256_GCM_8 inline:EXAMPLE a=crypto:3 AES_256_CM_HMAC_SHA1_80 inline:EXAMPLE a=crypto:4 AES_256_CM_HMAC_SHA1_32 inline:EXAMPLE a=crypto:5 AES_CM_128_HMAC_SHA1_80 inline:EXAMPLE a=crypto:6 AES_CM_128_HMAC_SHA1_32 inline:EXAMPLE

NoteAmazon Chime recognizes phone numbers only in E.164 format. Make sure that an E.164 phone number is in your From header.

Amazon Chime SDK event notiﬁcations

The Amazon Chime SDK supports sending meeting event notifications to Amazon EventBridge, Amazon Simple Queue Service (Amazon SQS), and Amazon Simple Notification Service (Amazon SNS). As you proceed, remember that the services listed here can go down. As a best practice, app builders should subscribe to multiple notification targets in order to enable higher availability for Chime meeting events.

Note

If you use the Amazon Chime SDK Meetings namespace, remember that you use a diﬀerent service principal. Instead of using the Chime service principal, you use ChimeSDKMeetings. For more information about the namespaces, refer to Migrating to the Amazon Chime SDK Meetings namespace (p. 25).

Sending notiﬁcations to EventBridge

We recommend sending Amazon Chime SDK Event notiﬁcations to EventBridge. Events are emitted on a best-eﬀort basis for Amazon Chime SDK events. For detailed information about using the Amazon Chime SDK with EventBridge, see Automating the Amazon Chime SDK with EventBridge in the Amazon Chime Administrator Guide. For information about EventBridge, see the Amazon EventBridge User Guide.

Sending notiﬁcations to Amazon SQS and Amazon SNS

You can use the CreateMeeting API in the Amazon Chime API Reference to send Amazon Chime SDK meeting event notifications to one Amazon SQS queue and one Amazon SNS topic per meeting. This can help reduce notification latency. For more information about Amazon SQS, see the Amazon Simple Queue Service Developer Guide. For more information about Amazon SNS, see the Amazon Simple Notification Service Developer Guide.

The notiﬁcations sent to Amazon SQS and Amazon SNS contain the same information as the notiﬁcations that Amazon Chime sends to EventBridge. The Amazon Chime SDK supports sending

(29)

Granting the Amazon Chime SDK access to Amazon SQS and Amazon SNS

meeting event notiﬁcations to queues and topics in the US East (N. Virginia) (us-east-1) AWS Region.

Event notiﬁcations might be delivered out of order of occurrence.

Granting the Amazon Chime SDK access to Amazon SQS and Amazon SNS

If you have an Amazon SQS queue or Amazon SNS topic conﬁgured in the us-east-1 Region and you want to send Amazon Chime SDK events to it, you must grant the Amazon Chime SDK permission to publish messages to the Amazon Resource Name (ARN) of the queue or topic. To do this, attach an AWS Identity and Access Management (IAM) policy to the queue or topic that grants the appropriate permissions to the Amazon Chime SDK. For more information, see Identity and access management in Amazon SQS in the Amazon Simple Queue Service Developer Guide and Example cases for Amazon SNS access control in the Amazon Simple Notiﬁcation Service Developer Guide.

Example : Allow the Amazon Chime SDK to publish events to an Amazon SQS queue The following example IAM policy grants the Amazon Chime SDK permission to publish meeting event notiﬁcations to the speciﬁed Amazon SQS queue. The example uses the aws:SourceArn or the aws:SourceAccount statement to address potential Confused Deputy issues. You can use both statements if you want to, but you only need one.

{

"Version": "2008-10-17", "Id": "example-ID", "Statement": [ {

"Sid": "example-statement-ID", "Effect": "Allow",

"Principal": {

"Service": "chime.amazonaws.com"

},

"Action": [

"sqs:SendMessage", "sqs:GetQueueUrl"

],

"Resource": "arn:aws:sqs:us-east-1:111122223333:queueName", "Condition": {

"ArnLike": {

"aws:SourceArn": "arn:>partition<:chime::111122223333:*"

},

"StringEquals": {

"aws:SourceAccount": "111122223333"

} } } ]}

If the Amazon SQS queue is enabled for server-side encryption (SSE), you must take an additional step.

Attach an IAM policy to the associated AWS KMS key that grants the Amazon Chime SDK permission to the AWS KMS actions needed to encrypt data added to the queue.

{ "Version": "2012-10-17", "Id": "example-ID", "Statement": [ {

"Sid": "example-statement-ID", "Effect": "Allow",

(30)

Granting the Amazon Chime SDK access to Amazon SQS and Amazon SNS "Principal": {

},

"Action": [

"kms:GenerateDataKey", "kms:Decrypt"

],

"Resource": "*"

} ] }

Example : Allow the Amazon Chime SDK to publish events to an Amazon SNS topic

The following example IAM policy grants the Amazon Chime SDK permission to publish meeting event notiﬁcations to the speciﬁed Amazon SNS topic.

{ "Version": "2008-10-17", "Id": "example-ID", "Statement": [ {

"Sid": "allow-chime-sdk-access-statement-id", "Effect": "Allow",

"Principal": {

},

"Action": [ "SNS:Publish"

],

"Resource": "arn:aws:sns:us-east-1:111122223333:topicName", "Condition": {

"ArnLike": {

"aws:SourceArn": "arn:partition:chime::111122223333:*"

},

"StringEquals": {

"aws:SourceAccount": "111122223333"

} } } ] }

(31)

Migrating to the Amazon Chime SDK Meetings namespace

Using Amazon Chime SDK meetings

The topics in this section explain how to use Amazon Chime SDK meetings to create custom meeting applications. We recommend following the topics in the order listed.

Topics

• Migrating to the Amazon Chime SDK Meetings namespace (p. 25)

• Meeting regions (p. 27)

• Creating Meetings (p. 30)

• Network conﬁguration (p. 31)

• Meeting events (p. 33)

• Creating Amazon Chime media capture pipelines (p. 41)

• Using Amazon Chime SDK live transcription (p. 49)

Migrating to the Amazon Chime SDK Meetings namespace

The Amazon Chime SDK Meetings namespace is a dedicated place for the APIs that create and manage Amazon Chime SDK meetings. You use the namespace to address Amazon Chime SDK meeting API endpoints in any Region in which they're available. Use this namespace if you're just starting to use the Amazon Chime SDK.

Existing applications that use the Amazon Chime namespace may continue to do so, but you should plan to migrate to the new namespace in order to use updated APIs and new features.

Topics

• Reasons to migrate (p. 25)

• Before you migrate (p. 26)

• Diﬀerences between the namespaces (p. 26)

Reasons to migrate

We encourage you to migrate to the Amazon Chime SDK Meetings namespace for these reasons:

Choice of API Endpoint

The Amazon Chime SDK Meetings namespace is the only API namespace which can use API

endpoints in any region that makes them available. If you want to use API endpoints other than US- EAST-1, you must use the Amazon Chime SDK Meetings namespace.

For more information about how Amazon Chime SDK meetings use AWS regions, refer to Meeting Regions in this guide.

Updated and new meeting APIs

We only add or update meeting APIs in the Amazon Chime SDK Meetings namespace. We fully support the meeting APIs in the Amazon Chime namespace, but they remain as-is.

(32)

Before you migrate

Before you migrate, be aware of the diﬀerences between the namespaces. The following table lists and describes them.

Amazon Chime SDK Meetings

namespace Amazon Chime namespace

AWS SDK namespace ChimeSDKMeetings Chime

Regions multiple US-EAST-1 only

Endpoints https://meetings-

chime.region.amazonaws.com https://

service.chime.aws.amazon.com Service principal meetings.chime.amazonaws.com chime.amazonaws.com

APIs Only APIs for meetings APIs for meetings and other

parts of Amazon Chime

CreateMeeting ExternalMeetingId and

MediaRegion are required ExternalMeetingId and MediaRegion are optional

Tags Not Available Available

Media pipelines Available via US-EAST-1

endpoint Available via US-EAST-1

endpoint SIP media application JoinChimeMeeting action

requires MeetingId JoinChimeMeeting action does not require MeetingId

Direct SIP integration Not Available Available

Diﬀerences between the namespaces

The following sections explain the diﬀerences between the Amazon Chime SDK and Amazon Chime SDK Meetings namespaces.

AWS SDK namespace

The Amazon Chime SDK namespace uses the Chime formal name. The Amazon Chime SDK Meetings namespace uses the ChimeSDKMeetings formal name. The precise format of the name varies by platform.

For example, if you use the AWS SDK in Node.js to create meetings, you use a line of code to address the namespace.

const chimeMeetings = AWS.Chime();

To migrate to the Amazon Chime Meetings SDK, update this line of code with the new namespace and the endpoint region.

const chimeMeetings = AWS.ChimeSDKMeetings({ region: "eu-central-1" });

Regions

(33)

Meeting regions

The Amazon Chime namespace can only address API endpoints in the US-EAST-1 region. The Amazon Chime SDK Meetings namespace can address Amazon Chime SDK meeting API endpoints in any Region they are available. For a current list of meeting Regions, refer to Available regions (p. 17) in this guide.

Endpoints

The Amazon Chime SDK Meetings namespace uses diﬀerent API endpoints than the Amazon Chime namespace.

Only the endpoint used to create a meeting can be used to modify it. This means a meeting created via an endpoint in EU-CENTRAL-1 can only be modiﬁed via EU-CENTRAL-1. It also means you cannot address a meeting created via the Chime namespace with the ChimeSDKMeeting namespace in US- EAST-1.

Service principal

The Amazon Chime SDK Meetings namespace uses a new service principal:

meetings.chime.amazonaws.com. If you have SQS, SNS, or other IAM access policies that grant access to the service, you need to update those polices to grant access to the new service principal.

APIs

The Amazon Chime SDK Meetings namespace only contains APIs to create and manage meetings. The Amazon Chime namespace includes APIs for meetings and other parts of the Amazon Chime service.

CreateMeeting required ﬁelds

In the Amazon Chime SDK Meetings namespace, the CreateMeeting and CreateMeetingWithAttendees APIs require the ExternalMeetingId and MediaRegion ﬁelds to be speciﬁed.

Tagging

A this time, the Amazon Chime SDK Meetings namespace doesn't support tags.

Media pipelines

Amazon Chime Media Pipelines work with meetings created by any meetings endpoint, with either the Amazon Chime SDK Meetings or the Amazon Chime namespace. Refer to Available Regions in the Developer Guide for the latest list of media pipeline regions.

SIP media applications

Amazon Chime SIP Media Applications (SMA) work with meetings created by any meetings endpoint, with either the Amazon Chime SDK Meetings or the Amazon Chime namespace. When using SMA with a meeting created through the Amazon Chime SDK Meetings namespace, the JoinChimeMeeting action requires the MeetingId parameter.

Meeting regions

Amazon Chime SDK meetings have control regions and media regions. A control region has an API endpoint used to create, update and delete meetings, and media regions host the actual meetings.

Typically, your application service uses the AWS SDK to sign and call APIs in the control plane, and your application client uses the Amazon Chime SDK for Javascript, iOS, or Android to connect to the meeting in the media plane.

A control region can create a meeting in any media region. However, you can only update a meeting in the control region used to create it. Meeting events such as AttendeeJoined go to EventBridge,

(34)

Choosing a control region

Amazon Simple Queue Service (SQS), or Amazon Simple Notiﬁcation Service (SNS) in the meeting control region.

For a list of available Amazon Chime SDK meeting control and media regions, refer to Available regions (p. 17) in this guide.

This diagram shows the typical ﬂow of data through the control and media regions.

Choosing a control region

Remember these factors when choosing a control Region for an Amazon Chime SDK meeting:

• Regulatory requirements. Is your application requiried to be within a geopolitical border, or use an endpoint with FIPS 140-2 validated cryptographic modules?

• API latency. Using the control Region nearest to the AWS Region of your application service can help reduce the APIs' network latency. In turn, that helps reduce the time needed to create meetings, and let users join meetings faster.

• High Availability. You can use multiple control Regions to implement a high availability architectures.

However each control Region operates independently. Also, you can only update meetings in the control Region used to create them. Futher, you must use that same region to consume meeting events with EventBridge, Amazon Simple Queue Service (SQS), or Amazon Simple Notiﬁcation Service (SNS).

Choosing a media region

Note

We recommend that you always specify a value in the MediaRegion parameter in the CreateMeeting API action. For more information about the Regions, refer to Available regions (p. 17).

When choosing a media Region to use for your Amazon Chime SDK meeting, common factors to consider include the following:

Regulatory requirements

If your Amazon Chime SDK meetings are subject to regulations requiring them to be hosted within a geopolitical border, consider hardcoding the meeting Region based on ﬁxed application logic.

Amazon Chime

Amazon Chime

Developer Guide

Amazon Chime: Developer Guide

Table of Contents

What is Amazon Chime?

Pricing

Resources

Extending the Amazon Chime desktop client

User management

Invite multiple users

Download user list

Log out multiple users

Update user personal PINs

Integrating chatbots into the Amazon Chime desktop client

Use chatbots with Amazon Chime

Prerequisites

DNS best practices for HTTPS endpoints

Step 1: Integrate a chatbot with Amazon Chime

AWS CLI

Amazon Chime API

AWS SDK for Java

Step 2: Conﬁgure the outbound endpoint for an Amazon Chime chatbot

AWS CLI

Amazon Chime API

AWS SDK for Java

Step 3: Add the chatbot to an Amazon Chime chat room

Authenticate chatbot requests

Update chatbots

Amazon Chime events sent to chatbots

Proxy phone sessions

Webhooks for Amazon Chime

Troubleshooting webhook errors

Using the Amazon Chime SDK

Amazon Chime SDK prerequisites

Amazon Chime SDK concepts

Amazon Chime SDK architecture

Amazon Chime SDK quotas

Amazon Chime SDK system requirements

Available regions

Meeting Regions

Media pipeline Regions

Public Switched Telephone Network (PSTN) Regions

Messaging Regions

Integrating with a client library

SIP integration using an Amazon Chime Voice Connector

Amazon Chime SDK event notiﬁcations

Sending notiﬁcations to EventBridge

Sending notiﬁcations to Amazon SQS and Amazon SNS

Granting the Amazon Chime SDK access to Amazon SQS and Amazon SNS

Using Amazon Chime SDK meetings

Migrating to the Amazon Chime SDK Meetings namespace

Reasons to migrate

Before you migrate

Diﬀerences between the namespaces

Meeting regions

Choosing a control region

Choosing a media region