Discord webhook: кастомный аватар и имя через username и avatar_url

Как устроены имя и аватар вебхука

У каждого вебхука есть имя и аватар по умолчанию — вы задаёте их при создании в Discord (Настройки сервера → Интеграции → Вебхуки). Именно они показываются, когда в запросе ничего не сказано об отправителе.

Поверх этого любой запрос на отправку может переопределить оба параметра двумя необязательными полями JSON:

username — отображаемое имя для этого конкретного сообщения;
avatar_url — публичная https://-ссылка на картинку для этого конкретного сообщения.

Это весь механизм. Ничего не нужно регистрировать, не нужен токен бота и дополнительные права. Переопределение применяется в момент отрисовки сообщения и живёт только вместе с ним. Следующий запрос без этих полей вернётся к значениям из настроек сервера.

Зачем это нужно: один вебхук в 10:00 может выглядеть как деплой-бот, в 10:05 — как система алертов, в 10:10 — как лента релизов, и читатели канала увидят трёх разных «отправителей», хотя вебхук один. Если вебхука у вас ещё нет, начните с инструкции по созданию и возвращайтесь.

Отправка с кастомным именем и аватаром

Минимальный payload:

{
  "content": "Сборка #482 прошла на main ✅",
  "username": "CI Pipeline",
  "avatar_url": "https://example.com/avatars/ci.png"
}

Через curl:

curl -H "Content-Type: application/json" \
     -d '{
       "content": "Сборка #482 прошла на main ✅",
       "username": "CI Pipeline",
       "avatar_url": "https://example.com/avatars/ci.png"
     }' \
     https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN

Успешный запрос вернёт 204 No Content. Добавьте к URL ?wait=true, если хотите получить созданное сообщение в виде JSON: объект author в ответе содержит переопределённое имя — это быстрый способ убедиться, что override принят.

curl -s -H "Content-Type: application/json" \
     -d '{"content": "ping", "username": "CI Pipeline"}' \
     "https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN?wait=true"

Поля независимы. Отправьте только username — останется аватар по умолчанию; только avatar_url — останется имя по умолчанию. Они сочетаются со всем остальным в payload: embed, файлами, опросами, thread_name для форумов, Components V2.

Правила для username

Discord проверяет username до того, как принять сообщение:

Максимум 80 символов. Длиннее — 400 Bad Request.
Не должно содержать «clyde» и «discord». Проверка не зависит от регистра и ищет подстроку, поэтому Discord Alerts, MyDiscordBot и CLYDE одинаково получат 400, а в теле ответа будет указано поле username.
Только обычный текст. Markdown в именах не рендерится: **Deploy** покажет звёздочки как есть. Юникод-эмодзи работают, синтаксис кастомных эмодзи вроде <:name:id> — нет.
Упоминания не пингуют. Имя не разбирается как текст сообщения, поэтому синтаксис упоминаний внутри него никого не уведомит.

Пробелы, знаки препинания, кириллица — допустимы. Discord обрезает пробелы по краям и применяет свои общие правила для имён, так что если необычное имя отклонено, сверьтесь с документацией Discord для разработчиков. Выбирайте имя, которое читается даже после обрезки на узком экране телефона: короткое и конкретное лучше длинного и описательного.

Те же правила действуют и для имени вебхука по умолчанию.

Требования к картинке аватара

У avatar_url явных правил меньше, чем у username, зато больше способов молча не сработать:

Публичный HTTPS-URL. Картинку скачивают серверы Discord, поэтому localhost, адреса внутренней сети и всё, что за логином или подписанным токеном, не загрузится. Передать учётные данные никак нельзя.
Прямая ссылка на файл изображения, а не на HTML-страницу с ним. PNG, JPG и WebP — безопасный выбор; ссылка «поделиться» из облачного диска не подойдёт.
Лучше квадрат. Discord показывает аватар в круге; неквадратную картинку обрежет, так что держите объект по центру.
Стабильный URL. Ссылки на вложения Discord (cdn.discordapp.com/attachments/...) содержат истекающие параметры, и аватар, размещённый так, со временем перестанет грузиться. Держите файл там, где вы всё контролируете сами: свой домен, объектное хранилище, raw-ссылка GitHub.

