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

CreateStreamSessionConnection

Enables clients to reconnect to a stream session while preserving all session state and data in the disconnected session. This reconnection process can be initiated when a stream session is in either PENDING_CLIENT_RECONNECTION or ACTIVE status. The process works as follows:

Initial disconnect:
- When a client disconnects or loses connection, the stream session transitions from CONNECTED to PENDING_CLIENT_RECONNECTION
Reconnection time window:
- Clients have ConnectionTimeoutSeconds (defined in StartStreamSession) to reconnect before session termination
- Your backend server must call CreateStreamSessionConnection to initiate reconnection
- Session transitions to RECONNECTING status
Reconnection completion:
- On successful CreateStreamSessionConnection, session status changes to ACTIVE
- Provide the new connection information to the requesting client
- Client must establish connection within ConnectionTimeoutSeconds
- Session terminates automatically if client fails to connect in time

For more information about the stream session lifecycle, see Stream sessions in the Amazon GameLift Streams Developer Guide.

To begin re-connecting to an existing stream session, specify the stream group ID and stream session ID that you want to reconnect to, and the signal request to use with the stream.

Request Syntax


POST /streamgroups/Identifier/streamsessions/StreamSessionIdentifier/connections HTTP/1.1
Content-type: application/json

{
   "ClientToken": "string",
   "SignalRequest": "string"
}

URI Request Parameters

The request uses the following URI parameters.

Identifier

Amazon Resource Name (ARN) or ID that uniquely identifies the stream group resource. Example ARN: arn:aws:gameliftstreams:us-west-2:111122223333:streamgroup/sg-1AB2C3De4. Example ID: sg-1AB2C3De4.

The stream group that you want to run this stream session with. The stream group must be in ACTIVE status.

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

Pattern: (^[a-zA-Z0-9-]+$)|(^arn:aws:gameliftstreams:([^: ]*):([0-9]{12}):([^: ]*)$)

Required: Yes

StreamSessionIdentifier

Amazon Resource Name (ARN) or ID that uniquely identifies the stream session resource. Example ARN: arn:aws:gameliftstreams:us-west-2:111122223333:streamsession/sg-1AB2C3De4/ABC123def4567. Example ID: ABC123def4567.

The stream session must be in PENDING_CLIENT_RECONNECTION or ACTIVE status.

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

Pattern: (^[a-zA-Z0-9-]+$)|(^arn:aws:gameliftstreams:([^: ]*):([0-9]{12}):([^: ]*)$)

Required: Yes

Request Body

The request accepts the following data in JSON format.

SignalRequest

A WebRTC ICE offer string to use when initializing a WebRTC connection. The offer is a very long JSON string. Provide the string as a text value in quotes. The offer must be newly generated, not the same offer provided to StartStreamSession.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes

ClientToken

A unique identifier that represents a client request. The request is idempotent, which ensures that an API request completes only once. When users send a request, Amazon GameLift Streams automatically populates this field.

Type: String

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

Pattern: [\x21-\x7E]+

Required: No

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "SignalResponse": "string"
}

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.

SignalResponse

The WebRTC answer string that the stream server generates in response to the SignalRequest.

Type: String

Errors

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

AccessDeniedException

You don't have the required permissions to access this Amazon GameLift Streams resource. Correct the permissions before you try again.

HTTP Status Code: 403

ConflictException

The requested operation would cause a conflict with the current state of a service resource associated with the request. Resolve the conflict before retrying this request.

HTTP Status Code: 409

InternalServerException

The service encountered an internal error and is unable to complete the request.

HTTP Status Code: 500

ResourceNotFoundException

The resource specified in the request was not found. Correct the request before you try again.

HTTP Status Code: 404

ThrottlingException

The request was denied due to request throttling. Retry the request after the suggested wait time.

HTTP Status Code: 429

ValidationException

One or more parameter values in the request fail to satisfy the specified constraints. Correct the invalid parameter values before retrying the request.

HTTP Status Code: 400