Webhook

Webhook client for sending messages via Discord webhooks

The webhook package provides a dedicated client for interacting with Discord webhooks, allowing you to send and manage messages through webhook URLs.

Installation

import "github.com/disgoorg/disgo/webhook"

Client

New

Creates a new webhook client with a webhook ID and token.

func New(id snowflake.ID, token string, opts ...ConfigOpt) *Client

id · snowflake.ID · required

The webhook ID

token · string · required

The webhook token

opts · ...ConfigOpt

Optional configuration options

NewWithURL

Creates a new webhook client by parsing a webhook URL.

func NewWithURL(webhookURL string, opts ...ConfigOpt) (*Client, error)

webhookURL · string · required

The full webhook URL from Discord

opts · ...ConfigOpt

Optional configuration options

Returns an error if the URL is invalid or cannot be parsed.

Client type

type Client struct {
    ID         snowflake.ID
    Token      string
    Rest       rest.Webhooks
    RestClient rest.Client
}

ID · snowflake.ID

The webhook’s ID

Token · string

The webhook’s token

Rest · rest.Webhooks

The REST client for webhook operations

RestClient · rest.Client

The underlying REST client

Webhook operations

URL

Returns the webhook’s URL.

func (c *Client) URL() string

GetWebhook

Retrieves webhook information.

func (c *Client) GetWebhook(opts ...rest.RequestOpt) (*discord.IncomingWebhook, error)

UpdateWebhook

Updates the webhook’s settings.

func (c *Client) UpdateWebhook(
    webhookUpdate discord.WebhookUpdateWithToken,
    opts ...rest.RequestOpt
) (*discord.IncomingWebhook, error)

webhookUpdate · discord.WebhookUpdateWithToken · required

The webhook update data

DeleteWebhook

Deletes the webhook.

func (c *Client) DeleteWebhook(opts ...rest.RequestOpt) error

Close

Closes the webhook client and underlying HTTP client.

func (c *Client) Close(ctx context.Context)

Message operations

CreateMessage

Sends a message through the webhook.

func (c *Client) CreateMessage(
    messageCreate discord.WebhookMessageCreate,
    params rest.CreateWebhookMessageParams,
    opts ...rest.RequestOpt
) (*discord.Message, error)

messageCreate · discord.WebhookMessageCreate · required

The message to create

params · rest.CreateWebhookMessageParams · required

Additional parameters for message creation

opts · ...rest.RequestOpt

Optional request options

CreateMessageInThread

Sends a message to a specific thread.

func (c *Client) CreateMessageInThread(
    messageCreate discord.WebhookMessageCreate,
    threadID snowflake.ID,
    opts ...rest.RequestOpt
) (*discord.Message, error)

messageCreate · discord.WebhookMessageCreate · required

The message to create

threadID · snowflake.ID · required

The thread ID to send the message to

CreateContent

Sends a simple text message.

func (c *Client) CreateContent(
    content string,
    opts ...rest.RequestOpt
) (*discord.Message, error)

content · string · required

The message content

CreateEmbeds

Sends a message with embeds.

func (c *Client) CreateEmbeds(
    embeds []discord.Embed,
    opts ...rest.RequestOpt
) (*discord.Message, error)

embeds · []discord.Embed · required

The embeds to send

GetMessage

Retrieves a message sent by the webhook.

func (c *Client) GetMessage(
    messageID snowflake.ID,
    opts ...rest.RequestOpt
) (*discord.Message, error)

messageID · snowflake.ID · required

The message ID to retrieve

UpdateMessage

Updates a message sent by the webhook.

func (c *Client) UpdateMessage(
    messageID snowflake.ID,
    messageUpdate discord.WebhookMessageUpdate,
    params rest.UpdateWebhookMessageParams,
    opts ...rest.RequestOpt
) (*discord.Message, error)

messageID · snowflake.ID · required

The message ID to update

messageUpdate · discord.WebhookMessageUpdate · required

The message updates to apply

params · rest.UpdateWebhookMessageParams · required

Additional parameters for the update

UpdateMessageInThread

