channels

Creates, updates, deletes, gets or lists a channels resource.

Overview

Name	channels
Type	Resource
Id	aws.chime_sdk_messaging.channels

Fields

The following fields are returned by SELECT queries:

list_channels

Name	Datatype	Description
channels	array	The information about each channel.
next_token	string	The token returned from previous API requests until the number of channels is reached. (pattern: <code>.*</code>)

describe_channel

Name	Datatype	Description
channel_arn	string	The ARN of a channel. (pattern: <code>arn:[a-z0-9-.]{1,63}:[a-z0-9-.]{0,63}:[a-z0-9-.]{0,63}:[a-z0-9-.]{0,63}:[^/].{0,1023}</code>)
channel_flow_arn	string	The ARN of the channel flow. (pattern: <code>arn:[a-z0-9-.]{1,63}:[a-z0-9-.]{0,63}:[a-z0-9-.]{0,63}:[a-z0-9-.]{0,63}:[^/].{0,1023}</code>)
created_by	object	The details of a user or bot.
created_timestamp	string (date-time)	The time at which the AppInstanceUser created the channel.
elastic_channel_configuration	object	The attributes required to configure and create an elastic channel. An elastic channel can support a maximum of 1-million members.
expiration_settings	object	Settings that control the interval after which a channel is deleted.
last_message_timestamp	string (date-time)	The time at which a member sent the last message in the channel.
last_updated_timestamp	string (date-time)	The time at which a channel was last updated.
metadata	string	The channel's metadata. (pattern: <code>.*</code>)
mode	string	The mode of the channel. (UNRESTRICTED, RESTRICTED)
name	string	The name of a channel. (pattern: <code>[\u0009\u000A\u000D\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFFFD\u10000-\u10FFFF]*</code>)
privacy	string	The channel's privacy setting. (PUBLIC, PRIVATE)

search_channels

Name	Datatype	Description
channels	array	A list of the channels in the request.
next_token	string	The token returned from previous API responses until the number of channels is reached. (pattern: <code>.*</code>)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_channels	select	app-instance-arn, x-amz-chime-bearer, region	privacy, max-results, next-token	Lists all Channels created under a single Chime App as a paginated list. You can specify filters to narrow results. Functionality & restrictions Use privacy = PUBLIC to retrieve all public channels in the account. Only an AppInstanceAdmin can set privacy = PRIVATE to list the private channels in an account. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUser or AppInstanceBot that makes the API call as the value in the header.
describe_channel	select	channel_arn, x-amz-chime-bearer, region		Returns the full details of a channel in an Amazon Chime AppInstance. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUser or AppInstanceBot that makes the API call as the value in the header.
search_channels	select	region	x-amz-chime-bearer, max-results, next-token	Allows the ChimeBearer to search channels by channel members. Users or bots can search across the channels that they belong to. Users in the AppInstanceAdmin role can search across all channels. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUser or AppInstanceBot that makes the API call as the value in the header. This operation isn't supported for AppInstanceUsers with a large number of memberships.
create_channel	insert	x-amz-chime-bearer, region, AppInstanceArn, Name, ClientRequestToken		Creates a channel to which you can add users and send messages. Restriction: You can't change a channel's privacy. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUser or AppInstanceBot that makes the API call as the value in the header.
update_channel	update	channel_arn, x-amz-chime-bearer, region		Update a channel's attributes. Restriction: You can't change a channel's privacy. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUser or AppInstanceBot that makes the API call as the value in the header.
put_channel_expiration_settings	replace	channel_arn, region	x-amz-chime-bearer	Sets the number of days before the channel is automatically deleted. A background process deletes expired channels within 6 hours of expiration. Actual deletion times may vary. Expired channels that have not yet been deleted appear as active, and you can update their expiration settings. The system honors the new settings. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUser or AppInstanceBot that makes the API call as the value in the header.
delete_channel	delete	channel_arn, x-amz-chime-bearer, region		Immediately makes a channel and its memberships inaccessible and marks them for deletion. This is an irreversible process. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUserArn or AppInstanceBot that makes the API call as the value in the header.
batch_create_channel_membership	exec	channel_arn, x-amz-chime-bearer, region, MemberArns		Adds a specified number of users and bots to a channel.
send_channel_message	exec	channel_arn, x-amz-chime-bearer, region, Content, Type, Persistence, ClientRequestToken		Sends a message to a particular channel that the member is a part of. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUser or AppInstanceBot that makes the API call as the value in the header. Also, STANDARD messages can be up to 4KB in size and contain metadata. Metadata is arbitrary, and you can use it in a variety of ways, such as containing a link to an attachment. CONTROL messages are limited to 30 bytes and do not contain metadata.
redact_channel_message	exec	channel_arn, message_id, x-amz-chime-bearer, region		Redacts message content and metadata. The message exists in the back end, but the action returns null content, and the state shows as redacted. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUser or AppInstanceBot that makes the API call as the value in the header.
update_channel_read_marker	exec	channel_arn, x-amz-chime-bearer, region		The details of the time when a user last read messages in a channel. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUser or AppInstanceBot that makes the API call as the value in the header.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
app-instance-arn	string	The ARN of the AppInstance.
channel_arn	string	The ARN of the channel.
message_id	string	The ID of the message being redacted.
region	string	AWS region (default: us-east-1)
x-amz-chime-bearer	string	The ARN of the AppInstanceUser or AppInstanceBot that makes the API call.
max-results	integer	The maximum number of channels that you want returned.
next-token	string	The token returned from previous API requests until the number of channels is reached.
privacy	string	The privacy setting. PUBLIC retrieves all the public channels. PRIVATE retrieves private channels. Only an AppInstanceAdmin can retrieve private channels.
x-amz-chime-bearer	string	The ARN of the AppInstanceUser or AppInstanceBot that makes the API call.

