nss_libs - Discord

Creates an API to send messages to a Discord channel.

WARNING

The Discord API is (for security reasons) only available on server side.

Examples

You can decide if you want to create a Discord API object based only on a webhook url (one hook + multiple players) or based on a specific player (one hook + one player).

One hook + one player

In this case an API object is created for a specific player and avatar image. This API object is used to send messages in the name of that specific player given in API object creation.

lua

-- Creates a reusable Discord API object. In this example for the example player "John Doe".
---@type NssLibsDiscordApi
local discord_api = exports.nss_libs:getDiscordApi(
        GetCurrentResourceName(),
        'WEBHOOK_URL',
        'USERNAME_OR_PLAYER_NAME_OR_BOT_NAME', -- E.g. as example the current player name "John Doe"
        'AVATAR_URL'
)

-- Send a message in the name of the example player "John Doe"
discord_api.message('Cheese stinks!')

Citizen.Wait(1000)

-- Send another message in the name of the example player "John Doe"
discord_api.message('Cheese still stinks!')

Citizen.Wait(1000)

-- Special case for method 'message': Alternative webhook URL
-- Send another message in the name of the example player "John Doe" to a different webhook url (but the alternate
-- webhook url is only used for this message)
discord_api.message('Player loves stinking cheese!', 'ALTERNATE_WEBHOOK_URL')

One webhook + multiple players

Simple (message)Extended (request)

lua

-- Creates a reusable Discord API object.
---@type NssLibsDiscordApi
local discord_api = exports.nss_libs:getDiscordApi(
        GetCurrentResourceName(),
        'WEBHOOK_URL'
)

-- Create a function to simplify sending messages
---@param username string
---@param avatar string
---@param message string
local sendMessage = function(username, avatar, message)
    discord_api.setUsername(username)
    discord_api.setAvatarUrl(avatar)
    discord_api.message(message)
end

sendMessage('John Doe', 'https://example.com/john_doe_avatar.png', 'Cheese stinks!')

Citizen.Wait(1000)

sendMessage('John Doe', 'https://example.com/john_doe_avatar.png', 'Cheese still stinks!')

Citizen.Wait(1000)

sendMessage('Jack Blue', 'https://example.com/jack_blue_avatar.png', 'Cheese still!')

lua

-- Creates a reusable Discord API object.
---@type NssLibsDiscordApi
local discord_api = exports.nss_libs:getDiscordApi(
        GetCurrentResourceName(),
        'WEBHOOK_URL'
)

-- Create a function to simplify sending messages
-- This function uses the request method instead of the simplified message method. The request object is used in later
-- examples, e.g. for embeds.
---@param username string
---@param avatar string
---@param message string
local sendMessage = function(username, avatar, message)
    local request = discord_api.create(username, avatar, message)
    request.send()
end

sendMessage('John Doe', 'https://example.com/john_doe_avatar.png', 'Cheese stinks!')

Citizen.Wait(1000)

sendMessage('John Doe', 'https://example.com/john_doe_avatar.png', 'Cheese still stinks!')

Citizen.Wait(1000)

sendMessage('Jack Blue', 'https://example.com/jack_blue_avatar.png', 'Cheese still!')

Example with modifiable embeds

lua

-- Creates a reusable Discord API object. In this example for the example player "John Doe".
---@type NssLibsDiscordApi
local discord_api = exports.nss_libs:getDiscordApi(
        GetCurrentResourceName(),
        'WEBHOOK_URL',
        'USERNAME_OR_PLAYER_NAME_OR_BOT_NAME', -- E.g. as example the current player name "John Doe"
        'AVATAR_URL'
)

-- Creates a Discord request object for the example player "John Doe".
---@type NssLibsDiscordRequestApi
local request = discord_api.create()

-- Creates a Discord embed object
---@type NssLibsDiscordRequestEmbedApi
local embed = request.addEmbed()
embed.setTitle('Cheese stinks!')
embed.setColor('#000000')
embed.setDescription('Everyone loves you.')

-- Sends the request
request.send()

Methods

`exports.nss_libs:getDiscordApi(resource_name, webhook_url, username?, avatar_url?)`

