Discordit

Send Discord messages through an incoming webhook. Use it as a library or as the discordit command. A successful post returns when Discord answers HTTP 204.

Install

Requires Python 3.13 or newer, and a Discord incoming webhook URL you are allowed to post to.

pip install lupaxa-discordit
discordit --help

Put the webhook URL in the environment, or in a profile, rather than in shell history.

CLI

discordit --webhook "$DISCORD_WEBHOOK_URL" --text "Hello"
discordit --profile testing --text "Hello"
discordit -p alerts --config "$HOME/work/discordit.yml" --text "Disk full"
discordit --webhook "$DISCORD_WEBHOOK_URL" --file report.txt --text "see attached"
discordit --webhook "$DISCORD_WEBHOOK_URL" --embed '{"title":"Hi"}' --tts
discordit --webhook "$DISCORD_WEBHOOK_URL" --thread-name Incident --text started
discordit --webhook "$DISCORD_WEBHOOK_URL" --allowed-mentions '{"parse":[]}' --text "no pings"
discordit --profile testing --validate
python -m lupaxa.discordit --version

The webhook URL must use Discord's /api/webhooks/ path. Pass --webhook, or --profile with a webhook_url in the config file.

--text, --embed, and --file may be combined. --validate cannot be combined with them. One of those four is required. Flags override the same fields from the selected profile. --timeout must be greater than 0.

Escaped newlines in --text are sent as real line breaks, so Hello\\nthere arrives as two lines. Content longer than 2000 characters is an error. --validate probes the webhook, then posts This is a validation message plus username and avatar when those are set. It does not send text-to-speech, a thread name, or allowed mentions.

Config

Profiles live in $HOME/.discordit.yml. Pass --config to use another file. --config requires --profile.

profiles:
  testing:
    webhook_url: https://discord.com/api/webhooks/WEBHOOK_ID/WEBHOOK_TOKEN
    username: PyBot
    avatar_url: https://example.com/avatar.png
    tts: false
    thread_name: Alerts
    allowed_mentions:
      parse: []
    timeout: 15

The file must contain a profiles mapping. Unknown keys are rejected.

Library

from lupaxa.discordit import Discordit, load_profile

profile = load_profile("testing")
client = Discordit(
    profile.webhook_url,
    username=profile.username,
    avatar_url=profile.avatar_url,
    tts=profile.tts or False,
    thread_name=profile.thread_name,
    allowed_mentions=profile.allowed_mentions,
    timeout=profile.timeout or 10.0,
)
client.send_message("Hello from a profile")
client.send_embed('{"title": "Hello"}')
client.send_file("report.txt", content="see attached")
client.validate()

send is an alias of send_message. Username, avatar URL, text-to-speech, thread name, and allowed mentions are added when you set them and the payload does not already include that field. send_payload posts a JSON object, with an optional file. A Discord HTTP 204 response returns True.

load_profile reads $HOME/.discordit.yml when no path is given. A missing file, unknown profile, or invalid YAML raises ConfigError. validate returns False when the probe does not succeed.

Exit codes

Development

make init
make python-install-dev
make python-check