Exports & API Reference

Table of Contents

• Overview
• Client-Side Exports
• Server-Side Exports
• Client Events
• Server Events
• Message Format
• Message Hooks
• Integration Examples

---

Overview

Oxide Chat provides full compatibility with the standard FiveM chat API, plus additional functionality.

Dual Export Names

Both export names work identically:

-- These are equivalent:
exports['oxide-chat']:addMessage(...)
exports['chat']:addMessage(...)

The chat export works because Oxide Chat uses provide 'chat' in its manifest.

---

Client-Side Exports

addMessage

Display a message in chat.

exports['oxide-chat']:addMessage(message)

Parameters

Name	Type	Description
message	table/string	Message data or simple string

Message Table Properties

Property	Type	Description
args	table	{ author, message } or { message }
color	table/string	RGB array {r, g, b} or hex string #RRGGBB
templateId	string	Chat type for styling
chatType	string	Alternative to templateId

Examples

-- Simple message
exports['oxide-chat']:addMessage('Hello world!')

-- With author
exports['oxide-chat']:addMessage({
    args = { 'System', 'Welcome to the server!' }
})

-- With color (RGB)
exports['oxide-chat']:addMessage({
    args = { 'Alert', 'Low health!' },
    color = { 255, 0, 0 }
})

-- With color (hex)
exports['oxide-chat']:addMessage({
    args = { 'Success', 'Transaction complete' },
    color = '#00FF00'
})

-- With chat type styling
exports['oxide-chat']:addMessage({
    args = { '', 'Server restarting...' },
    chatType = 'announcement'
})

---

addSuggestion

Add a command suggestion to autocomplete.

exports['oxide-chat']:addSuggestion(name, help, params)

Parameters

Name	Type	Description
name	string	Command name with / prefix
help	string	Description text
params	table	Array of parameter definitions

Param Properties

Property	Type	Description
name	string	Parameter name
help	string	Parameter description

Example

exports['oxide-chat']:addSuggestion('/pay', 'Pay a player money', {
    { name = 'id', help = 'Player server ID' },
    { name = 'amount', help = 'Amount to pay' }
})

---

addSuggestions

Add multiple suggestions at once.

exports['oxide-chat']:addSuggestions(suggestions)

Parameters

Name	Type	Description
suggestions	table	Array of suggestion objects

Example

exports['oxide-chat']:addSuggestions({
    { name = '/job', help = 'Check your current job' },
    { name = '/money', help = 'Check your balance' },
    { name = '/inventory', help = 'Open inventory', params = {} },
})

---

removeSuggestion

Remove a command suggestion.

exports['oxide-chat']:removeSuggestion(name)

Parameters

Name	Type	Description
name	string	Command name with / prefix

Example

exports['oxide-chat']:removeSuggestion('/secretcommand')

---

clearChat

Clear all messages from chat.

exports['oxide-chat']:clearChat()

---

isEnabled

Check if chat is enabled.

local enabled = exports['oxide-chat']:isEnabled()

Returns

Type	Description
boolean	Whether chat is enabled

---

setEnabled

Enable or disable chat.

exports['oxide-chat']:setEnabled(enabled)

Parameters

Name	Type	Description
enabled	boolean	Enable/disable chat

Example

-- Disable chat during cutscene
exports['oxide-chat']:setEnabled(false)

-- Re-enable after cutscene
exports['oxide-chat']:setEnabled(true)

---

getSuggestions

Get all registered suggestions.

local suggestions = exports['oxide-chat']:getSuggestions()

Returns

Type	Description
table	Map of command name to suggestion data

---

Server-Side Exports

addMessage

Send a message to one or all players.

exports['oxide-chat']:addMessage(target, message)
-- or
exports['oxide-chat']:addMessage(message)  -- Broadcasts to all

Parameters

Name	Type	Description
target	number	Player server ID or -1 for all
message	table	Message data

Examples

-- Send to specific player
exports['oxide-chat']:addMessage(source, {
    args = { 'Bank', 'You deposited $1,000' },
    color = { 0, 255, 0 }
})

-- Broadcast to all players
exports['oxide-chat']:addMessage({
    args = { 'Server', 'Maintenance in 5 minutes' },
    chatType = 'announcement'
})

-- Using -1 for all
exports['oxide-chat']:addMessage(-1, {
    args = { 'Event', 'Double XP is now active!' }
})

---

addSuggestion

Send a command suggestion to a player.

exports['oxide-chat']:addSuggestion(target, name, help, params)

Parameters

Name	Type	Description
target	number	Player server ID or -1 for all
name	string	Command name with / prefix
help	string	Description text
params	table	Parameter definitions

---

removeSuggestion

Remove a suggestion for a player.

exports['oxide-chat']:removeSuggestion(target, name)

---

clearChat

Clear chat for one or all players.

exports['oxide-chat']:clearChat(target)

Parameters

Name	Type	Description
target	number	Player server ID, -1 for all, or nil for all

---

addTemplate

Register a message template.

exports['oxide-chat']:addTemplate(id, template)

Parameters

Name	Type	Description
id	string	Template identifier
template	string	Template format string

---

registerMessageHook

Register a hook to intercept/modify messages.

local hookId = exports['oxide-chat']:registerMessageHook(callback)

Parameters

Name	Type	Description
callback	function	Hook function

Returns

Type	Description
number	Hook ID for reference

See Message Hooks for detailed usage.

---

Client Events

chat:addMessage

Display a message.

TriggerEvent('chat:addMessage', {
    args = { 'Author', 'Message' },
    color = { 255, 255, 255 }
})