Creates the Discord API object.

Param	Type	Default	Description
`resource_name`	`string`	—	The name of the resource that uses the Discord API (used for console identification)
`webhook_url`	`string`	—	The webhook url of the Discord channel
`username`	`string?`	—	The username of the Discord bot or the player name
`avatar_url`	`string?`	—	The avatar url of the Discord bot or the player avatar

Returns NssLibsDiscordApi

`NssLibsDiscordApi`

`.create(username?, avatar_url?, message?)`

Creates a request object for sending Discord messages.

Param	Type	Default	Description
`username`	`string?`	—	Overrides the username given in `getDiscordApi`
`avatar_url`	`string?`	—	Overrides the avatar url given in `getDiscordApi`
`message`	`string?`	—	The default message body, can be `nil` if using embeds only

Returns NssLibsDiscordRequestApi

`.message(message, temporary_webhook_url?)`

Sends a simple message to the Discord channel.

Param	Type	Default	Description
`message`	`string`	—	The message shown in the default message body
`temporary_webhook_url`	`string?`	—	Overrides the webhook url for this message only

`.setUsername(username)`

Sets the username for subsequent messages.

Param	Type	Default	Description
`username`	`string`	—	The username of the Discord bot or the player name

`.setAvatarUrl(avatar_url)`

Sets the avatar url for subsequent messages.

Param	Type	Default	Description
`avatar_url`	`string`	—	The avatar url of the Discord bot or the player

`.setWebhookUrl(webhook_url)`

Sets the webhook url for subsequent messages.

Param	Type	Default	Description
`webhook_url`	`string`	—	The webhook url of the Discord channel

`NssLibsDiscordRequestApi`

`.setUsername(username)`

Sets the username for that specific request.

Param	Type	Default	Description
`username`	`string`	—	The username of the Discord bot or the player name

`.setAvatarUrl(avatar_url)`

Sets the avatar url for that specific request.

Param	Type	Default	Description
`avatar_url`	`string`	—	The avatar url of the Discord bot or the player

`.setContent(message)`

Sets the message content for that specific request.

Param	Type	Default	Description
`message`	`string`	—	The message shown in the default message body

`.enableTextToSpeech()`

Enables text to speech for that specific request.

`.addEmbed()`

Adds an embed object to the request.

Returns NssLibsDiscordRequestEmbedApi

`.send(on_response?)`

Sends the request.

Param	Type	Default	Description
`on_response`	`function?`	—	Callback called after the request completes

The callback receives the following arguments:

Param	Type	Description
`err`	`any`	Error if the request failed
`text`	`string`	Response body text
`headers`	`table`	Response headers
`webhook_url`	`string`	The webhook URL used for this request

lua

request.send(function(err, text, headers, webhook_url)
    if err then
        print('Discord webhook failed:', err)
    else
        print('Message sent to:', webhook_url)
    end
end)

`NssLibsDiscordRequestEmbedApi`

TIP

See Discord webhook documentation for more information about Discord message embeds.

`.setTitle(title)`

Sets the title of the embed.

Param	Type	Default	Description
`title`	`string`	—	The title of the embed

`.setAuthor(name, url?, icon_url?)`

Sets the author of the embed.

Param	Type	Default	Description
`name`	`string`	—	The name of the author
`url`	`string?`	—	The url of the author (name becomes a hyperlink)
`icon_url`	`string?`	—	The icon url of the author

`.setDescription(description)`

Sets the description (content) of the embed.

Param	Type	Default	Description
`description`	`string`	—	The description of the embed

`.setUrl(url)`

Sets the url of the embed.

Param	Type	Default	Description
`url`	`string`	—	The url of the embed

`.setColor(color)`

Sets the color of the embed.

Param	Type	Default	Description
`color`	`string`	—	Hex color code or decimal color code

`.setImage(url)`

Sets the image of the embed.

Param	Type	Default	Description
`url`	`string`	—	The url of the image

`.setThumbnail(url)`

Sets the thumbnail of the embed.

Param	Type	Default	Description
`url`	`string`	—	The url of the thumbnail

`.setFooter(text, icon_url?)`

