Integrations

Integrations represent a connection between a service and a guild. This may include third-party services such as Twitch or YouTube, Discord-housed integrations such as bots, or internal integrations such as role subscriptions.

Integration Object

Integration Structure

Field	Type	Description
id ¹	snowflake	The ID of the integration
name	string	The name of the integration
type	string	The type of integration
enabled	boolean	Whether this integration is enabled
account	integration account object	Integration account information
syncing? ²	boolean	Whether this integration is syncing
role_id? ²	snowflake	Role ID that this integration uses for subscribers
enable_emoticons? ²	boolean	Whether emoticons should be synced for this integration (Twitch only)
expire_behavior? ²	integer	The behavior of expiring subscribers
expire_grace_period? ²	integer	The grace period before expiring subscribers (one of 1, 3, 7, 14, 30, in days)
synced_at? ²	ISO8601 timestamp	When this integration was last synced
subscriber_count? ²	integer	How many subscribers this integration has
revoked? ²	boolean	Whether this integration has been revoked
application? ³	integration application object	The integrated OAuth2 application
scopes? ³	array[string]	The scopes the application has been authorized with
role_connections_metadata ³ ⁴	array[application role connection metadata object]	The metadata that the application has set for role connections
user? ⁵	partial user object	The user that added this integration

¹ This field may also be the literal string "twitch-partners" to represent the Twitch Partners integration.

² Only provided for Twitch and YouTube integrations.

³ Only provided for Discord application integrations.

⁴ Only included when fetched from Get Guild Integrations with include_role_connections_metadata set to true.

⁵ Only included for integrations when fetched through the Get Guild Integrations endpoint. Some older or internally-created integrations may not have an attached user.

Integration Type

Value	Name
twitch	Twitch integration
youtube	YouTube integration
discord	Discord application integration
guild_subscription	Internal role subscription integration

Integration Expire Behavior

Value	Name	Description
0	REMOVE_ROLE	Remove the subscriber role from the user on expiration
1	KICK	Remove the user from the guild on expiration

Integration Account Structure

Field	Type	Description
id	string	The ID of the account
name	string	The name of the account

Integration Application Object

Integration Application Structure

Field	Type	Description
id	snowflake	The ID of the application
name	string	The name of the application
description	string	The description of the application
icon	?string	The application's icon hash
cover_image?	string	The application's default rich presence invite cover image hash
splash?	string	The application's splash hash
type	?integer	The type of the application, if any
primary_sku_id?	snowflake	The ID of the application's primary SKU (game, application subscription, etc.)
bot?	partial user object	The bot attached to this application
deeplink_uri?	?string	The URL used for deep linking during OAuth2 authorization on mobile devices
third_party_skus?	array[application SKU object]	The third party SKUs of the application's game
role_connections_verification_url? ¹	?string	The role connection verification entry point of the integration; when configured, this will render the application as a verification method in guild role verification configuration
is_verified	boolean	Whether the application is verified
is_discoverable	boolean	Whether the application is discoverable in the application directory
is_monetized	boolean	Whether the application has monetization enabled

¹ Only present when fetched from the Get Guild Integrations endpoint with include_role_connections_metadata set to true.

Integration Guild Object

Integration Guild Structure

Field	Type	Description
id	snowflake	The ID of the guild
name	string	The name of the guild (2-100 characters)
icon	?string	The guild's icon hash

GIF Object

GIF Structure

Field	Type	Description
id	string	The ID of the GIF
title (deprecated)	string	The title of the GIF
url	string	The provider source URL of the GIF
src	string	The media URL of the GIF in the requested format
gif_src	string	The media URL of the GIF in GIF format
preview	string	A preview image of the GIF
width	integer	Width of image
height	integer	Height of image

GIF Media Format