Discord проверяет, что avatar_url — корректно сформированный URL, но не проверяет, что по нему действительно лежит картинка. Если ссылка недоступна или это не изображение, ошибки не будет: сообщение просто выйдет с аватаром вебхука по умолчанию. Это первое, что стоит проверить, когда кастомный аватар «не работает».

Почему GIF-аватар остаётся статичным

Анимированные аватары — фича профилей пользователей, а не вебхуков. Если передать GIF в avatar_url, Discord возьмёт один кадр и покажет его как обычную картинку. Ни флага, ни поля, ни настройки, которые бы это изменили, нет, так что не тратьте время на конвертацию форматов. Если анимация важна, положите GIF в само сообщение — как image в embed или как загруженный файл: там он будет двигаться как обычно.

Один вебхук — много отправителей

Поскольку переопределение едет вместе с каждым запросом, одного вебхука хватает на все сервисы, которые пишут в канал. Держите небольшую карту «персонажей» и подставляйте поля перед отправкой:

#!/bin/bash
WEBHOOK_URL="https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN"

send_as() {
  local sender="$1" message="$2" name avatar
  case "$sender" in
    deploy)  name="Deploy Bot";    avatar="https://example.com/avatars/deploy.png" ;;
    alerts)  name="Alerts";        avatar="https://example.com/avatars/alerts.png" ;;
    release) name="Release Notes"; avatar="https://example.com/avatars/release.png" ;;
    *)       name="System";        avatar="https://example.com/avatars/system.png" ;;
  esac

  curl -s -H "Content-Type: application/json" \
       -d "$(jq -n --arg c "$message" --arg u "$name" --arg a "$avatar" \
             '{content: $c, username: $u, avatar_url: $a}')" \
       "$WEBHOOK_URL"
}

send_as deploy  "api v2.3.1 выкачен в production 🚀"
send_as alerts  "🔴 Доля ошибок на /checkout выше 5%"
send_as release "v2.3.1 — починен таймаут оплаты, добавлен экспорт в CSV"

jq собирает JSON сам, поэтому кавычки и переносы строк в тексте не сломают payload.

Два момента, о которых стоит помнить:

Лимиты частоты — на вебхук, а не на имя. Пять «отправителей» на одном URL делят один бюджет. Если они пишут пачками, вы получите 429 и должны выдержать retry_after; практические цифры и стратегия backoff — в руководстве по rate limits.
Discord всё равно знает, что это один вебхук. Участники не могут заблокировать или заглушить одного «персонажа», в журнале аудита одна интеграция, а любой, у кого есть URL, может писать под любым именем. Если разными отправителями владеют разные команды, дайте каждой свой вебхук — тогда утечка URL затронет только одного.

Если писать JSON вручную не хочется, визуальный конструктор на discord-webhook.com позволяет ввести имя, вставить ссылку на аватар и увидеть результат до отправки, а затем экспортирует тот же payload для ваших скриптов.

Смена значений по умолчанию в настройках сервера

Когда один и тот же образ должен применяться ко всем сообщениям вебхука, поменяйте значения по умолчанию, а не переопределяйте каждый раз:

Откройте Настройки сервера → Интеграции → Вебхуки (или настройки канала → Интеграции).
Нажмите на вебхук, чтобы раскрыть его.
Измените Имя и нажмите на аватар, чтобы загрузить новую картинку.
Нажмите Сохранить изменения.

Новые значения применяются к сообщениям, отправленным с этого момента. Уже опубликованные сообщения сохраняют имя и аватар, с которыми были отправлены, а любой запрос, который по-прежнему передаёт username или avatar_url, продолжает побеждать настройки. Частый источник путаницы: имя поменяли в настройках, «не сработало», а причина — скрипт, в котором захардкожено другое.