Sets the footer of the embed.

Param	Type	Default	Description
`text`	`string`	—	The text of the footer
`icon_url`	`string?`	—	The icon url of the footer

`.setTimestamp(utc_timestamp?)`

Sets the timestamp of the embed.

Param	Type	Default	Description
`utc_timestamp`	`string?`	—	ISO-8601 timestamp (`YYYY-MM-DDTHH:MM:SS.000Z`), uses current UTC time if `nil`

`.addField(name, value, inline?)`

Adds a field to the embed.

Param	Type	Default	Description
`name`	`string`	—	The name of the field
`value`	`string`	—	The value of the field
`inline`	`boolean?`	—	If the field should be inline

UI components

Client/server modules

Helper

Objects

nss_libs - Discord

Examples

One hook + one player

One webhook + multiple players

Example with modifiable embeds

Methods

`exports.nss_libs:getDiscordApi(resource_name, webhook_url, username?, avatar_url?)`

`NssLibsDiscordApi`

`.create(username?, avatar_url?, message?)`

`.message(message, temporary_webhook_url?)`

`.setUsername(username)`

`.setAvatarUrl(avatar_url)`

`.setWebhookUrl(webhook_url)`

`NssLibsDiscordRequestApi`

`.setUsername(username)`

`.setAvatarUrl(avatar_url)`

`.setContent(message)`

`.enableTextToSpeech()`

`.addEmbed()`

`.send(on_response?)`

`NssLibsDiscordRequestEmbedApi`

`.setTitle(title)`

`.setAuthor(name, url?, icon_url?)`

`.setDescription(description)`

`.setUrl(url)`

`.setColor(color)`

`.setImage(url)`

`.setThumbnail(url)`

`.setFooter(text, icon_url?)`

`.setTimestamp(utc_timestamp?)`

`.addField(name, value, inline?)`

Helper

nss_libs - Discord ​

Examples ​

One hook + one player ​

One webhook + multiple players ​

Example with modifiable embeds ​

Methods ​

exports.nss_libs:getDiscordApi(resource_name, webhook_url, username?, avatar_url?) ​

NssLibsDiscordApi ​

.create(username?, avatar_url?, message?) ​

.message(message, temporary_webhook_url?) ​

.setUsername(username) ​

.setAvatarUrl(avatar_url) ​

.setWebhookUrl(webhook_url) ​

NssLibsDiscordRequestApi ​

.setUsername(username) ​

.setAvatarUrl(avatar_url) ​

.setContent(message) ​

.enableTextToSpeech() ​

.addEmbed() ​

.send(on_response?) ​

NssLibsDiscordRequestEmbedApi ​

.setTitle(title) ​

.setAuthor(name, url?, icon_url?) ​

.setDescription(description) ​

.setUrl(url) ​

.setColor(color) ​

.setImage(url) ​

.setThumbnail(url) ​

.setFooter(text, icon_url?) ​

.setTimestamp(utc_timestamp?) ​

.addField(name, value, inline?) ​

nss_libs - Discord

Examples

One hook + one player

One webhook + multiple players

Example with modifiable embeds

Methods

`exports.nss_libs:getDiscordApi(resource_name, webhook_url, username?, avatar_url?)`

`NssLibsDiscordApi`

`.create(username?, avatar_url?, message?)`

`.message(message, temporary_webhook_url?)`

`.setUsername(username)`

`.setAvatarUrl(avatar_url)`

`.setWebhookUrl(webhook_url)`

`NssLibsDiscordRequestApi`

`.setUsername(username)`

`.setAvatarUrl(avatar_url)`

`.setContent(message)`

`.enableTextToSpeech()`

`.addEmbed()`

`.send(on_response?)`

`NssLibsDiscordRequestEmbedApi`

`.setTitle(title)`

`.setAuthor(name, url?, icon_url?)`

`.setDescription(description)`

`.setUrl(url)`

`.setColor(color)`

`.setImage(url)`

`.setThumbnail(url)`

`.setFooter(text, icon_url?)`

`.setTimestamp(utc_timestamp?)`

`.addField(name, value, inline?)`