# 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.