Making SDK calls from a back-end service for Amazon Chime SDK messaging

Once you create a user to represent your back-end services, you create a channel, send messages to that channel, and read messages from that channel.

Run the following CLI command to create a public channel.

aws chime-sdk-messaging create-channel \
    --chime-bearer "app_instance_user_arn" \
    --app-instance-arn "app_instance_arn" \
    --name "firstChannel"

The command produces an ARN in this format: arn:aws:chime:region:aws_account_id:app-instance/app_instance_id/channel/channel_id.

How IAM authorization works for back-end services

In the CLI command from the previous section, note the chime-bearer parameter. It identifies the user that creates or interacts with resources such as channels and messages. Nearly all Amazon Chime SDK messaging APIs take chime-bearer as a parameter, except APIs meant to be called only by developers, such as CreateAppInstance.

The IAM permissions for Amazon Chime SDK messaging APIs require an app-instance-user-arn that matches the chime-bearer parameter. Additional ARNs—typically channel ARNs—might be required based on the API. For back-end services like the example above, this leads to IAM policies like the following example:

JSON

Note the AppInstanceUser ARN and channel ARN in the Resource section. This IAM policy example grants the back-end service permission to make API calls as the user with the ID of "back-end-worker." If you want your back-end service to be able to make calls for the people who use your app, change the app_instance_user_arn to arn:aws:chime:region:aws_account_id:app-instance/app_instance_id/user/*.

Understanding implicit API authorization

In addition to IAM policies, the Amazon Chime SDK messaging APIs have implicit permissions. For example, an AppInstanceUser can only send a message or list a channel membership in channels to which the user belongs. One exception to this is an AppInstanceUser who was promoted to AppInstanceAdmin. By default, admins have permissions to all the channels in your app. For most use cases, you only need this for back-end services that contain significant business logic.

The following CLI command promotes a back-end user to an admin.

aws chime-sdk-identity create-app-instance-admin \
    --app-instance-admin-arn "app_instance_user_arn" \
    --app-instance-arn "app_instance_arn"

Sending and listing channel messages

The following CLI command sends channel messages.

aws chime-sdk-messaging send-channel-message \
    --chime-bearer "app_instance_user_arn" \
    --channel-arn "channel_arn" \
    --content "hello world" \
    --type STANDARD \
    --persistence PERSISTENT

The following CLI commands list channel messages in reverse chronological order.

aws chime-sdk-messaging list-channel-messages \
    --chime-bearer "app_instance_user_arn" \
    --channel-arn "channel_arn"