diff --git a/guide/docs/popular-topics/webhooks.mdx b/guide/docs/popular-topics/webhooks.mdx index b312f481..b8be41e3 100644 --- a/guide/docs/popular-topics/webhooks.mdx +++ b/guide/docs/popular-topics/webhooks.mdx @@ -5,4 +5,116 @@ hide_table_of_contents: true # Webhooks - +Webhooks provide a way to send messages to guild channels without a bot user or authentication. + +## Creating or Fetching webhooks + +There are two main ways of using webhooks in disnake. + +1. The first method involves fetching existing Webhooks from a Guild or Channel, or creating a new webhook. + - `await Guild.webhooks()` - Fetches a list of webhooks available in the guild. + - `await Channel.webhooks()` - Fetches a list of webhooks available in the channel. + - `await Channel.create_webhook()` - Creates and returns the created Webhook for the Channel. (Requires manage_webhooks) + - Supported Channels for `.webhooks()` and `.create_webhook()`: + - TextChannel + - ForumChannel + - VoiceChannel + - StageChannel + +:::note +Webhooks fetched or created using these methods are automatically bound to the bot's internal HTTP session. +::: + +2. The second way involves creating partial webhooks using the following methods: + - Webhook.from_url() - Create a Webhook from only a webhook + URL. + - Webhook.partial() - Create a Webhook with only a webhook ID, + and token. + +:::note +Webhooks created using these methods require that you create and manage a separate HTTP session that is provided to the method used. +An [example of this](#creating-a-webhook-from-a-url) is available further down this page. +::: + +### Other Webhook methods + +- Webhook.fetch - Useful for fetching the full webhook from a partial + webhook. +- Webhook.delete - Deletes the webhook. (Requires + manage_webhooks + + ) +- Webhook.edit - Edits the webhook (Requires + manage_webhooks + + ) +- Webhook.fetch_message - Fetches a + WebhookMessage + owned by the webhook using the messages's ID. +- Webhook.send - Sends a message using the Webhook. + +### Creating a Webhook from a URL + +```python title="webhook_from_url.py" +import disnake +import asyncio +import aiohttp + +URL = "https://discord.com/api/webhooks/808030843078836254/H82Ba5B958KkeAG4u4A3otcQvl64XPFNqmlP2aMmpJbCHntrEfxgoqE7_OZAzqP9Z2Dr" + + +async def main(): + + # Create the HTTP session using aiohttp.ClientSession + async with aiohttp.ClientSession() as session: + # Construct the Webhook from the URL using the HTTP session. + webhook = disnake.Webhook.from_url(URL, session=session) + # Send a message using the webhook with a custom username. + # Webhook `username` and `avatar` can be changed for each message that is sent. + # Doing this in the `.send` method will not alter the Webhook as it appears in the + # Guild or Channel integrations. + await webhook.send("I sent my first webhook!.", username="Webhook!") + + +if __name__ == "__main__": + asyncio.run(main()) +``` + +## SyncWebhook + +When working with Webhooks in the context of a bot, it's advisable to utilize disnake.Webhook to maintain an asynchronous approach. +Nevertheless, disnake does offer an alternative synchronous variant of Webhooks known as disnake.SyncWebhook, designed for scenarios +outside the realm of asynchronous projects. + +It's important to note that this version of the `Webhook` should be avoided in asynchronous projects, as its HTTP requests rely on the synchronous and blocking +[Requests](https://requests.readthedocs.io/en/latest/) library. + +Usage of this object remains largely consistent; the primary distinction is the utilization of [Requests](https://requests.readthedocs.io/en/latest/) for managing the HTTP session. + +### SyncWebhook example + +```python title='sync_webhook.py' +import requests +import disnake + + +URL = "https://discord.com/api/webhooks/808030843078836254/H82Ba5B958KkeAG4u4A3otcQvl64XPFNqmlP2aMmpJbCHntrEfxgoqE7_OZAzqP9Z2Dr" + + +def main(): + + # This time we create a requests.Session + with requests.Session() as session: + + # We are still passing the session to the Webhook, however + # it should be noted that if a session is not provided, the + # webhook will create it's own `requests.Session` and use that instead. + webhook = disnake.SyncWebhook.from_url(URL, session=session) + + # Notice we do not `await` the `webhook.send` method this time. + webhook.send("My first synchronous webhook!", username="SyncWebhook!") + + +if __name__ == "__main__": + main() +```