SELECT examples

list_channels

Lists all Channels created under a single Chime App as a paginated list. You can specify filters to narrow results. Functionality & restrictions Use privacy = PUBLIC to retrieve all public channels in the account. Only an AppInstanceAdmin can set privacy = PRIVATE to list the private channels in an account. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUser or AppInstanceBot that makes the API call as the value in the header.

SELECT
channels,
next_token
FROM aws.chime_sdk_messaging.channels
WHERE `app-instance-arn` = '{{ app-instance-arn }}' -- required
AND `x-amz-chime-bearer` = '{{ x-amz-chime-bearer }}' -- required
AND region = '{{ region }}' -- required
AND privacy = '{{ privacy }}'
AND `max-results` = '{{ max-results }}'
AND `next-token` = '{{ next-token }}'
;

describe_channel

Returns the full details of a channel in an Amazon Chime AppInstance. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUser or AppInstanceBot that makes the API call as the value in the header.

SELECT
channel_arn,
channel_flow_arn,
created_by,
created_timestamp,
elastic_channel_configuration,
expiration_settings,
last_message_timestamp,
last_updated_timestamp,
metadata,
mode,
name,
privacy
FROM aws.chime_sdk_messaging.channels
WHERE channel_arn = '{{ channel_arn }}' -- required
AND `x-amz-chime-bearer` = '{{ x-amz-chime-bearer }}' -- required
AND region = '{{ region }}' -- required
;

search_channels

Allows the ChimeBearer to search channels by channel members. Users or bots can search across the channels that they belong to. Users in the AppInstanceAdmin role can search across all channels. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUser or AppInstanceBot that makes the API call as the value in the header. This operation isn't supported for AppInstanceUsers with a large number of memberships.

SELECT
channels,
next_token
FROM aws.chime_sdk_messaging.channels
WHERE region = '{{ region }}' -- required
AND `x-amz-chime-bearer` = '{{ x-amz-chime-bearer }}'
AND `max-results` = '{{ max-results }}'
AND `next-token` = '{{ next-token }}'
;

INSERT examples

create_channel

Creates a channel to which you can add users and send messages. Restriction: You can't change a channel's privacy. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUser or AppInstanceBot that makes the API call as the value in the header.

INSERT INTO aws.chime_sdk_messaging.channels (
AppInstanceArn,
Name,
Mode,
Privacy,
Metadata,
ClientRequestToken,
Tags,
ChannelId,
MemberArns,
ModeratorArns,
ElasticChannelConfiguration,
ExpirationSettings,
`x-amz-chime-bearer`,
region
)
SELECT 
'{{ AppInstanceArn }}' /* required */,
'{{ Name }}' /* required */,
'{{ Mode }}',
'{{ Privacy }}',
'{{ Metadata }}',
'{{ ClientRequestToken }}' /* required */,
'{{ Tags }}',
'{{ ChannelId }}',
'{{ MemberArns }}',
'{{ ModeratorArns }}',
'{{ ElasticChannelConfiguration }}',
'{{ ExpirationSettings }}',
'{{ x-amz-chime-bearer }}',
'{{ region }}'
RETURNING
channel_arn
;

Manifest

# Description fields are for documentation purposes
- name: channels
props:
  - name: x-amz-chime-bearer
    value: "{{ x-amz-chime-bearer }}"
    description: Required parameter for the channels resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the channels resource.
  - name: AppInstanceArn
    value: "{{ AppInstanceArn }}"
  - name: Name
    value: "{{ Name }}"
  - name: Mode
    value: "{{ Mode }}"
    valid_values: ['UNRESTRICTED', 'RESTRICTED']
  - name: Privacy
    value: "{{ Privacy }}"
    valid_values: ['PUBLIC', 'PRIVATE']
  - name: Metadata
    value: "{{ Metadata }}"
  - name: ClientRequestToken
    value: "{{ ClientRequestToken }}"
  - name: Tags
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"
  - name: ChannelId
    value: "{{ ChannelId }}"
  - name: MemberArns
    value:
      - "{{ MemberArns }}"
  - name: ModeratorArns
    value:
      - "{{ ModeratorArns }}"
  - name: ElasticChannelConfiguration
    description: |
      The attributes required to configure and create an elastic channel. An elastic channel can support a maximum of 1-million members.
    value:
      MaximumSubChannels: {{ MaximumSubChannels }}
      TargetMembershipsPerSubChannel: {{ TargetMembershipsPerSubChannel }}
      MinimumMembershipPercentage: {{ MinimumMembershipPercentage }}
  - name: ExpirationSettings
    description: |
      Settings that control the interval after which a channel is deleted.
    value:
      ExpirationDays: {{ ExpirationDays }}
      ExpirationCriterion: "{{ ExpirationCriterion }}"