Value	Description
mp4	MP4 video
tinymp4	MP4 video in a smaller size
nanomp4	MP4 video in a very small size
loopedmp4	MP4 video that loops (same as `mp4`)
webm	WebM video
tinywebm	WebM video in a smaller size
nanowebm	WebM video in a very small size
gif	GIF image
mediumgif	GIF image in a medium size
tinygif	GIF image in a smaller size
nanogif	GIF image in a very small size

Example GIF

{
  "id": "12409989992265318124",
  "title": "",
  "url": "https://tenor.com/view/tasha-steelz-gif-25509948",
  "src": "https://media.tenor.com/rDkkJaMgfuwAAAP4/tasha-steelz.webm",
  "gif_src": "https://media.tenor.com/rDkkJaMgfuwAAAAC/tasha-steelz.gif",
  "width": 150,
  "height": 84,
  "preview": "https://media.tenor.com/rDkkJaMgfuwAAAAD/tasha-steelz.png"
}

Endpoints

Get Guild Integrations

GET/guilds/{guild.id}/integrations

Returns a list of integration objects for the guild. Requires the MANAGE_GUILD permission.

Query String Parameters

Field	Type	Description
has_commands?	boolean	Whether to only include Discord application integrations with registered commands (default false)
include_role_connections_metadata?	boolean	Whether to include integration role connection metadata (default false)

Create Guild Integration

POST/guilds/{guild.id}/integrations

Audit Log Reason

Enables an integration for the guild. Requires the MANAGE_GUILD permission. Returns a 204 empty response on success. Fires Guild Integrations Update and Integration Create Gateway events.

JSON Parameters

Field	Type	Description
type	string	The type of integration to enable (only `twitch` and `youtube` are supported)
id	string	The ID of the integration account to enable

Sync Guild Integration

POST/guilds/{guild.id}/integrations/{integration.id}/sync

Audit Log Reason

Syncs an integration for the guild. Requires the MANAGE_GUILD permission. Returns a 204 empty response on success. Fires Guild Integrations Update and Integration Update Gateway events.

Modify Guild Integration

PATCH/guilds/{guild.id}/integrations/{integration.id}

Audit Log Reason

Modifies the behavior and settings of the integration in the guild. Requires the MANAGE_GUILD permission. Returns a 204 empty response on success. Fires Guild Integrations Update and Integration Update Gateway events.

JSON Parameters

Field	Type	Description
expire_behavior?	integer	The behavior of expiring subscribers
expire_grace_period?	integer	The grace period before expiring subscribers (one of 1, 3, 7, 14, 30, in days)
enable_emoticons?	boolean	Whether emoticons should be synced for this integration (Twitch only)

Delete Guild Integration

DELETE/guilds/{guild.id}/integrations/{integration.id}

Audit Log Reason

Removes the given integration ID from the guild. Deletes any associated webhooks and kicks the associated bot (if there is one). Requires the MANAGE_GUILD permission. Returns a 204 empty response on success. Fires Guild Integrations Update, Integration Delete, and optionally Guild Member Remove and Webhooks Update Gateway events.

Migrate Guild Command Scope

POST/guilds/{guild.id}/migrate-command-scope

Migrates all Discord application integrations in the guild to the applications.commands OAuth2 scope. Requires the MANAGE_GUILD permission. Fires a Guild Integrations Update and multiple Integration Update Gateway events.

Response Body

Field	Type	Description
integration_ids_with_app_commands	array[snowflake]	The IDs of migrated integrations that now have application commands registered

Get Guild Integration Application IDs

GET/users/@me/guilds/integration-application-ids

Returns a mapping of guild IDs to lists of application IDs attached to the integrations in the current user's guilds.

Example Response

{
  "81384788765712384": [
    "157858575924985856",
    "157889000391180288",
    "157873248346832897",
    "157947794294833152",
    "173805066229252096"
  ],
  "1046920999469330512": []
}

Get Channel Integrations

GET/channels/{channel.id}/integrations

Returns a list of integration objects for the private channel.

Delete Channel Integration