chat:addSuggestion

Add a suggestion.

TriggerEvent('chat:addSuggestion', '/command', 'Help text', {
    { name = 'param', help = 'Parameter help' }
})

chat:addSuggestions

Add multiple suggestions.

TriggerEvent('chat:addSuggestions', {
    { name = '/cmd1', help = 'Command 1' },
    { name = '/cmd2', help = 'Command 2' },
})

chat:removeSuggestion

Remove a suggestion.

TriggerEvent('chat:removeSuggestion', '/command')

chat:clear

Clear all messages.

TriggerEvent('chat:clear')

chatMessage (Legacy)

Legacy event for simple messages.

TriggerEvent('chatMessage', 'Author', { 255, 0, 0 }, 'Message text')

---

Server Events

chat:addMessage

Send from server to client.

TriggerClientEvent('chat:addMessage', source, {
    args = { 'Server', 'Welcome!' }
})

chat:addSuggestion

Send suggestion to client.

TriggerClientEvent('chat:addSuggestion', source, '/help', 'Show help')

chat:addSuggestions

Send multiple suggestions.

TriggerClientEvent('chat:addSuggestions', source, suggestions)

chat:removeSuggestion

Remove a suggestion.

TriggerClientEvent('chat:removeSuggestion', source, '/command')

chat:clear

Clear client's chat.

TriggerClientEvent('chat:clear', source)
TriggerClientEvent('chat:clear', -1)  -- All players

---

Message Format

args Array

The args array determines the message format:

-- Two elements: author and message
args = { 'John', 'Hello everyone!' }
-- Output: "John: Hello everyone!"

-- One element: message only
args = { 'System message' }
-- Output: "System message"

-- Empty author
args = { '', 'Pre-formatted message' }
-- Output: "Pre-formatted message"

Color Formats

Colors can be specified as RGB arrays or hex strings:

-- RGB array
color = { 255, 128, 0 }

-- Hex string
color = '#FF8000'

-- Nested array (legacy support)
color = {{ 255, 128, 0 }}

Chat Types

Apply styling from Config.ChatTypes:

-- Using templateId
{ templateId = 'announcement' }

-- Using chatType
{ chatType = 'police' }

Chat type styling includes:

• Color
• Prefix (e.g., "[LSPD]")
• Italic formatting

---

Message Hooks

Intercept and modify messages before they're sent.

Registering a Hook

-- Server-side
local hookId = exports['oxide-chat']:registerMessageHook(function(source, author, message)
    -- Return modified message
    return {
        author = author,
        message = message:gsub('badword', '****')
    }
end)

Hook Callback Parameters

Parameter	Type	Description
source	number	Player server ID
author	string	Message author
message	string	Message content

Hook Return Values

Return	Effect
false	Cancel the message
{ cancel = true }	Cancel the message
{ author = '...' }	Modify author
{ message = '...' }	Modify message
nil	No modification

Hook Examples

-- Profanity filter
exports['oxide-chat']:registerMessageHook(function(source, author, message)
    local filtered = message:gsub('badword', '****')
    return { message = filtered }
end)

-- Block messages from muted players
local mutedPlayers = {}

exports['oxide-chat']:registerMessageHook(function(source, author, message)
    if mutedPlayers[source] then
        return false  -- Cancel message
    end
end)

-- Add prefix based on player data
exports['oxide-chat']:registerMessageHook(function(source, author, message)
    local Player = QBCore.Functions.GetPlayer(source)
    if Player and Player.PlayerData.metadata.vip then
        return { author = '[VIP] ' .. author }
    end
end)

Hook Cleanup

Hooks are automatically removed when their registering resource stops.

---

Integration Examples

Shop Purchase Notification

-- Server-side
RegisterNetEvent('shop:purchase', function(itemName, price)
    local src = source
    exports['oxide-chat']:addMessage(src, {
        args = { 'Shop', 'Purchased ' .. itemName .. ' for $' .. price },
        color = '#00FF00'
    })
end)

Job-Specific Announcement

-- Server-side
function AnnounceToJob(jobName, message)
    for _, playerId in ipairs(QBCore.Functions.GetPlayers()) do
        local Player = QBCore.Functions.GetPlayer(playerId)
        if Player and Player.PlayerData.job.name == jobName then
            exports['oxide-chat']:addMessage(playerId, {
                args = { '', message },
                chatType = jobName
            })
        end
    end
end

-- Usage
AnnounceToJob('police', '[DISPATCH] 10-90 at Legion Square')

Dynamic Suggestion Updates

-- Client-side: Update suggestions based on job
RegisterNetEvent('QBCore:Client:OnJobUpdate', function(job)
    -- Remove old job suggestions
    exports['oxide-chat']:removeSuggestion('/oldcommand')

    -- Add new job suggestions
    if job.name == 'police' then
        exports['oxide-chat']:addSuggestion('/cuff', 'Handcuff a player')
        exports['oxide-chat']:addSuggestion('/escort', 'Escort a player')
    end
end)

Temporary Chat Disable

-- Client-side: Disable during cutscene
function StartCutscene()
    exports['oxide-chat']:setEnabled(false)
    -- ... cutscene code ...
end

function EndCutscene()
    exports['oxide-chat']:setEnabled(true)
end

Custom Chat Type

-- Config addition (config/main.lua)
Config.ChatTypes.gang = {
    prefix = 'GANG',
    color = '#9B59B6'
}

-- Server-side usage
exports['oxide-chat']:addMessage(source, {
    args = { '', gangName .. ' Radio: ' .. message },
    chatType = 'gang'
})