# API reference **Topics** + [ # WebSocket endpoint APIs ](api-endpoint.md) + [ # Asynchronous message reception ](async-message-reception-api.md) # WebSocket endpoint APIs The following are the Amazon Kinesis Video Streams with WebRTC WebSocket endpoint APIs: **Topics** + [ # ConnectAsMaster ](ConnectAsMaster.md) + [ # ConnectAsViewer ](ConnectAsViewer.md) # ConnectAsMaster Connects as a master to the signaling channel specified by the endpoint. Any WebSocket-complaint library can be used to connect to the secure websocket (WSS) endpoint obtained from a `GetSignalingChannelEndpoint` API call. The Amazon Resource Name (ARN) of the signaling channel must be provided as a query string parameter. There are separate endpoints for connecting as a master and as a viewer. If more than one client connects as master to a specific channel, then the most recent request takes precedence. Existing connection metadata is overwritten by the new one. ## Request ``` "X-Amz-ChannelARN": "string" ``` + **X-Amz-ChannelARN** - ARN of the signaling channel. + Type: string + Length constraints: Minimum length of 1. Maximum length of 1024. + Pattern: `arn:aws:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/[0-9]+` + Required: Yes ## Response 200 OK HTTP status code with an empty body. ## Errors + InvalidArgumentException A specified parameter exceeds its restrictions, is not supported, or cannot be used. For more information, see the returned message. HTTP Status Code: 400 + AccessDeniedException The caller is not authorized to access the given channel or the token has expired. HTTP Status Code: 403 + ResourceNotFoundException The channel doesn't exist. HTTP Status Code: 404 + ClientLimitExceededException When the API is invoked at a rate that is too high. For more information, see [Amazon Kinesis Video Streams with WebRTC service quotas](kvswebrtc-limits.md) and [Error Retries and Exponential Backoff in AWS](https://docs.aws.amazon.com/general/latest/gr/api-retries.html). HTTP Status Code: 400 ## Limits/Throttling This API is throttled at an account level if the API is invoked at too high a rate. An error returned when throttled with `ClientLimitExceededException`. ## Idempotent If a connection already exists for the specified clientId and channel, the connection metadata is updated with the new information. ## Retry behavior This is counted as a new API call. ## Concurrent calls Concurrent calls are allowed, the connection metadata is updated for each call. # ConnectAsViewer Connects as a viewer to the signaling channel specified by the endpoint. Any WebSocket-compliant library can be used to connect to the secure websocket (WSS) endpoint obtained from the `GetSignalingChannelEndpoint` API call. The Amazon Resource Name (ARN) of the signaling channel and the client ID must be provided as query string parameters. There are separate endpoints for connecting as a master and as a viewer. If there is an existing connection with the same `ClientId` as specified in the request, the new connection takes precedence. The connection metadata is overwritten with the new information. ## Request ``` "X-Amz-ChannelARN": "string", "X-Amz-ClientId": "string" ``` + **X-Amz-ChannelARN** - ARN of the signaling channel. + Type: string + Length constraints: Minimum length of 1. Maximum length of 1024 + Pattern: `arn:aws:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/[0-9]+` + Required: Yes + **X-Amz-ClientId** - A unique identifier for the client. + Type: string + Length constraints: Minimum length of 1. Maximum length of 256. + Pattern: `^(?!(?i)AWS_.*)[a-zA-Z0-9_.-]` **Note** `X-Amz-ClientId` can't start with `AWS_`. + Required: Yes ## Response 200 OK HTTP status code with an empty body. ## Errors + InvalidArgumentException A specified parameter exceeds its restrictions, is not supported, or cannot be used. For more information, see the returned message. HTTP Status Code: 400 + AccessDeniedException The caller is not authorized to access the given channel or the token has expired. HTTP Status Code: 403 + ResourceNotFoundException The channel doesn't exist. HTTP Status Code: 404 + ClientLimitExceededException When the API is invoked at a rate that is too high or when there are more than the supported maximum number of viewers connected to the channel. For more information, see [Amazon Kinesis Video Streams with WebRTC service quotas](kvswebrtc-limits.md) and [Error Retries and Exponential Backoff in AWS](https://docs.aws.amazon.com/general/latest/gr/api-retries.html). HTTP Status Code: 400 ## Limits/Throttling This API is throttled at an account level if the API is invoked at too high a rate or when there are more than the supported maximum number of viewers connected to the channel. An error returned when throttled with `ClientLimitExceededException`. ## Idempotent If a connection already exists for the specified `ClientId` and channel, the connection metadata is updated with the new information. ## Retry behavior This is counted as a new API call. ## Concurrent calls Concurrent calls are allowed, the connection metadata is updated for each call. # Asynchronous message reception All response messages are asynchronously delivered to the recipient as events (for example, an SDP offer or SDP answer delivery). The following is the event message structure. ## Event ``` { "senderClientId": "string", "messageType": "string", "messagePayload": "string", "statusResponse": { "correlationId": "string", "errorType": "string", "statusCode": "string", "description": "string" } } ``` + **senderClientId** - A unique identifier for the sender client. + Type: String + Length constraints: Minimum length of 1. Maximum length of 256. + Pattern: `[a-zA-Z0-9_.-]+` + Required: No + **messageType** - Type of the event. + Type: ENUM + Valid Types: `SDP_OFFER`, `SDP_ANSWER`, `ICE_CANDIDATE`, `GO_AWAY`, `RECONNECT_ICE_SERVER`, `STATUS_RESPONSE` + Length constraints: Minimum length of 1. Maximum length of 256. + Pattern: `[a-zA-Z0-9_.-]+` + Required: Yes + **messagePayload** - The base64-encoded message content. + Type: String + Length constraints: Minimum length of 1. Maximum length of 10K. + Required: No + **correlationId** - An unique identifier of the message for which the status is meant. This is the same correlationId provided in the client messages (for example, SDP offer, SDP answer, or ICE candidate). + Type: String + Length constraints: Minimum length of 1. Maximum length of 256. + Pattern: `[a-zA-Z0-9_.-]+` + Required: Yes + **errorType** - A name to uniquely identify the error. + Type: String + Length constraints: Minimum length of 1. Maximum length of 256. + Pattern: `[a-zA-Z0-9_.-]+` + Required: No + **statusCode** - HTTP status code corresponding to the nature of the response. + Type: String + Length constraints: Minimum length of 1. Maximum length of 256. + Pattern: `[a-zA-Z0-9_.-]+` + Required: No + **description** - A string description explaining the status. + Type: String + Length constraints: Minimum length of 1. Maximum length of 1K. + Required: No # SendSdpOffer Sends the offer to the target recipient. The prerequisite is that the client must be already connected to the WebSocket endpoint obtained from the `GetSignalingChannelEndpoint` API. If the sender type is a viewer, then it sends the offer to a master. Also, it is not necessary to specify the `RecipientClientId` and any specified value for `RecipientClientId` is ignored. If the sender type is master, the offer is sent to the target viewer specified by the `RecipientClientId`. `RecipientClientId` is a required input in this case. A master client app is allowed to send an offer to any viewer, whereas a viewer client app is only allowed to send an offer to a master client app. If a viewer client app attempts to send an offer to another viewer client app, the request will NOT be honored. If there is an outstanding offer for the same client which is not yet delivered, it is overwritten with the new offer. ## Request ``` { "action": "SDP_OFFER", "recipientClientId": "string", "messagePayload": "string", "correlationId": "string" } ``` + **action** - Type of the message that is being sent. + Type: ENUM + Valid values: `SDP_OFFER`, `SDP_ANSWER`, `ICE_CANDIDATE` + Length constraints: Minimum length of 1. Maximum length of 256. + Pattern: `[a-zA-Z0-9_.-]+` + Required: Yes + **recipientClientId** - The unique identifier for the recipient. + Type: String + Length constraints: Minimum length of 1. Maximum length of 256. + Pattern: `[a-zA-Z0-9_.-]+` + Required: Yes + **messagePayload** - The base-64-encoded message content. + Type: String + Length constraints: Minimum length of 1. Maximum length of 10K. + Required: Yes + **correlationId** - A unique identifier for the message. This is an optional parameter. + Type: String + Length constraints: Minimum length of 1. Maximum length of 256. + Pattern: `[a-zA-Z0-9_.-]+` + Required: No ## Response If the message is successfully received by the signaling backend, no response is returned. If the service encounters an error and if the `correlationId` is specified in the request, the error details are returned as a `STATUS_RESPONSE` message. For more information, see [Asynchronous message reception](async-message-reception-api.md). ## Errors + InvalidArgumentException A specified parameter exceeds its restrictions, is not supported, or cannot be used. For more information, see the returned message. HTTP Status Code: 400 + ClientLimitExceededException When the API is invoked at a rate that is too high. For more information, see [Amazon Kinesis Video Streams with WebRTC service quotas](kvswebrtc-limits.md) and [Error Retries and Exponential Backoff in AWS](https://docs.aws.amazon.com/general/latest/gr/api-retries.html). HTTP Status Code: 400 ## Limits/Throttling This API is throttled at an account level if the API is invoked at too high a rate. An error returned when throttled with `ClientLimitExceededException`. ## Idempotent This API is not idempotent. ## Retry behavior This is counted as a new API call. ## Concurrent calls Concurrent calls are allowed. An offer is sent once per each call. # SendSdpAnswer Sends the answer to the target recipient. The prerequisite is that the client must be already connected to the WebSocket endpoint obtained from the `GetSignalingChannelEndpoint` API. If the sender type is a viewer, then it sends the answer to a master. Also, it is not necessary to specify the `RecipientClientId` and any specified value for `RecipientClientId` is ignored. If the sender type is master, the answer is sent to the target viewer specified by the `RecipientClientId`. `RecipientClientId` is a required input in this case. A master client app is allowed to send an answer to any viewer, whereas a viewer client app is only allowed to send an answer to a master client app. If a viewer client app attempts to send an answer to another viewer client app, the request will NOT be honored. If there is an outstanding answer for the same client which is not yet delivered, it is overwritten with the new answer. ## Request ``` { "action": "SDP_ANSWER", "recipientClientId": "string", "messagePayload": "string", "correlationId": "string" } ``` + **action** - Type of the message that is being sent. + Type: ENUM + Valid values: `SDP_OFFER`, `SDP_ANSWER`, `ICE_CANDIDATE` + Length constraints: Minimum length of 1. Maximum length of 256. + Pattern: `[a-zA-Z0-9_.-]+` + Required: Yes + **recipientClientId** - The unique identifier for the recipient. + Type: String + Length constraints: Minimum length of 1. Maximum length of 256. + Pattern: `[a-zA-Z0-9_.-]+` + Required: Yes + **messagePayload** - The base-64-encoded message content. + Type: String + Length constraints: Minimum length of 1. Maximum length of 10K. + Required: Yes + **correlationId** - A unique identifier for the message. + Type: String + Length constraints: Minimum length of 1. Maximum length of 256. + Pattern: `[a-zA-Z0-9_.-]+` + Required: No ## Response No response is returned if the message is successfully received by the signaling backend. If the service encounters an error and if the `correlationId` is specified in the request, the error details are returned as a `STATUS_RESPONSE` message. For more information, see [Asynchronous message reception](async-message-reception-api.md). ## Errors + InvalidArgumentException A specified parameter exceeds its restrictions, is not supported, or cannot be used. For more information, see the returned message. HTTP Status Code: 400 + ClientLimitExceededException Returned when the API is invoked at a rate that is too high. For more information, see [Amazon Kinesis Video Streams with WebRTC service quotas](kvswebrtc-limits.md) and [Error Retries and Exponential Backoff in AWS](https://docs.aws.amazon.com/general/latest/gr/api-retries.html). HTTP Status Code: 400 ## Limits/Throttling This API is throttled at an account level if the API is invoked at too high a rate. An error is returned when throttled with `ClientLimitExceededException`. ## Idempotent This API is not idempotent. ## Retry behavior This is counted as a new API call. ## Concurrent calls Concurrent calls are allowed. An offer is sent once per each call. # SendIceCandidate Sends the ICE candidate to the target recipient. The prerequisite is that the client must be already connected to the WebSocket endpoint obtained from the `GetSignalingChannelEndpoint` API. If the sender type is a viewer, then it sends the ICE candidate to a master. Also, it is not necessary to specify the `RecipientClientId` and any specified value for `RecipientClientId` is ignored. If the sender type is master, the ICE candidate is sent to the target specified by the `RecipientClientId`. `RecipientClientId` is a required input in this case. A master client app is allowed to send an ICE candidate to any viewer, whereas a viewer client app is only allowed to send an ICE candidate to a master client app. If a viewer client app attempts to send an ICE candidate to another viewer client app, the request will NOT be honored. ## Request ``` { "action": "ICE_CANDIDATE", "recipientClientId": "string", "messagePayload": "string", "correlationId": "string" } ``` + **action** - Type of the message that is being sent. + Type: ENUM + Valid values: `SDP_OFFER`, `SDP_ANSWER`, `ICE_CANDIDATE` + Length constraints: Minimum length of 1. Maximum length of 256. + Pattern: `[a-zA-Z0-9_.-]+` + Required: Yes + **recipientClientId** - A unique identifier for the recipient. + Type: String + Length constraints: Minimum length of 1. Maximum length of 256. + Pattern: `[a-zA-Z0-9_.-]+` + Required: No + **messagePayload** - The base64-encoded message content. + Type: String + Length constraints: Minimum length of 1. Maximum length of 10K. + Required: Yes + **correlationId** - A unique identifier for the message. + Type: String + Length constraints: Minimum length of 1. Maximum length of 256. + Pattern: `[a-zA-Z0-9_.-]+` + Required: No ## Response No response is returned if the message is successfully received by the signaling backend. If the service encounters an error and if the `correlationId` is specified in the request, the error details are returned as a `STATUS_RESPONSE` message. For more information, see [Asynchronous message reception](async-message-reception-api.md). ## Errors + InvalidArgumentException A specified parameter exceeds its restrictions, is not supported, or cannot be used. For more information, see the returned message. HTTP Status Code: 400 + ClientLimitExceededException When the API is invoked at a rate that is too high. For more information, see [Amazon Kinesis Video Streams with WebRTC service quotas](kvswebrtc-limits.md) and [Error Retries and Exponential Backoff in AWS](https://docs.aws.amazon.com/general/latest/gr/api-retries.html). HTTP Status Code: 400 ## Limits/Throttling This API is throttled at an account level if the API is invoked at too high a rate. An error returned when throttled with `ClientLimitExceededException`. ## Idempotent This API is not idempotent. ## Retry behavior This is counted as a new API call. ## Concurrent calls Concurrent calls are allowed. An offer is sent once per each call. # Disconnect A client can close a connection at any time. WebSocket-compliant libraries support close functionality. When the connection is closed, service marks the client as offline for the specific signaling channel and does not try to deliver any messages. The same behavior also applies in the event of idle connection timeout. The service also sends disconnect indications to the client, for example, during deployments or server maintenance. The following are the defined indication messages: + **GO\$1AWAY**: This message is used to initiate the connection shutdown. It enables a client to gracefully process previous messages, disconnect, and reconnect to the signaling channel if needed. + **RECONNECT\$1ICE\$1SERVER**: This message is used to initiate the relay connection shutdown and enables a client to gracefully disconnect, obtain a new ICE server configuration, and reconnect to the relay servers if needed.