Updates a message in a specific thread.

func (c *Client) UpdateMessageInThread(
    messageID snowflake.ID,
    messageUpdate discord.WebhookMessageUpdate,
    threadID snowflake.ID,
    opts ...rest.RequestOpt
) (*discord.Message, error)

UpdateContent

Updates a message’s text content.

func (c *Client) UpdateContent(
    messageID snowflake.ID,
    content string,
    opts ...rest.RequestOpt
) (*discord.Message, error)

messageID · snowflake.ID · required

The message ID to update

content · string · required

The new message content

UpdateEmbeds

Updates a message’s embeds.

func (c *Client) UpdateEmbeds(
    messageID snowflake.ID,
    embeds []discord.Embed,
    opts ...rest.RequestOpt
) (*discord.Message, error)

messageID · snowflake.ID · required

The message ID to update

embeds · []discord.Embed · required

The new embeds

DeleteMessage

Deletes a message sent by the webhook.

func (c *Client) DeleteMessage(
    messageID snowflake.ID,
    opts ...rest.RequestOpt
) error

messageID · snowflake.ID · required

The message ID to delete

DeleteMessageInThread

Deletes a message in a specific thread.

func (c *Client) DeleteMessageInThread(
    messageID snowflake.ID,
    threadID snowflake.ID,
    opts ...rest.RequestOpt
) error

messageID · snowflake.ID · required

The message ID to delete

threadID · snowflake.ID · required

The thread ID containing the message

Configuration

WithLogger

Sets a custom logger.

func WithLogger(logger *slog.Logger) ConfigOpt

WithRestClient

Sets a custom REST client.

func WithRestClient(restClient rest.Client) ConfigOpt

WithRestClientConfigOpts

Sets REST client configuration options.

func WithRestClientConfigOpts(opts ...rest.ClientConfigOpt) ConfigOpt

WithWebhooks

Sets a custom webhooks REST interface.

func WithWebhooks(webhooks rest.Webhooks) ConfigOpt

WithDefaultAllowedMentions

Sets default allowed mentions for all messages.

func WithDefaultAllowedMentions(allowedMentions discord.AllowedMentions) ConfigOpt

allowedMentions · discord.AllowedMentions · required

Default allowed mentions configuration

Errors

var ErrInvalidWebhookURL = errors.New("invalid webhook URL")

Returned when parsing an invalid webhook URL.

Example usage

Using webhook URL

package main

import (
    "context"
    "log"

    "github.com/disgoorg/disgo/discord"
    "github.com/disgoorg/disgo/webhook"
)

func main() {
    webhookURL := "https://discord.com/api/webhooks/123456789/abcdefgh"

    client, err := webhook.NewWithURL(webhookURL)
    if err != nil {
        log.Fatal("error creating webhook client: ", err)
    }
    defer client.Close(context.TODO())

    // Send a simple message
    _, err = client.CreateContent("Hello from DisGo!")
    if err != nil {
        log.Fatal("error sending message: ", err)
    }
}

Using ID and token

package main

import (
    "context"
    "log"

    "github.com/disgoorg/disgo/discord"
    "github.com/disgoorg/disgo/webhook"
    "github.com/disgoorg/snowflake/v2"
)

func main() {
    webhookID := snowflake.ID(123456789)
    webhookToken := "your-webhook-token"

    client := webhook.New(webhookID, webhookToken)
    defer client.Close(context.TODO())

    // Send a message with embeds
    _, err := client.CreateEmbeds([]discord.Embed{
        {
            Title:       "Example Embed",
            Description: "This is an example embed sent via webhook",
            Color:       0x5865F2,
        },
    })
    if err != nil {
        log.Fatal("error sending message: ", err)
    }
}

Updating messages

// Create a message
msg, err := client.CreateContent("Original message")
if err != nil {
    log.Fatal(err)
}

// Update the message
updatedMsg, err := client.UpdateContent(msg.ID, "Updated message")
if err != nil {
    log.Fatal(err)
}

// Delete the message
err = client.DeleteMessage(msg.ID)
if err != nil {
    log.Fatal(err)
}