> For the complete documentation index, see [llms.txt](https://ccfivem.gitbook.io/ccfivem-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ccfivem.gitbook.io/ccfivem-docs/server-management/chat-cc_chat.md).

# Chat (cc\_chat)

**CrankChaos Chat** replaces the built-in FiveM chat: channels, `/me` and `/do` as 3D text, emojis and anti-spam.

## Features

* Global, job, gang and OOC channels, checked on the server
* `/me` and `/do` as 3D text with typing indicator
* Share your GPS location in chat
* Emoji picker and command suggestions
* Anti-spam (rate limit, duplicate detection, temporary mute)
* Compatible with the standard `chat:*` events, so existing scripts keep working
* Optional Discord webhook for logs
* Settings saved per character

## Frameworks

ESX Legacy, QBCore and QBox. The framework is detected through the framework bridge.

## Security

The client only sends the text and the desired channel. Name, job/gang, recipients, GPS position and rate limiting are decided by the server. Messages are rendered as text, never as HTML.

{% hint style="info" %}
The program code is protected by Cfx asset escrow. `config/`, `locales/` and `shared/cc_framework.lua` stay editable.
{% endhint %}

## Pages

* Installation
* Configuration
* API
* FAQ

Need help? See Support.

## Installation

See also the general installation guide and dependencies.

### Requirements

| Resource                   | Required | Notes                                                    |
| -------------------------- | -------- | -------------------------------------------------------- |
| `oxmysql`                  | yes      | fxmanifest dependency; stores the per-character settings |
| ESX Legacy / QBCore / QBox | yes      | auto-detected                                            |

{% hint style="warning" %}
The built-in FiveM `chat` resource must be disabled. Two chats must never run in parallel.
{% endhint %}

### Steps

1. Copy the folder to `resources/[crankchaos]/cc_chat` (including `web/dist`).
2. Remove or stop the default `chat` resource in your `server.cfg`.
3. Add to `server.cfg`, ideally before your other gameplay resources:

```cfg
ensure oxmysql
ensure es_extended        # or qb-core / qbx_core
ensure cc_chat
```

4. Start the server. The console prints a ready line for `[cc_chat]`.

### Database

No SQL import needed. The table `cc_chat_settings` is created automatically.

### Permissions

No ACE permissions are required.

## Configuration

Editable files: `config/config.lua`, `config/ui.lua` (language and look), `locales/de.json`, `locales/en.json`, `shared/cc_framework.lua` (framework bridge).

### General

```lua
Config.OpenKey = 't'              -- key to open the chat (cc_chat_open)
Config.MaxLength = 280            -- max characters per message
Config.MessageDurationMs = 12000  -- how long messages stay visible
Config.HistoryLimit = 100         -- messages kept in history
```

Players can rebind the key in the FiveM key bindings.

### Anti-spam

```lua
Config.RateLimit = {
    windowMs = 10000,     -- time window
    messages = 6,         -- max messages per window
    duplicateMs = 30000,  -- identical message blocked for this long
    muteMs = 15000,       -- temporary mute when exceeded
}
```

### 3D text

```lua
Config.ThreeD = {
    distance = 20.0,        -- range of /me and /do
    durationMs = 7000,      -- display time
    typingDistance = 12.0,  -- range of the typing indicator
}
```

### Channels

```lua
Config.Channels = {
    global = { enabled = true },
    job = { enabled = true },
    gang = { enabled = true },
    ooc = { enabled = true },
}
```

Job and gang channels are only visible to players with a matching job or gang.

### Gangs on ESX

ESX has no shared gang standard. Map jobs to gangs:

```lua
Config.GangJobs = {}
-- example: Config.GangJobs.ballas = 'ballas'
```

QBCore and QBox provide gangs directly.

### Command suggestions

```lua
Config.Commands = {
    { name = 'me', help = 'chat.command.me', args = 'text' },
    { name = 'do', help = 'chat.command.do', args = 'text' },
    { name = 'clear', help = 'chat.command.clear' },
}
```

### Discord logging

```lua
Config.Webhook = {
    enabled = false,
    url = '',
    username = 'CrankChaos Chat',
}
```

The URL is only used server-side and is never sent to clients.

## Exports, Events & Commands

### Commands

| Command / key        | Who      | Effect                     |
| -------------------- | -------- | -------------------------- |
| `T` (`cc_chat_open`) | everyone | open the chat; rebindable  |
| `/me <text>`         | everyone | 3D action text nearby      |
| `/do <text>`         | everyone | 3D description text nearby |
| `/clear`             | everyone | clear your own chat        |

### Server export

#### SendMessage(channel, author, text, targets)

| Parameter | Description                                            |
| --------- | ------------------------------------------------------ |
| `channel` | channel, default `system`                              |
| `author`  | sender name, default `Server`                          |
| `text`    | message text                                           |
| `targets` | `nil` = everyone, a server ID, or a list of server IDs |

```lua
exports.cc_chat:SendMessage('system', 'Server', 'Restart in 10 minutes')
exports.cc_chat:SendMessage('system', 'Support', 'Message', { 12, 18 })
```

### Compatible client events

cc\_chat handles the standard FiveM chat events, so existing scripts work without changes:

* `chat:addMessage`
* `chat:addSuggestion`
* `chat:removeSuggestion`
* `chat:clear`

```lua
TriggerClientEvent('chat:addMessage', src, { args = { 'System', 'Hello' } })
```

## FAQ & Troubleshooting

**Two chats appear / messages are duplicated.** The default FiveM `chat` resource is still running. Remove it from `server.cfg`.

**Player settings are lost after a restart.** `oxmysql` was not running when cc\_chat started. Make sure `ensure oxmysql` comes before `ensure cc_chat`.

**The gang channel is empty on ESX.** ESX has no gang system. Map gang jobs in `Config.GangJobs`.

**A player cannot see the job channel.** Job and gang channels are only shown to players with a matching job or gang.

**A player is suddenly muted.** They hit the anti-spam limit (`Config.RateLimit`). The mute ends after `muteMs`.

**Can players change the open key?** Yes, in the FiveM key bindings (`cc_chat_open`).

Still stuck? See Support.


---

# 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://ccfivem.gitbook.io/ccfivem-docs/server-management/chat-cc_chat.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.