Значения по умолчанию можно менять и программно — PATCH на сам URL вебхука с полем name и аватаром в виде image data; точный формат payload сверьте с документацией Discord для разработчиков, прежде чем на это полагаться.

Граничные случаи

Переопределения не сохраняются. Discord не запоминает последний отправленный username. Каждый запрос, которому нужен кастомный отправитель, обязан передать его заново — поэтому паттерн с картой отправителей держит значения в вашем коде, а не рассчитывает на Discord.

Редактирование не меняет отправителя. Эндпоинт редактирования (PATCH .../messages/{message_id}) принимает content, embeds, components и вложения, но username и avatar_url там игнорируются. Сообщение сохраняет того отправителя, с которым создано; чтобы «переименовать», удалите и отправьте заново.

Форумы и треды уважают переопределение. Когда thread_name создаёт пост на форуме, стартовое сообщение показывает кастомное имя и аватар. Отправка в существующий тред через ?thread_id= работает так же.

Ответ содержит итогового отправителя. С ?wait=true поле author.username в возвращённом сообщении — ваш override (или значение по умолчанию, если вы его не передали). Удобно логировать, под каким «персонажем» ушло сообщение.

У ботов иначе. Имя и аватар бота принадлежат приложению; менять их на каждое сообщение нельзя. Если нужен отправитель на уровне сообщения, вебхуки — правильный инструмент; остальные различия — в сравнении бота и вебхука.

Частые ошибки

400 Bad Request с упоминанием username. Либо имя длиннее 80 символов, либо содержит clyde или discord (в любом регистре, в любом месте строки). Переименуйте и отправьте снова.

Кастомный аватар не показывается, ошибки нет. URL недоступен публично, отдаёт HTML-страницу или требует авторизации. Откройте ссылку в приватном окне браузера: если там не отображается голая картинка, Discord её тоже не скачает.

Вчера аватар работал, сегодня пустой. Ссылка на картинку истекла или файл переехал — типично для вложений Discord и временных хранилищ. Перенесите файл на стабильный URL.

GIF-аватар не анимируется. Ожидаемое поведение, см. выше.

Поменяли имя в настройках, а сообщения приходят со старым. Скрипт передаёт username в payload. Уберите поле, чтобы использовалось значение по умолчанию.

404 с {"message":"Unknown Webhook","code":10015}. URL или токен неверный, либо вебхук удалён. Скопируйте URL заново из настроек сервера.

429 Too Many Requests. Слишком много сообщений через один вебхук за короткое время; несколько «персонажей» отдельных лимитов не получают. Подождите retry_after секунд и повторите.

Полный список кодов ответа и их смысл — в статье про ошибки вебхуков.

FAQ

Можно ли поставить вебхуку анимированный GIF-аватар?

Нет. Discord показывает аватары вебхуков статичными; GIF, переданный в avatar_url, отобразится одним кадром. Если нужна анимация, положите GIF в embed или прикрепите файлом.

Сохраняются ли username и avatar_url после отправки?

Нет. Оба поля действуют только на то сообщение, с которым отправлены. Не передадите их в следующем запросе — Discord возьмёт значения по умолчанию из настроек сервера.

Почему Discord отклоняет имя вебхука?

Имя длиннее 80 символов или содержит подстроку «clyde» либо «discord» в любом регистре. Discord Status, discordbot и Clyde2 не пройдут; Server Status пройдёт.

Можно ли поменять имя у уже отправленного сообщения?

Нет. Эндпоинт редактирования игнорирует username и avatar_url. Удалите сообщение и отправьте заново с нужным именем и аватаром.

Что дальше

Настройте имена и аватары один раз — и каждое уведомление из вебхука будет выглядеть так, будто пришло от нужного сервиса. Чтобы перебрать варианты без терминала, откройте бесплатный конструктор Discord Webhook: задайте имя и аватар, посмотрите предпросмотр и экспортируйте JSON или код.