> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/interface/cuxial-chat/developers.md).

# Exports & events

Public API of Cuxial Chat: exports and events to send messages from other resources.

Send messages to the chat, open it or read its channels from your own resources. Resources written for the standard chat need no changes.

## Server exports

### message

Sends a message to one player, several players or everyone.

```lua
exports.cuxial_chat:message(target, data)
```

| Parameter       | Type                       | Description                                                                                            |
| --------------- | -------------------------- | ------------------------------------------------------------------------------------------------------ |
| `target`        | number \| number\[] \| nil | A server id, a list of ids, or `-1` / `nil` for everyone.                                              |
| `data.text`     | string                     | Message text. Required. Cut at 600 characters.                                                         |
| `data.channel`  | string                     | Channel `id` from `data/channels.lua`. Unknown or missing = `system`.                                  |
| `data.author`   | string                     | Name shown as author.                                                                                  |
| `data.authorId` | number                     | Server id of the author. In a channel with bubbles, the message also appears above that player's head. |
| `data.to`       | string                     | Name of the recipient, shown next to the author.                                                       |
| `data.tags`     | table                      | List of tags: `{ { label = 'Text', color = '#rrggbb' } }`.                                             |
| `data.image`    | string                     | URL of an image shown with the message. It is not checked against `images.hosts`.                      |
| `data.system`   | boolean                    | Marks the message as a system message. Defaults to `true` when there is no `author`.                   |

**Returns:** `boolean`. `true` when the message was sent; `false` when the data is invalid or no valid id was given.

```lua
exports.cuxial_chat:message(source, {
    channel = 'sancion',
    text = 'You have been warned: *respect the safe zone*.',
    tags = { { label = 'Warning', color = '#f59e0b' } },
})
```

### system

Shortcut for a system message.

```lua
exports.cuxial_chat:system(target, text)
```

| Parameter | Type                       | Description                                               |
| --------- | -------------------------- | --------------------------------------------------------- |
| `target`  | number \| number\[] \| nil | A server id, a list of ids, or `-1` / `nil` for everyone. |
| `text`    | string                     | Message text.                                             |

**Returns:** `boolean`.

```lua
exports.cuxial_chat:system(-1, 'Server restart in 10 minutes.')
```

### getChannels

Returns the channel list with the labels already translated.

```lua
local channels = exports.cuxial_chat:getChannels()
```

**Returns:** `table[]`. Each entry has the fields of `data/channels.lua` (`id`, `label`, `voice`, `color`, `tab`, `order`, `icon`, `command`...).

```lua
for _, channel in ipairs(exports.cuxial_chat:getChannels()) do
    print(channel.id, channel.label, channel.color)
end
```

## Client exports

### addMessage

Shows a system message to the local player.

```lua
exports.cuxial_chat:addMessage(text, channel)
```

| Parameter | Type   | Description                                  |
| --------- | ------ | -------------------------------------------- |
| `text`    | string | Message text.                                |
| `channel` | string | Channel `id`. Optional; `system` by default. |

```lua
exports.cuxial_chat:addMessage('Vehicle stored.')
```

### open

Opens the chat, optionally on a given channel. Does nothing if the chat is already open.

```lua
exports.cuxial_chat:open(channel)
```

| Parameter | Type   | Description             |
| --------- | ------ | ----------------------- |
| `channel` | string | Channel `id`. Optional. |

```lua
exports.cuxial_chat:open('ooc')
```

### close

Closes the chat.

```lua
exports.cuxial_chat:close()
```

### isOpen

Tells whether the chat is open.

```lua
local open = exports.cuxial_chat:isOpen()
```

**Returns:** `boolean`.

```lua
if exports.cuxial_chat:isOpen() then return end
```

### refreshMask

Re-checks whether the player is wearing a mask. The chat already checks each time it opens. Call this export from your clothing resource after changing the mask so the anonymous name updates at once.

```lua
exports.cuxial_chat:refreshMask()
```

{% hint style="info" %}
The result is published in the player state bag `chatMasked` (`boolean`), which other resources can read. It is only published with `anonymous.enabled = true`.
{% endhint %}

## Standard chat compatibility

Cuxial Chat provides the `chat` resource, so code written for the default chat keeps working. These messages are shown in the `system` channel.

### exports.chat:addMessage

{% tabs %}
{% tab title="Client" %}

```lua
exports.chat:addMessage({
    color = { 255, 200, 0 },
    args = { 'Garage', 'Vehicle stored.' },
})
```

{% endtab %}

{% tab title="Server" %}

```lua
exports.chat:addMessage(source, {
    args = { 'Garage', 'Vehicle stored.' },
})
```

{% endtab %}
{% endtabs %}

Accepted forms of the message:

| Form                          | Result                                                                              |
| ----------------------------- | ----------------------------------------------------------------------------------- |
| A plain string                | Shown as the text.                                                                  |
| `args = { 'Author', 'Text' }` | Author and text.                                                                    |
| `args = { 'Text' }`           | Text only.                                                                          |
| `template`                    | Used only when `args` carries no text. Shown as plain text, with HTML tags removed. |
| `color = { r, g, b }`         | Adds a coloured tag to the message.                                                 |

### Client events

| Event                   | Parameters              | What it does                                                       |
| ----------------------- | ----------------------- | ------------------------------------------------------------------ |
| `chat:addMessage`       | `message`               | Adds a message. Same forms as the export.                          |
| `chatMessage`           | `author, color, text`   | Adds a message in the legacy format.                               |
| `chat:clear`            | none                    | Clears the chat.                                                   |
| `chat:show`             | none                    | Opens the chat.                                                    |
| `chat:addSuggestion`    | `command, help, params` | Adds a command to the autocomplete list.                           |
| `chat:addSuggestions`   | `list`                  | Adds several commands. Each entry has `name`, `help` and `params`. |
| `chat:removeSuggestion` | `command`               | Removes a command from the list.                                   |

```lua
TriggerClientEvent('chat:addSuggestion', -1, '/repair', 'Repair the vehicle', {
    { name = 'id', help = 'Player id' },
})
```

### Server event: chatMessage

Triggered on the server before a message written without a command is delivered. Cancel it to block the message.

| Parameter | Type   | Description              |
| --------- | ------ | ------------------------ |
| `source`  | number | Server id of the author. |
| `name`    | string | Character name.          |
| `text`    | string | Message text.            |

```lua
AddEventHandler('chatMessage', function(source, name, text)
    if text:find('forbidden') then
        CancelEvent()
    end
end)
```

{% hint style="info" %}
Messages sent with a command (`/me`, `/do`, `/pm`...) do not trigger this event.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cuxial.com/scripts/interface/cuxial-chat/developers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.