# WebSockets

WebSocket support makes it possible to open a two-way interactive communication session between a client and ProcessMaker IDP. With this API, you can send messages to a server and receive event-driven responses without having to poll the server for a reply. WebSocket support requires an integration rule with Queue Name `WEB_SOCKET_EVENTS` and an Entity Reference to a certain entity to process events.

First, open the connection: `wss://processmaker-idp.com/api/websocket/events`. Then you can subscribe or unsubscribe to events of a particular entity instance defined by an ID. Notifications are received after update operations are made on the subscribed file. Each request requires an Authorization header with a Bearer token from Keycloak. Also, a second header `Origin` is required with the ProcessMaker IDP base URL as the value.

## **Subscribe**

Example:

```json
{
  "action": "subscribe",
  "entity": "file",
  "id": "fc795c7a-451f-474b-9a56-ac5ca6d140dd"
}
```

## **Notifications**

The client will be notified at every value change of an attribute of that particular entity instance:

```json
{
  "entity": "FILE",
  "id": "37c3b618-9ad8-49ef-b0af-c329dd0b3ebb",
  "name": "example.pdf",
  "action": "UPDATE",
  "attributes": ["fullText", "language", "annotatable"]
}
```

If you would like to get notified of new or updated files in a folder, the Event Type of the integration rule related to the child entity (in this case FILE) should be set to both `CREATE` and `UPDATE`. You will need to subscribe to the folder.

A new file:

```json
{
  "entity": "FOLDER",
  "id": "8fe828a8-b35e-434c-abcd-a95756c8a1f5",
  "action": "CREATE_FILE",
  "child": {
    "name": "new_file.pdf",
    "entity": "FILE",
    "id": "5a021d0f-b864-413a-91b1-7e027de959b1"
  }
}
```

An updated file:

```json
{
  "entity": "FOLDER",
  "id": "8fe828a8-b35e-434c-abcd-a95756c8a1f5",
  "action": "UPDATE_FILE",
  "child": {
    "name": "example.pdf",
    "entity": "FILE",
    "id": "37c3b618-9ad8-49ef-b0af-c329dd0b3ebb"
  },
  "attributes": ["fullText", "language", "annotatable"]
}
```

## **Unsubscribe**

Example:

```json
{
  "action": "unsubscribe",
  "entity": "FILE",
  "id": "37c3b618-9ad8-49ef-b0af-c329dd0b3ebb"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://processmaker.gitbook.io/idp/idp-developer/websockets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.