Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

CreateChatToken

Creates an encrypted token that is used to establish an individual WebSocket connection to a room. The token is valid for one minute, and a connection (session) established with the token is valid for the specified duration.

Encryption keys are owned by Amazon IVS Chat and never used directly by your application.

Request Syntax


POST /CreateChatToken HTTP/1.1
Content-type: application/json

{
   "attributes": { 
      "string" : "string" 
   },
   "capabilities": [ "string" ],
   "roomIdentifier": "string",
   "sessionDurationInMinutes": number,
   "userId": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

attributes

Application-provided attributes to encode into the token and attach to a chat session. Map keys and values can contain UTF-8 encoded text. The maximum length of this field is 1 KB total.

Type: String to string map

Required: No

capabilities

Set of capabilities that the user is allowed to perform in the room. Default: None (the capability to view messages is implicitly included in all requests).

Type: Array of strings

Valid Values: SEND_MESSAGE | DISCONNECT_USER | DELETE_MESSAGE

Required: No

roomIdentifier

Identifier of the room that the client is trying to access. Currently this must be an ARN.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: ^arn:aws:ivschat:[a-z0-9-]+:[0-9]+:room/[a-zA-Z0-9-]+$

Required: Yes

sessionDurationInMinutes

Session duration (in minutes), after which the session expires. Default: 60 (1 hour).

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 180.

Required: No

userId

Application-provided ID that uniquely identifies the user associated with this token. This can be any UTF-8 encoded text.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Required: Yes

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "sessionExpirationTime": number,
   "token": "string",
   "tokenExpirationTime": number
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

sessionExpirationTime

Time after which an end user's session is no longer valid. This is an ISO 8601 timestamp; note that this is returned as a string.

Type: Timestamp

token

The issued client token, encrypted.

Type: String

tokenExpirationTime

Time after which the token is no longer valid and cannot be used to connect to a room. This is an ISO 8601 timestamp; note that this is returned as a string.

Type: Timestamp

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

HTTP Status Code: 403

PendingVerification

HTTP Status Code: 403

ResourceNotFoundException

HTTP Status Code: 404

ValidationException

HTTP Status Code: 400