Integrate Discord Bot

Endpoint to integrate a Discord bot into the ToolzzAI agent.

Request Example

curl --request POST \
  --url https://chat.api.toolzz.com.br/api/v1/discord/integration \
  --header 'Authorization: Bearer TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data '
{
  "botId": "uuid",
  "unitId": "uuid",
  "title": "string",
  "guildId": "string_digits",
  "guildName": "string",
  "channelIds": [
    "string_digits"
  ],
  "channelsDetail": [
    {
      "id": "string_digits",
      "guild_id": "string_digits",
      "name": "string",
      "type": 0,
      "position": 123,
      "parent_id": "string_digits | null",
      "topic": "string | null",
      "nsfw": false,
      "last_message_id": "string_digits | null",
      "rate_limit_per_user": 0,
      "flags": 0,
      "icon_emoji": {
        "id": "uuid | null",
        "name": "string | null"
      },
      "theme_color": null,
      "permission_overwrites": []
    }
  ],
  "permissions": "string_digits",
  "autoReplyOnMention": true,
  "threadAutoCreate": true,
  "scope": "all | mentions | none",
  "botToken": "discord_bot_token"
}
'

Response Example

{
  "id": "uuid",
  "title": "string",
  "connectionStatus": "string",
  "guildName": "string",
  "channelsDetail": [
    {
      "id": "string_digits",
      "name": "string"
    }
  ],
  "channelIds": ["string_digits"],
  "isActive": true,
  "createdAt": "2026-04-17 12:26:12.804444"
}

Request description

Access Token

Parameter	Type	Description	Required
Authorization	String	Access token (“Bearer” must be before the token)	Yes

Body Parameters

Parameter	Type	Description	Required
botId	UUID	Unique bot identifier in the Toolzz AI system.	Yes
unitId	UUID	Organizational unit identifier.	Yes
title	String	Custom title to identify the integration.	Yes
guildId	String	Numeric ID (Snowflake) of the Discord server.	Yes
guildName	String	Discord server name.	Yes
channelIds	Array[Str]	List containing only the IDs of the channels to be monitored.	Yes
permissions	String	Bitwise permissions (number defining the bot’s access).	Yes
autoReplyOnMention	Boolean	If active, the bot automatically responds when mentioned.	Yes
threadAutoCreate	Boolean	If active, the bot creates threads to organize conversations.	Yes
scope	String	Action scope (e.g., all, mentions).	Yes
botToken	String	Secret token (Bot Token) obtained from the Discord Developer Portal.	Yes
channelsDetail[]	Array[Obj]	List of objects with technical details for each channel:	Yes
channelsDetail[].id	String	Channel Snowflake ID.	Yes
channelsDetail[].name	String	Channel name (e.g., “general”).	Yes
channelsDetail[].type	Number	Channel type (e.g., 0 for text, 2 for voice, 4 for category).	Yes
channelsDetail[].guild_id	String	ID of the server the channel belongs to.	Yes
channelsDetail[].position	Number	Hierarchical position of the channel in the server list.	No
channelsDetail[].parent_id	String	ID of the parent category where the channel is inserted.	No
channelsDetail[].topic	String	Description/Topic defined for the channel.	No
channelsDetail[].nsfw	Boolean	Defines if the channel is marked for adult content.	No
channelsDetail[].flags	Number	Internal configuration flags of the channel on Discord.	No
channelsDetail[].icon_emoji	Object	Object containing id and name of the channel emoji.	No

Response description

Here is the consolidated technical documentation for the response (return) of the Discord integration configuration, based on the provided object:

Unified Documentation: Discord Configuration Response

Key	Type	Description
id	UUID	Unique identifier of the integration configuration in the database.
botId	UUID	Unique bot identifier in the Toolzz AI system.
unitId	UUID	Unique identifier of the owning organizational unit.
title	String	Title assigned to the integration.
isActive	Boolean	Defines if the integration is active in the system.
connectionStatus	String	Current status of the connection with Discord (e.g., disconnected, connected).
guildId	String	Snowflake ID of the Discord server.
guildName	String	Discord server name.
channelIds[]	Array[Str]	List of IDs of the channels configured for interaction.
channelsDetail[]	Array[Obj]	Summary list with the details of the available channels:
channelsDetail[].id	String	Channel Snowflake ID.
channelsDetail[].name	String	Channel name on Discord.
scope	String	Message monitoring scope (e.g., all).
permissions	String	Bitwise permission string of the bot on the server.
autoReplyOnMention	Boolean	If the bot automatically responds when mentioned.
threadAutoCreate	Boolean	If the bot automatically creates threads in new conversations.
welcomeMessage	String	Welcome message sent by the bot when starting interactions.
botToken	String	Bot token (usually masked for security).
isTokenMasked	Boolean	Indicates if the botToken is hidden/masked in the response.
lastConnectedAt	String/Null	Date and time of the last successful connection.
lastDisconnectedAt	String/Null	Date and time of the last recorded disconnection.
lastConnectionErrorCode	String/Null	Error code of the last failed connection attempt.
lastConnectionErrorMessage	String/Null	Descriptive message of the connection error.
createdAt	String	Record creation date and time (ISO 8601).
updatedAt	String	Last update date and time.
deletedAt	String/Null	Logical deletion date and time (soft delete), if any.

---

Security

To access this endpoint, it is necessary to send a valid access token through the authorization header (Authorization) of the request. Additionally, the API is protected by other security measures to safeguard user data.

To access your access token, follow these steps:

1. Log in to the ToolzzAI platform
2. Click on “Settings”
3. Click on “Access Token”
4. Copy the access token