WebSockets Service

Access info
Endpoint https://websockets-manager-api.socrate.io/graphql
Required access keys Tenant-level service access key
Pricing Please contact us for details at contact@bitsoftware.ro
Notes To call the service, the access key must be provided in the x-api-key header of the HTTP request. If you are using the GraphQL console, you can view the service’s documentation and schema only after entering an access key. Make sure that the scope of the key allows access to the queries and mutations that you require. For example, to grant the key access to all queries and mutations, the keys’s scope must be set to websockets-manager-api:query:* websockets-manager-api:mutation:*.

Usage

The WebSockets Service enables applications to push notifications to clients that implement the WebSocket protocol, such as browsers. The WebSocket protocol is defined in RFC 6455 and it provides bi-directional communication between client and server over HTTP(S) through a single open connection. It is typically used for exchanging live messages between a server and a client (like in a chat application), or to notify browsers instantly of server changes. SBS specifically targets only the second scenario (that is, pushing notifications from the WebSocket server to connected WebSocket clients).

You may want to implement the WebSockets service in order to instantly inform your application’s users of various events, for example:

  • send a notification to the user’s browser when a time-consuming process has completed, such as computations of data-intensive tax declarations.
  • send a notification to the user’s browser when your application has software updates.

How it works

Implementing the WebSocket service in your application involves the following steps:

  1. Register each user to which you would like to push notifications as a recipient. Registering a recipient consists of running the registerRecipient mutation where you provide as input a string that uniquely identifies the recipient (typically, the ID of the user in your application). A simple recipient like the one from the code listing below takes as input the recipient name only. For more advanced customization and increased security, you may provide additional input arguments that are further described under registerRecipient.

    mutation registerRecipient($input:RegisterRecipientInput!) {
      registerRecipient(input:$input) {
        token
        connectionUri
      }
    }

    {
      "input": {
        "recipient": "d9f3c17a-c6de-4e5e-b42b-98fbfb46a108"
      }
    }

    In the response, you get a URI at which the server is accepting WebSocket connections. The URI has the format wss://websockets.socrate.io/?token=SOME_TOKEN, where SOME_TOKEN is generated by SBS on each call.

  2. From the user’s browser, open a connection to the Websocket server URI obtained in the previous step. A minimal WebSocket client might look as follows (just make sure to replace SOME_TOKEN with your actual token):

    <!DOCTYPE html>
    <html lang="en">
    <head>
    <title>WebSocket Client Example</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script>
        var ws = new WebSocket("wss://websockets.socrate.io/?token=SOME_TOKEN");
    
        ws.onopen = () => {
          document.getElementById("status").innerText = "WebSocket connection open.";
        }
    
        ws.onclose = () => {
          document.getElementById("status").innerText = "WebSocket connection closed.";
        }
    </script>
    </head>
    <body>
        <div id="status"></div>
    </body>
    </html>

    You can view the state of the WebSocket connection from the browser’s developer tools. In Chrome, press Ctrl+Shift+I to open Developer Tools. Click the Network tab, and then click WS. After refreshing page, the WebSocket connection details appear in the list.

    WebSocket in browser’s Developer Tools

  3. Send the actual notification to the recipients registered previously. To do this, run the pushMessage mutation, which takes as input an array of target recipient names. If needed, you can also send a message globally to all connected recipients regardless of their name, by running the pushGlobalMessage mutation. In either case, all targeted recipients that are currently connected to the Websocket URI will instantly receive the notification message.

    mutation pushMessage($input:MessageInput!) {
      pushMessage(input:$input) {
        item {
          id
          message
          status
          expiresAt
          createdAt
          deliveredAt
          cancelledAt
          globalMessageId
        }
        error{
          message
        }
      }
    }
    

    {
      "input": {
        "recipients": ["d9f3c17a-c6de-4e5e-b42b-98fbfb46a108"],
        "message": "The quick brown fox jumps over the lazy dog"
      }
    }

    The Messages tab of the browser should now display the received message, accordingly:

    WebSocket message

Queries

globalMessages

Lists all messages pushed globally to all recipients.

Arguments

Argument Type Description
filter GlobalMessagesFilter Optional. Provides options for filtering records, as a GlobalMessagesFilter type.
nextToken String Optional argument used to fetch the next set of query results. This value can be obtained from the nextToken attribute of the GlobalMessagesQueryResult type.
GlobalMessagesFilter input

You can specify zero or more filtering options. When multiple filtering options are specified, they are joined by a logical AND operator.

Attribute Type Description
createdAt DateTimeFilter Optional. If this parameter is specified, only global messages pushed within this date range will be listed. The range itself is defined as DateTimeFilter type.
expiresAt DateTimeFilter Optional. If this parameter is specified, only global messages with expiry date within this date range will be listed. The range itself is defined as DateTimeFilter type.
topic String Optional. Lists only global messages that were sent with this specific topic.
DateTimeFilter input
Attribute Type Description
from String Specifies the start date of the date range.
to String Specifies the end date of the date range.

Result

