2021/10/19 - Amazon Chime SDK Messaging - 13 new 5 updated api methods
Changes The Amazon Chime SDK now allows developers to execute business logic on in-flight messages before they are delivered to members of a messaging channel with channel flows.
Calls back Chime SDK Messaging with a processing response message. This should be invoked from the processor Lambda. This is a developer API.
You can return one of the following processing responses:
Update message content or metadata
Deny a message
Make no changes to the message
See also: AWS API Documentation
Request Syntax
client.channel_flow_callback(
CallbackId='string',
ChannelArn='string',
DeleteResource=True|False,
ChannelMessage={
'MessageId': 'string',
'Content': 'string',
'Metadata': 'string'
}
)
string
[REQUIRED]
The identifier passed to the processor by the service when invoked. Use the identifier to call back the service.
This field is autopopulated if not provided.
string
[REQUIRED]
The ARN of the channel.
boolean
When a processor determines that a message needs to be DENIED , pass this parameter with a value of true.
dict
[REQUIRED]
Stores information about the processed message.
MessageId (string) -- [REQUIRED]
The message ID.
Content (string) --
The message content.
Metadata (string) --
The message metadata.
dict
Response Syntax
{
'ChannelArn': 'string',
'CallbackId': 'string'
}
Response Structure
(dict) --
ChannelArn (string) --
The ARN of the channel.
CallbackId (string) --
The call back ID passed in the request.
Returns the full details of a channel flow in an Amazon Chime AppInstance . This is a developer API.
See also: AWS API Documentation
Request Syntax
client.describe_channel_flow(
ChannelFlowArn='string'
)
string
[REQUIRED]
The ARN of the channel flow.
dict
Response Syntax
{
'ChannelFlow': {
'ChannelFlowArn': 'string',
'Processors': [
{
'Name': 'string',
'Configuration': {
'Lambda': {
'ResourceArn': 'string',
'InvocationType': 'ASYNC'
}
},
'ExecutionOrder': 123,
'FallbackAction': 'CONTINUE'|'ABORT'
},
],
'Name': 'string',
'CreatedTimestamp': datetime(2015, 1, 1),
'LastUpdatedTimestamp': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
ChannelFlow (dict) --
The channel flow details.
ChannelFlowArn (string) --
The ARN of the channel flow.
Processors (list) --
Information about the processor Lambda functions.
(dict) --
The information about a processor in a channel flow.
Name (string) --
The name of the channel flow.
Configuration (dict) --
The information about the type of processor and its identifier.
Lambda (dict) --
Indicates that the processor is of type Lambda.
ResourceArn (string) --
The ARN of the Lambda message processing function.
InvocationType (string) --
Controls how the Lambda function is invoked.
ExecutionOrder (integer) --
The sequence in which processors run. If you have multiple processors in a channel flow, message processing goes through each processor in the sequence. The value determines the sequence. At this point, we support only 1 processor within a flow.
FallbackAction (string) --
Determines whether to continue or stop processing if communication with processor fails. If the last processor in a channel flow sequence has a fallback action of CONTINUE, and communication with the processor fails, the message is considered processed and sent to the recipients in the channel.
Name (string) --
The name of the channel flow.
CreatedTimestamp (datetime) --
The time at which the channel flow was created.
LastUpdatedTimestamp (datetime) --
The time at which a channel flow was updated.
Updates channel flow attributes. This is a developer API.
See also: AWS API Documentation
Request Syntax
client.update_channel_flow(
ChannelFlowArn='string',
Processors=[
{
'Name': 'string',
'Configuration': {
'Lambda': {
'ResourceArn': 'string',
'InvocationType': 'ASYNC'
}
},
'ExecutionOrder': 123,
'FallbackAction': 'CONTINUE'|'ABORT'
},
],
Name='string'
)
string
[REQUIRED]
The ARN of the channel flow.
list
[REQUIRED]
Information about the processor Lambda functions
(dict) --
The information about a processor in a channel flow.
Name (string) -- [REQUIRED]
The name of the channel flow.
Configuration (dict) -- [REQUIRED]
The information about the type of processor and its identifier.
Lambda (dict) -- [REQUIRED]
Indicates that the processor is of type Lambda.
ResourceArn (string) -- [REQUIRED]
The ARN of the Lambda message processing function.
InvocationType (string) -- [REQUIRED]
Controls how the Lambda function is invoked.
ExecutionOrder (integer) -- [REQUIRED]
The sequence in which processors run. If you have multiple processors in a channel flow, message processing goes through each processor in the sequence. The value determines the sequence. At this point, we support only 1 processor within a flow.
FallbackAction (string) -- [REQUIRED]
Determines whether to continue or stop processing if communication with processor fails. If the last processor in a channel flow sequence has a fallback action of CONTINUE, and communication with the processor fails, the message is considered processed and sent to the recipients in the channel.
string
[REQUIRED]
The name of the channel flow.
dict
Response Syntax
{
'ChannelFlowArn': 'string'
}
Response Structure
(dict) --
ChannelFlowArn (string) --
The ARN of the channel flow.
Associates a channel flow with a channel. Once associated, all messages to that channel go through channel flow processors. To stop processing, use the DisassociateChannelFlow API.
Note
Only administrators or channel moderators can associate a channel flow. The x-amz-chime-bearer request header is mandatory. Use the AppInstanceUserArn of the user that makes the API call as the value in the header.
See also: AWS API Documentation
Request Syntax
client.associate_channel_flow(
ChannelArn='string',
ChannelFlowArn='string',
ChimeBearer='string'
)
string
[REQUIRED]
The ARN of the channel.
string
[REQUIRED]
The ARN of the channel flow.
string
[REQUIRED]
The AppInstanceUserArn of the user making the API call.
None
Lists the tags applied to an Amazon Chime SDK messaging resource.
See also: AWS API Documentation
Request Syntax
client.list_tags_for_resource(
ResourceARN='string'
)
string
[REQUIRED]
The ARN of the resource.
dict
Response Syntax
{
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
}
Response Structure
(dict) --
Tags (list) --
The tag key-value pairs.
(dict) --
A tag object containing a key-value pair.
Key (string) --
The key in a tag.
Value (string) --
The value in a tag.
Returns a paginated lists of all the channel flows created under a single Chime. This is a developer API.
See also: AWS API Documentation
Request Syntax
client.list_channel_flows(
AppInstanceArn='string',
MaxResults=123,
NextToken='string'
)
string
[REQUIRED]
The ARN of the app instance.
integer
The maximum number of channel flows that you want to return.
string
The token passed by previous API calls until all requested channel flows are returned.
dict
Response Syntax
{
'ChannelFlows': [
{
'ChannelFlowArn': 'string',
'Name': 'string',
'Processors': [
{
'Name': 'string',
'Configuration': {
'Lambda': {
'ResourceArn': 'string',
'InvocationType': 'ASYNC'
}
},
'ExecutionOrder': 123,
'FallbackAction': 'CONTINUE'|'ABORT'
},
]
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
ChannelFlows (list) --
The information about each channel flow.
(dict) --
Summary of details of a channel flow.
ChannelFlowArn (string) --
The ARN of the channel flow.
Name (string) --
The name of the channel flow.
Processors (list) --
Information about the processor Lambda functions.
(dict) --
The information about a processor in a channel flow.
Name (string) --
The name of the channel flow.
Configuration (dict) --
The information about the type of processor and its identifier.
Lambda (dict) --
Indicates that the processor is of type Lambda.
ResourceArn (string) --
The ARN of the Lambda message processing function.
InvocationType (string) --
Controls how the Lambda function is invoked.
ExecutionOrder (integer) --
The sequence in which processors run. If you have multiple processors in a channel flow, message processing goes through each processor in the sequence. The value determines the sequence. At this point, we support only 1 processor within a flow.
FallbackAction (string) --
Determines whether to continue or stop processing if communication with processor fails. If the last processor in a channel flow sequence has a fallback action of CONTINUE, and communication with the processor fails, the message is considered processed and sent to the recipients in the channel.
NextToken (string) --
The token passed by previous API calls until all requested channels are returned.
Disassociates a channel flow from all its channels. Once disassociated, all messages to that channel stop going through the channel flow processor.
Note
Only administrators or channel moderators can disassociate a channel flow. The x-amz-chime-bearer request header is mandatory. Use the AppInstanceUserArn of the user that makes the API call as the value in the header.
See also: AWS API Documentation
Request Syntax
client.disassociate_channel_flow(
ChannelArn='string',
ChannelFlowArn='string',
ChimeBearer='string'
)
string
[REQUIRED]
The ARN of the channel.
string
[REQUIRED]
The ARN of the channel flow.
string
[REQUIRED]
The AppInstanceUserArn of the user making the API call.
None
Creates a channel flow, a container for processors. Processors are AWS Lambda functions that perform actions on chat messages, such as stripping out profanity. You can associate channel flows with channels, and the processors in the channel flow then take action on all messages sent to that channel. This is a developer API.
Channel flows process the following items:
New and updated messages
Persistent and non-persistent messages
The Standard message type
Note
Channel flows don't process Control or System messages. For more information about the message types provided by Chime SDK Messaging, refer to Message types in the Amazon Chime developer guide .
See also: AWS API Documentation
Request Syntax
client.create_channel_flow(
AppInstanceArn='string',
Processors=[
{
'Name': 'string',
'Configuration': {
'Lambda': {
'ResourceArn': 'string',
'InvocationType': 'ASYNC'
}
},
'ExecutionOrder': 123,
'FallbackAction': 'CONTINUE'|'ABORT'
},
],
Name='string',
Tags=[
{
'Key': 'string',
'Value': 'string'
},
],
ClientRequestToken='string'
)
string
[REQUIRED]
The ARN of the channel flow request.
list
[REQUIRED]
Information about the processor Lambda functions.
(dict) --
The information about a processor in a channel flow.
Name (string) -- [REQUIRED]
The name of the channel flow.
Configuration (dict) -- [REQUIRED]
The information about the type of processor and its identifier.
Lambda (dict) -- [REQUIRED]
Indicates that the processor is of type Lambda.
ResourceArn (string) -- [REQUIRED]
The ARN of the Lambda message processing function.
InvocationType (string) -- [REQUIRED]
Controls how the Lambda function is invoked.
ExecutionOrder (integer) -- [REQUIRED]
The sequence in which processors run. If you have multiple processors in a channel flow, message processing goes through each processor in the sequence. The value determines the sequence. At this point, we support only 1 processor within a flow.
FallbackAction (string) -- [REQUIRED]
Determines whether to continue or stop processing if communication with processor fails. If the last processor in a channel flow sequence has a fallback action of CONTINUE, and communication with the processor fails, the message is considered processed and sent to the recipients in the channel.
string
[REQUIRED]
The name of the channel flow.
list
The tags for the creation request.
(dict) --
A tag object containing a key-value pair.
Key (string) -- [REQUIRED]
The key in a tag.
Value (string) -- [REQUIRED]
The value in a tag.
string
[REQUIRED]
The client token for the request. An Idempotency token.
dict
Response Syntax
{
'ChannelFlowArn': 'string'
}
Response Structure
(dict) --
ChannelFlowArn (string) --
The ARN of the channel flow.
Applies the specified tags to the specified Amazon Chime SDK messaging resource.
See also: AWS API Documentation
Request Syntax
client.tag_resource(
ResourceARN='string',
Tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
string
[REQUIRED]
The resource ARN.
list
[REQUIRED]
The tag key-value pairs.
(dict) --
A tag object containing a key-value pair.
Key (string) -- [REQUIRED]
The key in a tag.
Value (string) -- [REQUIRED]
The value in a tag.
None
Deletes a channel flow, an irreversible process. This is a developer API.
Note
This API works only when the channel flow is not associated with any channel. To get a list of all channels that a channel flow is associated with, use the ListChannelsAssociatedWithChannelFlow API. Use the DisassociateChannelFlow API to disassociate a channel flow from all channels.
See also: AWS API Documentation
Request Syntax
client.delete_channel_flow(
ChannelFlowArn='string'
)
string
[REQUIRED]
The ARN of the channel flow.
None
Lists all channels associated with a specified channel flow. You can associate a channel flow with multiple channels, but you can only associate a channel with one channel flow. This is a developer API.
See also: AWS API Documentation
Request Syntax
client.list_channels_associated_with_channel_flow(
ChannelFlowArn='string',
MaxResults=123,
NextToken='string'
)
string
[REQUIRED]
The ARN of the channel flow.
integer
The maximum number of channels that you want to return.
string
The token passed by previous API calls until all requested channels are returned.
dict
Response Syntax
{
'Channels': [
{
'Name': 'string',
'ChannelArn': 'string',
'Mode': 'UNRESTRICTED'|'RESTRICTED',
'Privacy': 'PUBLIC'|'PRIVATE',
'Metadata': 'string'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Channels (list) --
The information about each channel.
(dict) --
Summary of details of a channel associated with channel flow.
Name (string) --
The name of the channel flow.
ChannelArn (string) --
The ARN of the channel.
Mode (string) --
The mode of the channel.
Privacy (string) --
The channel's privacy setting.
Metadata (string) --
The channel's metadata.
NextToken (string) --
The token passed by previous API calls until all requested channels are returned.
Removes the specified tags from the specified Amazon Chime SDK messaging resource.
See also: AWS API Documentation
Request Syntax
client.untag_resource(
ResourceARN='string',
TagKeys=[
'string',
]
)
string
[REQUIRED]
The resource ARN.
list
[REQUIRED]
The tag keys.
(string) --
None
Gets message status for a specified messageId . Use this API to determine the intermediate status of messages going through channel flow processing. The API provides an alternative to retrieving message status if the event was not received because a client wasn't connected to a websocket.
Messages can have any one of these statuses.
SENT
Message processed successfully
PENDING
Ongoing processing
FAILED
Processing failed
DENIED
Messasge denied by the processor
Note
This API does not return statuses for denied messages, because we don't store them once the processor denies them.
Only the message sender can invoke this API.
The x-amz-chime-bearer request header is mandatory. Use the AppInstanceUserArn of the user that makes the API call as the value in the header
See also: AWS API Documentation
Request Syntax
client.get_channel_message_status(
ChannelArn='string',
MessageId='string',
ChimeBearer='string'
)
string
[REQUIRED]
The ARN of the channel
string
[REQUIRED]
The ID of the message.
string
[REQUIRED]
The AppInstanceUserArn of the user making the API call.
dict
Response Syntax
{
'Status': {
'Value': 'SENT'|'PENDING'|'FAILED'|'DENIED',
'Detail': 'string'
}
}
Response Structure
(dict) --
Status (dict) --
The message status and details.
Value (string) --
The message status value.
Detail (string) --
Contains more details about the messasge status.
{'Channel': {'ChannelFlowArn': 'string'}}
Returns the full details of a channel in an Amazon Chime AppInstance .
Note
The x-amz-chime-bearer request header is mandatory. Use the AppInstanceUserArn of the user that makes the API call as the value in the header.
See also: AWS API Documentation
Request Syntax
client.describe_channel(
ChannelArn='string',
ChimeBearer='string'
)
string
[REQUIRED]
The ARN of the channel.
string
[REQUIRED]
The AppInstanceUserArn of the user that makes the API call.
dict
Response Syntax
{
'Channel': {
'Name': 'string',
'ChannelArn': 'string',
'Mode': 'UNRESTRICTED'|'RESTRICTED',
'Privacy': 'PUBLIC'|'PRIVATE',
'Metadata': 'string',
'CreatedBy': {
'Arn': 'string',
'Name': 'string'
},
'CreatedTimestamp': datetime(2015, 1, 1),
'LastMessageTimestamp': datetime(2015, 1, 1),
'LastUpdatedTimestamp': datetime(2015, 1, 1),
'ChannelFlowArn': 'string'
}
}
Response Structure
(dict) --
Channel (dict) --
The channel details.
Name (string) --
The name of a channel.
ChannelArn (string) --
The ARN of a channel.
Mode (string) --
The mode of the channel.
Privacy (string) --
The channel's privacy setting.
Metadata (string) --
The channel's metadata.
CreatedBy (dict) --
The AppInstanceUser who created the channel.
Arn (string) --
The ARN in an Identity.
Name (string) --
The name in an Identity.
CreatedTimestamp (datetime) --
The time at which the AppInstanceUser created the channel.
LastMessageTimestamp (datetime) --
The time at which a member sent the last message in the channel.
LastUpdatedTimestamp (datetime) --
The time at which a channel was last updated.
ChannelFlowArn (string) --
The ARN of the channel flow.
{'ChannelMessage': {'Status': {'Detail': 'string',
'Value': 'SENT | PENDING | FAILED | DENIED'}}}
Gets the full details of a channel message.
Note
The x-amz-chime-bearer request header is mandatory. Use the AppInstanceUserArn of the user that makes the API call as the value in the header.
See also: AWS API Documentation
Request Syntax
client.get_channel_message(
ChannelArn='string',
MessageId='string',
ChimeBearer='string'
)
string
[REQUIRED]
The ARN of the channel.
string
[REQUIRED]
The ID of the message.
string
[REQUIRED]
The AppInstanceUserArn of the user that makes the API call.
dict
Response Syntax
{
'ChannelMessage': {
'ChannelArn': 'string',
'MessageId': 'string',
'Content': 'string',
'Metadata': 'string',
'Type': 'STANDARD'|'CONTROL',
'CreatedTimestamp': datetime(2015, 1, 1),
'LastEditedTimestamp': datetime(2015, 1, 1),
'LastUpdatedTimestamp': datetime(2015, 1, 1),
'Sender': {
'Arn': 'string',
'Name': 'string'
},
'Redacted': True|False,
'Persistence': 'PERSISTENT'|'NON_PERSISTENT',
'Status': {
'Value': 'SENT'|'PENDING'|'FAILED'|'DENIED',
'Detail': 'string'
}
}
}
Response Structure
(dict) --
ChannelMessage (dict) --
The details of and content in the message.
ChannelArn (string) --
The ARN of the channel.
MessageId (string) --
The ID of a message.
Content (string) --
The message content.
Metadata (string) --
The message metadata.
Type (string) --
The message type.
CreatedTimestamp (datetime) --
The time at which the message was created.
LastEditedTimestamp (datetime) --
The time at which a message was edited.
LastUpdatedTimestamp (datetime) --
The time at which a message was updated.
Sender (dict) --
The message sender.
Arn (string) --
The ARN in an Identity.
Name (string) --
The name in an Identity.
Redacted (boolean) --
Hides the content of a message.
Persistence (string) --
The persistence setting for a channel message.
Status (dict) --
The status of the channel message.
Value (string) --
The message status value.
Detail (string) --
Contains more details about the messasge status.
{'ChannelMessages': {'Status': {'Detail': 'string',
'Value': 'SENT | PENDING | FAILED | DENIED'}}}
List all the messages in a channel. Returns a paginated list of ChannelMessages . By default, sorted by creation timestamp in descending order.
Note
Redacted messages appear in the results as empty, since they are only redacted, not deleted. Deleted messages do not appear in the results. This action always returns the latest version of an edited message.
Also, the x-amz-chime-bearer request header is mandatory. Use the AppInstanceUserArn of the user that makes the API call as the value in the header.
See also: AWS API Documentation
Request Syntax
client.list_channel_messages(
ChannelArn='string',
SortOrder='ASCENDING'|'DESCENDING',
NotBefore=datetime(2015, 1, 1),
NotAfter=datetime(2015, 1, 1),
MaxResults=123,
NextToken='string',
ChimeBearer='string'
)
string
[REQUIRED]
The ARN of the channel.
string
The order in which you want messages sorted. Default is Descending, based on time created.
datetime
The initial or starting time stamp for your requested messages.
datetime
The final or ending time stamp for your requested messages.
integer
The maximum number of messages that you want returned.
string
The token passed by previous API calls until all requested messages are returned.
string
[REQUIRED]
The AppInstanceUserArn of the user that makes the API call.
dict
Response Syntax
{
'ChannelArn': 'string',
'NextToken': 'string',
'ChannelMessages': [
{
'MessageId': 'string',
'Content': 'string',
'Metadata': 'string',
'Type': 'STANDARD'|'CONTROL',
'CreatedTimestamp': datetime(2015, 1, 1),
'LastUpdatedTimestamp': datetime(2015, 1, 1),
'LastEditedTimestamp': datetime(2015, 1, 1),
'Sender': {
'Arn': 'string',
'Name': 'string'
},
'Redacted': True|False,
'Status': {
'Value': 'SENT'|'PENDING'|'FAILED'|'DENIED',
'Detail': 'string'
}
},
]
}
Response Structure
(dict) --
ChannelArn (string) --
The ARN of the channel containing the requested messages.
NextToken (string) --
The token passed by previous API calls until all requested messages are returned.
ChannelMessages (list) --
The information about, and content of, each requested message.
(dict) --
Summary of the messages in a Channel .
MessageId (string) --
The ID of the message.
Content (string) --
The content of the message.
Metadata (string) --
The metadata of the message.
Type (string) --
The type of message.
CreatedTimestamp (datetime) --
The time at which the message summary was created.
LastUpdatedTimestamp (datetime) --
The time at which a message was last updated.
LastEditedTimestamp (datetime) --
The time at which a message was last edited.
Sender (dict) --
The message sender.
Arn (string) --
The ARN in an Identity.
Name (string) --
The name in an Identity.
Redacted (boolean) --
Indicates whether a message was redacted.
Status (dict) --
The message status. The status value is SENT for messages sent to a channel without a channel flow. For channels associated with channel flow, the value determines the processing stage.
Value (string) --
The message status value.
Detail (string) --
Contains more details about the messasge status.
{'Status': {'Detail': 'string', 'Value': 'SENT | PENDING | FAILED | DENIED'}}
Sends a message to a particular channel that the member is a part of.
Note
The x-amz-chime-bearer request header is mandatory. Use the AppInstanceUserArn of the user that makes the API call as the value in the header.
Also, STANDARD messages can contain 4KB of data and the 1KB of metadata. CONTROL messages can contain 30 bytes of data and no metadata.
See also: AWS API Documentation
Request Syntax
client.send_channel_message(
ChannelArn='string',
Content='string',
Type='STANDARD'|'CONTROL',
Persistence='PERSISTENT'|'NON_PERSISTENT',
Metadata='string',
ClientRequestToken='string',
ChimeBearer='string'
)
string
[REQUIRED]
The ARN of the channel.
string
[REQUIRED]
The content of the message.
string
[REQUIRED]
The type of message, STANDARD or CONTROL .
string
[REQUIRED]
Boolean that controls whether the message is persisted on the back end. Required.
string
The optional metadata for each message.
string
[REQUIRED]
The Idempotency token for each client request.
This field is autopopulated if not provided.
string
[REQUIRED]
The AppInstanceUserArn of the user that makes the API call.
dict
Response Syntax
{
'ChannelArn': 'string',
'MessageId': 'string',
'Status': {
'Value': 'SENT'|'PENDING'|'FAILED'|'DENIED',
'Detail': 'string'
}
}
Response Structure
(dict) --
ChannelArn (string) --
The ARN of the channel.
MessageId (string) --
The ID string assigned to each message.
Status (dict) --
The status of the channel message.
Value (string) --
The message status value.
Detail (string) --
Contains more details about the messasge status.
{'Status': {'Detail': 'string', 'Value': 'SENT | PENDING | FAILED | DENIED'}}
Updates the content of a message.
Note
The x-amz-chime-bearer request header is mandatory. Use the AppInstanceUserArn of the user that makes the API call as the value in the header.
See also: AWS API Documentation
Request Syntax
client.update_channel_message(
ChannelArn='string',
MessageId='string',
Content='string',
Metadata='string',
ChimeBearer='string'
)
string
[REQUIRED]
The ARN of the channel.
string
[REQUIRED]
The ID string of the message being updated.
string
The content of the message being updated.
string
The metadata of the message being updated.
string
[REQUIRED]
The AppInstanceUserArn of the user that makes the API call.
dict
Response Syntax
{
'ChannelArn': 'string',
'MessageId': 'string',
'Status': {
'Value': 'SENT'|'PENDING'|'FAILED'|'DENIED',
'Detail': 'string'
}
}
Response Structure
(dict) --
ChannelArn (string) --
The ARN of the channel.
MessageId (string) --
The ID string of the message being updated.
Status (dict) --
The status of the message update.
Value (string) --
The message status value.
Detail (string) --
Contains more details about the messasge status.