rooms

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

Overview

Name	rooms
Type	Resource
Id	aws.ivschat.rooms

Fields

The following fields are returned by SELECT queries:

get_room

Name	Datatype	Description
id	string	Room ID, generated by the system. This is a relative identifier, the part of the ARN that uniquely identifies the room. (pattern: <code>[a-zA-Z0-9]+</code>)
name	string	Room name. The value does not need to be unique. (pattern: <code>[a-zA-Z0-9-_]*</code>)
arn	string	Room ARN, from the request (if identifier was an ARN). (pattern: <code>arn:aws:ivschat:[a-z0-9-]+:[0-9]+:room/[a-zA-Z0-9-]+</code>)
create_time	string (date-time)	Time when the room was created. This is an ISO 8601 timestamp; note that this is returned as a string.
logging_configuration_identifiers	array	Array of logging configurations attached to the room.
maximum_message_length	integer	Maximum number of characters in a single message. Messages are expected to be UTF-8 encoded and this limit applies specifically to rune/code-point count, not number of bytes. Default: 500.
maximum_message_rate_per_second	integer	Maximum number of messages per second that can be sent to the room (by all clients). Default: 10.
message_review_handler	object	Configuration information for optional message review.
tags	object	Tags attached to the resource. Array of maps, each of the form string:string (key:value).
update_time	string (date-time)	Time of the room’s last update. This is an ISO 8601 timestamp; note that this is returned as a string.

list_rooms

Name	Datatype	Description
next_token	string	If there are more rooms than maxResults, use nextToken in the request to get the next set.
rooms	array	List of the matching rooms (summary information only).

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_room	select	region		Gets the specified room.
list_rooms	select	region		Gets summary information about all your rooms in the AWS region where the API request is processed. Results are sorted in descending order of updateTime.
create_chat_token	insert	region, roomIdentifier, userId		Creates an encrypted token that is used by a chat participant to establish an individual WebSocket chat connection to a room. When the token is used to connect to chat, the connection is valid for the session duration specified in the request. The token becomes invalid at the token-expiration timestamp included in the response. Use the capabilities field to permit an end user to send messages or moderate a room. The attributes field securely attaches structured data to the chat session; the data is included within each message sent by the end user and received by other participants in the room. Common use cases for attributes include passing end-user profile data like an icon, display name, colors, badges, and other display features. Encryption keys are owned by Amazon IVS Chat and never used directly by your application.
create_room	insert	region		Creates a room that allows clients to connect and pass messages.
update_room	update	region, identifier		Updates a room’s configuration.
delete_message	delete	region		Sends an event to a specific room which directs clients to delete a specific message; that is, unrender it from view and delete it from the client’s chat history. This event’s EventName is aws:DELETE_MESSAGE. This replicates the DeleteMessage WebSocket operation in the Amazon IVS Chat Messaging API.
delete_room	delete	region		Deletes the specified room.
disconnect_user	exec	region, roomIdentifier, userId		Disconnects all connections using a specified user ID from a room. This replicates the DisconnectUser WebSocket operation in the Amazon IVS Chat Messaging API.
send_event	exec	region, roomIdentifier, eventName		Sends an event to a room. Use this within your application’s business logic to send events to clients of a room; e.g., to notify clients to change the way the chat UI is rendered.

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
region	string	AWS region (default: us-east-1)

SELECT examples

get_room

Gets the specified room.

SELECT
id,
name,
arn,
create_time,
logging_configuration_identifiers,
maximum_message_length,
maximum_message_rate_per_second,
message_review_handler,
tags,
update_time
FROM aws.ivschat.rooms
WHERE region = '{{ region }}' -- required
;

list_rooms

Gets summary information about all your rooms in the AWS region where the API request is processed. Results are sorted in descending order of updateTime.

SELECT
next_token,
rooms
FROM aws.ivschat.rooms
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_chat_token

Creates an encrypted token that is used by a chat participant to establish an individual WebSocket chat connection to a room. When the token is used to connect to chat, the connection is valid for the session duration specified in the request. The token becomes invalid at the token-expiration timestamp included in the response. Use the capabilities field to permit an end user to send messages or moderate a room. The attributes field securely attaches structured data to the chat session; the data is included within each message sent by the end user and received by other participants in the room. Common use cases for attributes include passing end-user profile data like an icon, display name, colors, badges, and other display features. Encryption keys are owned by Amazon IVS Chat and never used directly by your application.