GlobalMessagesQueryResult type
Attribute Type Description
items [GlobalMessage] The list of global messages that match the filter criteria. See the GlobalMessage type.
nextToken String If null, then the query has reached the end of the list of results that match the query criteria. If not null, then use this value in the nextToken input argument, with the same filter, to fetch the next set of results.
GlobalMessage type
Attribute Type Description
id ID The unique identifier of the message.
message String The text of the message.
topic String The topic with which the message was sent.
expiresAt DateTime The date and time when the message is due to expire.
createdAt DateTime The date and time when the message was created.

messages

Lists messages pushed to specific recipients (that is, not globally).

Arguments

Argument Type Description
filter MessagesFilter Optional. Provides options for filtering records, as a MessagesFilter type.
nextToken String Optional argument used to fetch the next set of query results. This value can be obtained from the nextToken attribute of the MessagesQueryResult type.
MessagesFilter input

You can specify zero or more filtering options. When multiple filtering options are specified, they are joined by a logical AND operator.

Attribute Type Description
recipient String Optional. Lists only messages sent to this recipient.
globalMessageId ID Optional. Lists only messages where the globalMessageId attribute matches this value.
createdAt DateTimeFilter Optional. If this parameter is specified, only global messages pushed within this date range will be listed. The range itself is defined as DateTimeFilter type.
expiresAt DateTimeFilter Optional. If this parameter is specified, only global messages with expiry date within this date range will be listed. The range itself is defined as DateTimeFilter type.
topic String Optional. Lists only messages that were sent with this specific topic.

Result

MessagesQueryResult type
Attribute Type Description
items [GlobalMessage] The list of global messages that match the filter criteria. See the GlobalMessage type.
nextToken String If null, then the query has reached the end of the list of results that match the query criteria. If not null, then use this value in the nextToken input argument, with the same filter, to fetch the next set of results.
Message type
Attribute Type Description
id ID The unique identifier of the message.
recipient String The name of the recipient to which the message was pushed.
message String The text of the message.
topic String The topic with which the message was sent.
status MessageStatus The message delivery status. Valid values: PENDING, DELIVERED, CANCELLED.
expiresAt DateTime The date and time when the message is due to expire.
createdAt DateTime The date and time when the message was created.
deliveredAt DateTime The date and time when the message was delivered.
cancelledAt DateTime The date and time when the message delivery was cancelled.
globalMessageId ID The global identifier of the message.

version

Returns the API version.

Mutations

pushGlobalMessage

Sends a message globally to all registered recipients that are currently connected to the WebSocket server.

Arguments

Attribute Type Description
input GlobalMessageInput! Mandatory. Provides input to the mutation, as a GlobalMessageInput type.
GlobalMessageInput type
Attribute Type Description
message String Mandatory. The text of the message to be pushed.
topic String Optional. Assigns a topic to the message. If specified, the message will be pushed only to recipients labelled with this topic at creation time.
expiresAt DateTime Optional. Assigns an expiry date and time to the message. If the recipient opens the WebSocket connection after the message has expired, they will no longer receive the message. Note that the supplied date and time must be in the GMT timezone. Example value: 2023-07-18T15:00:00

Result

See the GlobalMessage type.

pushMessage

Sends a message to designated recipients that are currently connected to the WebSocket server.

Arguments

Attribute Type Description
input MessageInput! Mandatory. Provides input to the mutation, as a MessageInput type.
MessageInput type
Attribute Type Description
recipients [String!]! Mandatory. Specifies the recipients of the message, as an array of String. At least one recipient must be provided.
message String Mandatory. The text of the message to be pushed.
topic String Optional. Assigns a topic to the message. If specified, the message will be pushed only to recipients labelled with this topic at creation time.
expiresAt DateTime Optional. Assigns an expiry date and time to the message. If the recipient opens the WebSocket connection after the message has expired, they will no longer receive the message. Note that the supplied date and time must be in the GMT timezone. Example value: 2023-07-18T15:00:00

Result

See the Message type.

registerRecipient

Registers a recipient to which your application can push WebSocket messages. This mutation returns the Websocket server URI to which the recipient can connect in order to receive notifications from the WebSocket server.

Arguments

Attribute Type Description
input RegisterRecipientInput! Mandatory. Provides input to the mutation, as a RegisterRecipientInput type.
RegisterRecipientInput type
Attribute Type Description
recipient String! Mandatory. The name of the recipient. This is typically the identifier of the user in your application, or any other string with which you would like to uniquely identify the recipient. Note that SBS does not store the recipients that you register as a result of this mutation. It is up to your application to keep track of all registered recipients.
sourceIp String Optional, used to provide additional security. If provided, the recipient will be able to connect to its designated WebSocket server URI only if the request originates from this IP address.
origin String Optional, used to provide additional security. If provided, the recipient will be able to connect to its designated WebSocket server URI only if the request originates from this domain. The domain can be in the form http://example.org or https://example.org. This is the same value that appears in the origin HTTP header.
topic String Optional. Assigns a topic to the recipient. This provides the ability to channel messages only to recipients that have been labelled with a specific topic.

Result

RegisterRecipientResponse type
Attribute Type Description
token Token A token uniquely identifies the recipient and is part of the connection URI to which the WebSocket client will connect.
connectionUri String The URI at which the recipient (WebSocket client) can establish a connection to the WebSocket server.

Read more

VAT Validator Service Miscellaneous