Webhook clients

This page covers the three ways to get something you can post through: creating a webhook, retrieving the webhooks a guild or channel already has, and building a client from a webhook URL. You're assumed to have a bot named "my-bot" logged in and to know the builder contract.

Creating a webhook

a new webhook builder named %string% in %guildchannel% prepares a webhook in a channel; like every builder, nothing exists on Discord until you read the build result of it under await. The bot needs Manage Webhooks in that channel.

on message received seen by "my-bot":
    if discord content of event-message is "!hook":
        set {_b} to a new webhook builder named "Announcer" in event-channel
        set webhook avatar of {_b} to "https://example.com/avatar.png"
        await set {_hook} to the build result of {_b}
        make {_hook} post "Hello from a fresh webhook"

webhook avatar is the only setter of the builder (an image URL or a local file path): the name and the channel are given to the constructor. A channel holds at most 15 webhooks; Discord refuses the build beyond that.

Retrieving existing webhooks

webhooks of %guild% lists every webhook of a guild, and channel webhooks of %standardguildmessagechannel% the ones of a single channel. Both ask Discord, so both require await (see cache and await), and both need Manage Webhooks.

on message received seen by "my-bot":
    if discord content of event-message is "!hooks":
        await set {_hooks::*} to channel webhooks of event-channel
        loop {_hooks::*}:
            reply with "%name of loop-value% (%webhook type of loop-value%)"

Building a client from a URL

a new webhook client from url %string% turns a webhook URL (the one Discord shows under Integrations → Webhooks → Copy Webhook URL) into a client. It needs no permission in the guild and the bot does not have to be in it: the bot only carries the HTTP requests. Without using bot, the only loaded bot is used.

options:
    hook-url: "https://discord.com/api/webhooks/123/abc"

on message received seen by "my-bot":
    if discord content of event-message is "!url-hook":
        set {_client} to a new webhook client from url {@hook-url} using bot "my-bot"
        make {_client} post "Posted through a URL"

A client built this way can post, edit and delete its own messages, nothing else: it has no name, channel or owner to read, and destroy does not accept it.

Webhook properties

A retrieved or created webhook exposes its Discord state. name, webhook avatar and webhook channel are writable and change the webhook on Discord; put await in front to wait for the change before the next line.

on message received seen by "my-bot":
    if discord content of event-message is "!rename-hooks":
        await set {_hooks::*} to channel webhooks of event-channel
        loop {_hooks::*}:
            await set name of loop-value to "Renamed"

Deleting a webhook

destroy deletes a webhook; every client built from its URL stops working at the same time.

on message received seen by "my-bot":
    if discord content of event-message is "!clear-hooks":
        await set {_hooks::*} to channel webhooks of event-channel
        loop {_hooks::*}:
            destroy loop-value

Errors you may see