UPDATE examples

update_channel

Update a channel's attributes. Restriction: You can't change a channel's privacy. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUser or AppInstanceBot that makes the API call as the value in the header.

UPDATE aws.chime_sdk_messaging.channels
SET 
Name = '{{ Name }}',
Mode = '{{ Mode }}',
Metadata = '{{ Metadata }}'
WHERE 
channel_arn = '{{ channel_arn }}' --required
AND `x-amz-chime-bearer` = '{{ x-amz-chime-bearer }}' --required
AND region = '{{ region }}' --required
RETURNING
channel_arn;

REPLACE examples

put_channel_expiration_settings

Sets the number of days before the channel is automatically deleted. A background process deletes expired channels within 6 hours of expiration. Actual deletion times may vary. Expired channels that have not yet been deleted appear as active, and you can update their expiration settings. The system honors the new settings. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUser or AppInstanceBot that makes the API call as the value in the header.

REPLACE aws.chime_sdk_messaging.channels
SET 
ExpirationSettings = '{{ ExpirationSettings }}'
WHERE 
channel_arn = '{{ channel_arn }}' --required
AND region = '{{ region }}' --required
AND `x-amz-chime-bearer` = '{{ x-amz-chime-bearer}}'
RETURNING
channel_arn,
expiration_settings;

DELETE examples

delete_channel

Immediately makes a channel and its memberships inaccessible and marks them for deletion. This is an irreversible process. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUserArn or AppInstanceBot that makes the API call as the value in the header.

DELETE FROM aws.chime_sdk_messaging.channels
WHERE channel_arn = '{{ channel_arn }}' --required
AND `x-amz-chime-bearer` = '{{ x-amz-chime-bearer }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

batch_create_channel_membership

Adds a specified number of users and bots to a channel.

EXEC aws.chime_sdk_messaging.channels.batch_create_channel_membership 
@channel_arn='{{ channel_arn }}' --required, 
@x-amz-chime-bearer='{{ x-amz-chime-bearer }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"Type": "{{ Type }}", 
"MemberArns": "{{ MemberArns }}", 
"SubChannelId": "{{ SubChannelId }}"
}'
;

send_channel_message

Sends a message to a particular channel that the member is a part of. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUser or AppInstanceBot that makes the API call as the value in the header. Also, STANDARD messages can be up to 4KB in size and contain metadata. Metadata is arbitrary, and you can use it in a variety of ways, such as containing a link to an attachment. CONTROL messages are limited to 30 bytes and do not contain metadata.

EXEC aws.chime_sdk_messaging.channels.send_channel_message 
@channel_arn='{{ channel_arn }}' --required, 
@x-amz-chime-bearer='{{ x-amz-chime-bearer }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"Content": "{{ Content }}", 
"Type": "{{ Type }}", 
"Persistence": "{{ Persistence }}", 
"Metadata": "{{ Metadata }}", 
"ClientRequestToken": "{{ ClientRequestToken }}", 
"PushNotification": "{{ PushNotification }}", 
"MessageAttributes": "{{ MessageAttributes }}", 
"SubChannelId": "{{ SubChannelId }}", 
"ContentType": "{{ ContentType }}", 
"Target": "{{ Target }}"
}'
;

redact_channel_message

Redacts message content and metadata. The message exists in the back end, but the action returns null content, and the state shows as redacted. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUser or AppInstanceBot that makes the API call as the value in the header.

EXEC aws.chime_sdk_messaging.channels.redact_channel_message 
@channel_arn='{{ channel_arn }}' --required, 
@message_id='{{ message_id }}' --required, 
@x-amz-chime-bearer='{{ x-amz-chime-bearer }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"SubChannelId": "{{ SubChannelId }}"
}'
;

update_channel_read_marker

The details of the time when a user last read messages in a channel. The x-amz-chime-bearer request header is mandatory. Use the ARN of the AppInstanceUser or AppInstanceBot that makes the API call as the value in the header.

EXEC aws.chime_sdk_messaging.channels.update_channel_read_marker 
@channel_arn='{{ channel_arn }}' --required, 
@x-amz-chime-bearer='{{ x-amz-chime-bearer }}' --required, 
@region='{{ region }}' --required
;