> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.cacolombia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Real-Time Events via WebSocket Subscriptions

> CA Colombia broadcasts real-time events over WebSocket topics. Learn the event payload structure for user and character events.

CA Colombia delivers real-time updates over WebSocket subscriptions rather than traditional HTTP webhooks. Once connected, your client subscribes to one or more named topics and receives event messages as users and characters are created, updated, or deleted. This page documents the payload formats for every event topic. For instructions on establishing a connection and authenticating, see the [WebSocket guide](/guides/websocket).

***

## Event Message Structure

Every message delivered over the WebSocket connection shares the same envelope structure. The `channel` field identifies which topic the event belongs to, `type` is always `"event"` for data events, and `data` contains the topic-specific payload.

```json theme={null}
{
  "channel": "characters:update",
  "type": "event",
  "data": { ... }
}
```

| Field     | Type     | Description                                                    |
| --------- | -------- | -------------------------------------------------------------- |
| `channel` | `string` | The subscription topic that produced this event.               |
| `type`    | `string` | Message type. Data events always use `"event"`.                |
| `data`    | `object` | The event payload. Shape varies by topic — see sections below. |

<Note>
  Your client should check the `type` field of every incoming message and handle only `"event"` messages for topic data. Messages with other `type` values, or error objects without a `type` field, should be handled or silently ignored as appropriate.
</Note>

***

## User Events

User events notify you when an account is created, its profile is modified, or it is removed from the platform. Subscribe to one or more of the following topics:

| Topic          | When it fires                                        |
| -------------- | ---------------------------------------------------- |
| `users:create` | A new user account has been created.                 |
| `users:update` | An existing user's profile or settings have changed. |
| `users:delete` | A user account has been deleted.                     |

The `data` payload for all user events contains the updated state of the user object at the time the event was emitted, including the user's ID, permissions, linked providers, and active character reference.

**Example — `users:update` event:**

```json theme={null}
{
  "channel": "users:update",
  "type": "event",
  "data": {
    "userId": "123456789012345678",
    "permissions": 1024,
    "maxCharacters": 3,
    "activeCharacter": "987654321098765432",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-06-20T14:45:00.000Z"
  }
}
```

***

## Character Events

Character events notify you when a character is created, modified, or removed. Subscribe to one or more of the following topics:

| Topic               | When it fires                                      |
| ------------------- | -------------------------------------------------- |
| `characters:create` | A new character has been created.                  |
| `characters:update` | A character's data or approval status has changed. |
| `characters:delete` | A character has been deleted.                      |

The `data` payload for character events contains the full character object. The fields included are:

| Field          | Type             | Description                                                              |
| -------------- | ---------------- | ------------------------------------------------------------------------ |
| `userId`       | `string`         | Snowflake ID of the user who owns this character.                        |
| `characterId`  | `string`         | Unique Snowflake ID for this character.                                  |
| `firstNames`   | `string`         | The character's first name(s).                                           |
| `lastNames`    | `string`         | The character's last name(s).                                            |
| `age`          | `number`         | The character's age.                                                     |
| `height`       | `number`         | The character's height.                                                  |
| `gender`       | `string`         | `"Masculino"` or `"Femenino"`.                                           |
| `bloodType`    | `string`         | One of `O+`, `O-`, `A+`, `A-`, `B+`, `B-`, `AB+`, `AB-`.                 |
| `nationality`  | `object`         | Object containing `nombre`, `abrev`, and `lugar` fields.                 |
| `dob`          | `string`         | Date of birth in `DD/MM/YYYY` format.                                    |
| `avatarHash`   | `string \| null` | Hash of the character's avatar image.                                    |
| `idCardHash`   | `string \| null` | Hash of the generated ID card image.                                     |
| `fullBodyHash` | `string \| null` | Hash of the full-body image.                                             |
| `avatar3dHash` | `string \| null` | Hash of the 3D avatar asset.                                             |
| `idStatus`     | `string`         | Approval state: `"draft"`, `"submitted"`, `"approved"`, or `"rejected"`. |
| `wallet`       | `object \| null` | The character's wallet object if one exists, otherwise `null`.           |
| `createdAt`    | `string`         | ISO 8601 timestamp of when the character was created.                    |
| `updatedAt`    | `string`         | ISO 8601 timestamp of the last update.                                   |

**Example — `characters:create` event:**

```json theme={null}
{
  "channel": "characters:create",
  "type": "event",
  "data": {
    "userId": "123456789012345678",
    "characterId": "234567890123456789",
    "firstNames": "Carlos",
    "lastNames": "Rodríguez",
    "age": 28,
    "height": 175,
    "gender": "Masculino",
    "bloodType": "O+",
    "nationality": {
      "nombre": "Colombiana",
      "abrev": "COL",
      "lugar": "Colombia"
    },
    "dob": "15/03/1996",
    "avatarHash": null,
    "idCardHash": null,
    "fullBodyHash": null,
    "avatar3dHash": null,
    "idStatus": "draft",
    "wallet": null,
    "createdAt": "2024-06-20T14:45:00.000Z",
    "updatedAt": "2024-06-20T14:45:00.000Z"
  }
}
```

<Tip>
  Subscribe to `characters:update` to detect when a character's `idStatus` changes from `"submitted"` to `"approved"` or `"rejected"`. This is the recommended way to react to staff approval decisions in real time without polling the REST API.
</Tip>

***

## Subscribing to Topics

<Note>
  Subscribe only to the topics your application actually needs. Every active subscription adds to the volume of messages your client must process. Receiving unnecessary events — especially on high-traffic topics like `characters:update` — can increase latency and memory usage in your integration.
</Note>

See the [WebSocket guide](/guides/websocket) for the exact subscribe message format and how to manage your active subscriptions over the lifetime of a connection.