INSERT INTO aws.ivschat.rooms (
roomIdentifier,
userId,
capabilities,
sessionDurationInMinutes,
attributes,
region
)
SELECT 
'{{ roomIdentifier }}' /* required */,
'{{ userId }}' /* required */,
'{{ capabilities }}',
{{ sessionDurationInMinutes }},
'{{ attributes }}',
'{{ region }}'
RETURNING
session_expiration_time,
token,
token_expiration_time
;

create_room

Creates a room that allows clients to connect and pass messages.

INSERT INTO aws.ivschat.rooms (
name,
maximumMessageRatePerSecond,
maximumMessageLength,
messageReviewHandler,
tags,
loggingConfigurationIdentifiers,
region
)
SELECT 
'{{ name }}',
{{ maximumMessageRatePerSecond }},
{{ maximumMessageLength }},
'{{ messageReviewHandler }}',
'{{ tags }}',
'{{ loggingConfigurationIdentifiers }}',
'{{ region }}'
RETURNING
id,
name,
arn,
create_time,
logging_configuration_identifiers,
maximum_message_length,
maximum_message_rate_per_second,
message_review_handler,
tags,
update_time
;

Manifest

# Description fields are for documentation purposes
- name: rooms
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the rooms resource.
  - name: roomIdentifier
    value: "{{ roomIdentifier }}"
  - name: userId
    value: "{{ userId }}"
  - name: capabilities
    value:
      - "{{ capabilities }}"
  - name: sessionDurationInMinutes
    value: {{ sessionDurationInMinutes }}
  - name: attributes
    value: "{{ attributes }}"
  - name: name
    value: "{{ name }}"
  - name: maximumMessageRatePerSecond
    value: {{ maximumMessageRatePerSecond }}
  - name: maximumMessageLength
    value: {{ maximumMessageLength }}
  - name: messageReviewHandler
    description: |
      Configuration information for optional message review.
    value:
      uri: "{{ uri }}"
      fallbackResult: "{{ fallbackResult }}"
  - name: tags
    value: "{{ tags }}"
  - name: loggingConfigurationIdentifiers
    value:
      - "{{ loggingConfigurationIdentifiers }}"

UPDATE examples

update_room

Updates a room’s configuration.

UPDATE aws.ivschat.rooms
SET 
identifier = '{{ identifier }}',
name = '{{ name }}',
maximumMessageRatePerSecond = {{ maximumMessageRatePerSecond }},
maximumMessageLength = {{ maximumMessageLength }},
messageReviewHandler = '{{ messageReviewHandler }}',
loggingConfigurationIdentifiers = '{{ loggingConfigurationIdentifiers }}'
WHERE 
region = '{{ region }}' --required
AND identifier = '{{ identifier }}' --required
RETURNING
id,
name,
arn,
create_time,
logging_configuration_identifiers,
maximum_message_length,
maximum_message_rate_per_second,
message_review_handler,
tags,
update_time;

DELETE examples

delete_message

Sends an event to a specific room which directs clients to delete a specific message; that is, unrender it from view and delete it from the client’s chat history. This event’s EventName is aws:DELETE_MESSAGE. This replicates the DeleteMessage WebSocket operation in the Amazon IVS Chat Messaging API.

DELETE FROM aws.ivschat.rooms
WHERE region = '{{ region }}' --required
;

delete_room

Deletes the specified room.

DELETE FROM aws.ivschat.rooms
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

disconnect_user

Disconnects all connections using a specified user ID from a room. This replicates the DisconnectUser WebSocket operation in the Amazon IVS Chat Messaging API.

EXEC aws.ivschat.rooms.disconnect_user 
@region='{{ region }}' --required 
@@json=
'{
"roomIdentifier": "{{ roomIdentifier }}", 
"userId": "{{ userId }}", 
"reason": "{{ reason }}"
}'
;

send_event

Sends an event to a room. Use this within your application’s business logic to send events to clients of a room; e.g., to notify clients to change the way the chat UI is rendered.

EXEC aws.ivschat.rooms.send_event 
@region='{{ region }}' --required 
@@json=
'{
"roomIdentifier": "{{ roomIdentifier }}", 
"eventName": "{{ eventName }}", 
"attributes": "{{ attributes }}"
}'
;