From 3eafc6ccba684b2efb9afd379b7d0c535b2d5869 Mon Sep 17 00:00:00 2001 From: Styler Date: Wed, 20 Sep 2023 18:55:42 +0200 Subject: [PATCH 1/4] Astro docs --- docs/websockets/index.md | 53 ++++++++++++++++++++++- docs/websockets/topics/chatbot-timeout.md | 18 ++++++++ 2 files changed, 70 insertions(+), 1 deletion(-) create mode 100644 docs/websockets/topics/chatbot-timeout.md diff --git a/docs/websockets/index.md b/docs/websockets/index.md index 3c9394c..e3c26c0 100644 --- a/docs/websockets/index.md +++ b/docs/websockets/index.md @@ -1,3 +1,54 @@ # Websockets -To be continued... +## Astro Websocket Gateway + +Astro is our dedicated websocket gateway. It provides a publish-subscribe (pubsub) pattern for real-time data updates. + +Clients establish a WebSocket connection to: `wss://astro.streamelements.com` + +### Request from client to server + +| Parameter | Type | Description | +| --- | --- | --- | +| `type` | `string` | The type of request. Valid options are `SUBSCRIBE` AND `UNSUBSCRIBE` | +| `nonce` | `string` | A unique identifier for the request. This can be handy to identity the response (Optional) | +| `data.topic` | `string` | The topic to subscribe to. | +| `data.token` | `string` | The token to authenticate the request. | +| `data.token_type` | `string` | The type of token. Valid options are `apikey` and `jwt` | + +```json +{ + "type": "SUBSCRIBE", + "nonce": "86ccb2b3-eb8d-4b3c-902d-509c3f5ca88c", + "data": { + "topic": "channel.follow", + "token": "test_token", + "token_type": "jwt" + } +} +``` + +### Response from server to client + +| Parameter | Type | Description | +| --- | --- | --- | +| `id` | `string` | The unique identifier of the response. | +| `type` | `string` | The type of response. Valid options are `RESPONSE` | +| `nonce` | `string` | The nonce of the request. | +| `error` | `string` | The error code. | + +```json +{ + "id":"04c25ba8-9162-4968-968b-9f7f5d3bc361", + "ts":"2023-09-20T16:43:21Z", + "type":"RESPONSE", + "nonce":"86ccb2b3-eb8d-4b3c-902d-509c3f5ca88c", + "data":"successfully subscribed to topic" +} +``` + +### Topics + +| Topic | Required Scope | You are notified when | +| --- | --- | --- | +| `chatbot.timeout` | `bot:read` | When the chatbot times someone out | diff --git a/docs/websockets/topics/chatbot-timeout.md b/docs/websockets/topics/chatbot-timeout.md new file mode 100644 index 0000000..fd71ea6 --- /dev/null +++ b/docs/websockets/topics/chatbot-timeout.md @@ -0,0 +1,18 @@ +# chatbot.timeout + +## Description + +When the chatbot times someone out. + +## Status + +- `In development` + +#### Payload + +```json +{ + "user": "sabrinabee26", + "duration": 300 +} +``` From 190c381aa62fa42ca80f82c8563029131e195382 Mon Sep 17 00:00:00 2001 From: Styler Date: Wed, 20 Sep 2023 18:59:47 +0200 Subject: [PATCH 2/4] Update JSON formatting in websockets/index.md --- docs/websockets/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/websockets/index.md b/docs/websockets/index.md index e3c26c0..9148ef1 100644 --- a/docs/websockets/index.md +++ b/docs/websockets/index.md @@ -39,11 +39,11 @@ Clients establish a WebSocket connection to: `wss://astro.streamelements.com` ```json { - "id":"04c25ba8-9162-4968-968b-9f7f5d3bc361", - "ts":"2023-09-20T16:43:21Z", - "type":"RESPONSE", - "nonce":"86ccb2b3-eb8d-4b3c-902d-509c3f5ca88c", - "data":"successfully subscribed to topic" + "id": "04c25ba8-9162-4968-968b-9f7f5d3bc361", + "ts": "2023-09-20T16:43:21Z", + "type": "RESPONSE", + "nonce": "86ccb2b3-eb8d-4b3c-902d-509c3f5ca88c", + "data": "successfully subscribed to topic" } ``` From 2bf37e10cc394f562b94cf6b2cf6310ec44f8838 Mon Sep 17 00:00:00 2001 From: Styler Date: Sat, 23 Sep 2023 14:01:55 +0200 Subject: [PATCH 3/4] Update WebSocket documentation with new topic categories --- docs/websockets/index.md | 38 ++++++++++++++++++++++---- docs/websockets/topics/_category_.json | 3 ++ 2 files changed, 35 insertions(+), 6 deletions(-) create mode 100644 docs/websockets/topics/_category_.json diff --git a/docs/websockets/index.md b/docs/websockets/index.md index 9148ef1..c7d5f51 100644 --- a/docs/websockets/index.md +++ b/docs/websockets/index.md @@ -10,7 +10,7 @@ Clients establish a WebSocket connection to: `wss://astro.streamelements.com` | Parameter | Type | Description | | --- | --- | --- | -| `type` | `string` | The type of request. Valid options are `SUBSCRIBE` AND `UNSUBSCRIBE` | +| `type` | `string` | The type of request. Valid options are `subscribe` AND `unsubscribe` | | `nonce` | `string` | A unique identifier for the request. This can be handy to identity the response (Optional) | | `data.topic` | `string` | The topic to subscribe to. | | `data.token` | `string` | The token to authenticate the request. | @@ -18,7 +18,7 @@ Clients establish a WebSocket connection to: `wss://astro.streamelements.com` ```json { - "type": "SUBSCRIBE", + "type": "subscribe", "nonce": "86ccb2b3-eb8d-4b3c-902d-509c3f5ca88c", "data": { "topic": "channel.follow", @@ -36,19 +36,45 @@ Clients establish a WebSocket connection to: `wss://astro.streamelements.com` | `type` | `string` | The type of response. Valid options are `RESPONSE` | | `nonce` | `string` | The nonce of the request. | | `error` | `string` | The error code. | +| `data` | `object` | The data of the response. | ```json { - "id": "04c25ba8-9162-4968-968b-9f7f5d3bc361", + "id": "01HB0YE5TR26EH71DVPJ68MA82", "ts": "2023-09-20T16:43:21Z", - "type": "RESPONSE", + "type": "response", "nonce": "86ccb2b3-eb8d-4b3c-902d-509c3f5ca88c", "data": "successfully subscribed to topic" } ``` +### Errors + +| Error | Description | +| --- | --- | +| `err_internal_error` | An internal error occurred. | +| `err_bad_request` | The request was malformed or invalid. | +| `err_unauthorized` | The request lacked valid authentication credentials. | +| `rate_limit_exceeded` | The rate limit for the API has been exceeded. | +| `invalid_message` | The message was invalid or could not be processed. | + +```json +{ + "id": "01HB0YE5Y88FXMXXCN4ME7M8A1", + "ts": "2023-09-20T16:43:21Z", + "type": "response", + "nonce": "86ccb2b3-eb8d-4b3c-902d-509c3f5ca88c", + "error": "err_unauthorized", + "data": { + "message": "invalid token" + } +} +``` + ### Topics -| Topic | Required Scope | You are notified when | +This will be released in the near future. + + diff --git a/docs/websockets/topics/_category_.json b/docs/websockets/topics/_category_.json new file mode 100644 index 0000000..17778bd --- /dev/null +++ b/docs/websockets/topics/_category_.json @@ -0,0 +1,3 @@ +{ + "label": "Topics" +} From 5b3f1cd06ef78cc5ba920450da6d34c2493a20ef Mon Sep 17 00:00:00 2001 From: Styler Date: Sat, 23 Sep 2023 14:10:14 +0200 Subject: [PATCH 4/4] Refactor websocket documentation with request and response examples --- docs/websockets/index.md | 59 ++++++++++++++++++++++++++++++---------- 1 file changed, 44 insertions(+), 15 deletions(-) diff --git a/docs/websockets/index.md b/docs/websockets/index.md index c7d5f51..edd1aa4 100644 --- a/docs/websockets/index.md +++ b/docs/websockets/index.md @@ -2,19 +2,23 @@ ## Astro Websocket Gateway -Astro is our dedicated websocket gateway. It provides a publish-subscribe (pubsub) pattern for real-time data updates. +Astro is StreamElements' dedicated websocket gateway. It employs a publish-subscribe (pubsub) pattern to facilitate real-time data updates. -Clients establish a WebSocket connection to: `wss://astro.streamelements.com` +To establish a WebSocket connection, clients should connect to: `wss://astro.streamelements.com` -### Request from client to server +### Client-to-Server Request + +The following parameters are used in a client-to-server request: | Parameter | Type | Description | | --- | --- | --- | -| `type` | `string` | The type of request. Valid options are `subscribe` AND `unsubscribe` | -| `nonce` | `string` | A unique identifier for the request. This can be handy to identity the response (Optional) | -| `data.topic` | `string` | The topic to subscribe to. | -| `data.token` | `string` | The token to authenticate the request. | -| `data.token_type` | `string` | The type of token. Valid options are `apikey` and `jwt` | +| `type` | `string` | Defines the type of request. Valid options are `subscribe` and `unsubscribe`. | +| `nonce` | `string` | A unique identifier for the request. Useful for identifying the corresponding response (Optional). | +| `data.topic` | `string` | The topic to which the client wishes to subscribe. | +| `data.token` | `string` | The token used to authenticate the request. | +| `data.token_type` | `string` | Specifies the type of token. Valid options are `apikey` and `jwt`. | + +Here is an example of a client-to-server request: ```json { @@ -28,15 +32,19 @@ Clients establish a WebSocket connection to: `wss://astro.streamelements.com` } ``` -### Response from server to client +### Server-to-Client Response + +The following parameters are used in a server-to-client response: | Parameter | Type | Description | | --- | --- | --- | | `id` | `string` | The unique identifier of the response. | -| `type` | `string` | The type of response. Valid options are `RESPONSE` | -| `nonce` | `string` | The nonce of the request. | -| `error` | `string` | The error code. | -| `data` | `object` | The data of the response. | +| `type` | `string` | Defines the type of response. The only valid option is `RESPONSE`. | +| `nonce` | `string` | The nonce of the original request. | +| `error` | `string` | The error code, if any. | +| `data` | `object` | The data contained in the response. | + +Here is an example of a server-to-client response: ```json { @@ -48,7 +56,25 @@ Clients establish a WebSocket connection to: `wss://astro.streamelements.com` } ``` -### Errors +### Server Notifications + +Clients can receive notifications from the server. Here is an example: + +```json +{ + "id": "01HB0YF39XF16HMHCPDYZYJYFK", + "ts": "2023-09-23T12:06:25Z", + "type": "message", + "topic": "astro", + "data": { + "message":"Hello world!" + } +} +``` + +### Error Codes + +The following error codes may be returned in a server-to-client response: | Error | Description | | --- | --- | @@ -58,6 +84,8 @@ Clients establish a WebSocket connection to: `wss://astro.streamelements.com` | `rate_limit_exceeded` | The rate limit for the API has been exceeded. | | `invalid_message` | The message was invalid or could not be processed. | +Here is an example of a server-to-client response containing an error: + ```json { "id": "01HB0YE5Y88FXMXXCN4ME7M8A1", @@ -73,8 +101,9 @@ Clients establish a WebSocket connection to: `wss://astro.streamelements.com` ### Topics -This will be released in the near future. +Information on available topics will be released in the near future. +