DELETE/channels/{channel.id}/integrations/{integration.id}

Audit Log Reason

Removes the given integration ID from the channel. Returns a 204 empty response on success. Fires an Integration Delete Gateway event.

Field	Type	Description
q	string	The search query to use

Tenor GIF Structure

Field	Type	Description
type	string	The type of the GIF (always `gif`)
url	string	The provider source URL of the GIF
src	string	The media URL of the GIF
width	integer	Width of image
height	integer	Height of image

Example Response

[
  {
    "type": "gif",
    "url": "https://tenor.com/bQ3Du.gif",
    "src": "https://media.tenor.com/RbG_9Eh9KLoAAAAS/alien-alien-reveal.gif",
    "width": 100,
    "height": 90
  }
]

GET/gifs/trending-search

Returns a list of the top trending search terms.

Query String Parameters

Field	Type	Description
limit? ¹	integer	The maximum number of search terms to return (1-50, default 5)
locale?	string	The locale to use in search results (default `en-US`)

¹ The limit is only a suggestion; the API may return fewer GIFs.

Get Suggested GIF Search Terms

GET/gifs/suggest

Unauthenticated

Returns a list of recommended search terms based on the provided query.

Query String Parameters

Field	Type	Description
q	string	The search query to use
limit? ¹	integer	The maximum number of search terms to return (1-50, default 20)
locale?	string	The locale to use in search results (default `en-US`)

¹ The limit is only a suggestion; the API may return fewer GIFs.

Search GIFs

GET/gifs/search

Unauthenticated

Returns a list of GIF objects based on the provided query.

Query String Parameters

Field	Type	Description
q	string	The search query to use
limit? ¹	integer	The maximum number of GIFs to return (20-500)
media_format?	string	The media format to use (default `mediumgif`)
locale?	string	The locale to use in search results (default `en-US`)

¹ The limit is only a suggestion; the API may return fewer GIFs.

GET/gifs/trending

Unauthenticated

Returns trending GIF categories and their associated preview GIFs.

Query String Parameters

Field	Type	Description
media_format?	string	The media format to use (default `mediumgif`)
locale?	string	The locale to use in search results (default `en-US`)

Response Body

Field	Type	Description
categories	array[GIF category object]	The trending GIF categories
gifs	array[GIF object]	A trending GIF to use as a placeholder

GIF Category Structure

Field	Type	Description
name	string	The name of the category
src	string	The media URL of a preview GIF

Example Response

{
  "categories": [
    {
      "name": "whatever",
      "src": "https://media.tenor.com/97c0UK_cAHMAAAAd/whatever-sassy.gif"
    }
  ],
  "gifs": [
    {
      "id": "16750982996130936929",
      "title": "",
      "url": "https://tenor.com/view/peace-out-peace-sign-peace-ice-age-eddie-gif-16750982996130936929",
      "src": "https://media.tenor.com/6HdySNL-OGEAAAAC/peace-out-peace-sign.gif",
      "gif_src": "https://media.tenor.com/6HdySNL-OGEAAAAC/peace-out-peace-sign.gif",
      "width": 498,
      "height": 498,
      "preview": "https://media.tenor.com/6HdySNL-OGEAAAAD/peace-out-peace-sign.png"
    }
  ]
}

GET/gifs/trending-gifs

Unauthenticated

Returns a list of GIF objects that are currently trending.

Query String Parameters

Field	Type	Description
limit? ¹	integer	The maximum number of GIFs to return (20-500)
media_format?	string	The media format to use (default `mediumgif`)
locale?	string	The locale to use in search results (default `en-US`)

¹ The limit is only a suggestion; the API may return fewer GIFs.

Track Selected GIF

POST/gifs/select

Tracks the selection of a GIF by the user. Returns a 204 empty response on success.

JSON Parameters

Field	Type	Description
id	string	The ID of the selected GIF
q	string	The search query used to find the GIF