AWS Documentation » Amazon API Gateway » Developer Guide » Creating, Deploying, and Invoking a WebSocket API in Amazon API Gateway » Invoke a WebSocket API » Use @connections Commands in Your Backend Service

Use @connections Commands in Your Backend Service

Your backend service can use the following WebSocket connection HTTP requests to send a callback message to a connected client, get connection information, or disconnect the client.

Important

These requests use IAM authorization, so you must sign them with Signature Version 4 (SigV4). To do this, you can use the API Gateway Management API. For more information, see ApiGatewayManagementApi.

In the following command, you'll need to replace {api-id} with the actual API ID, which is displayed the API Gateway console or returned by the AWS CLI create-api command. In addition, if your API is in a region other than us-east-1, you'll need to substitute the correct region.

To send a callback message to the client, use:

POST https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}

You can test this request by using Postman or by calling awscurl as in the following example:

awscurl --service execute-api -X POST -d "hello world" https://{prefix}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}

You'll need to URL-encode the command as in the following example:

awscurl --service execute-api -X POST -d "hello world" https://aabbccddee.execute-api.us-east-1.amazonaws.com/prod/%40connections/R0oXAdfD0kwCH6w%3D

To get the latest connection status of the client, use:

GET https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}

To disconnect the client, use:

DELETE https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}

Note

Postman doesn't encode the @connections URL, so you'll need to replace = and @ characters in the encoded URL.

You can dynamically build a callback URL by using the $context variables in your integration. For example, if you use Lambda proxy integration with a Node.js Lambda function, you can build the URL as follows:

exports.handler = function(event, context, callback) {
var domain = event.requestContext.domain;
var stage = event.requestContext.stage;
var connectionId = event.requestContext.connectionId;
var callbackUrl = util.format(util.format('https://%s/%s/@connections/%s', domain, stage, connectionId);
// Do a SigV4 and then make the call
}