Вебхуки

Вебхук

Вебхук — это адрес, через который программа пишет в один текстовый канал сообщества. Вебхук не аккаунт. Он не состоит в сообществе, не читает канал и не получает событий. Он только отправляет сообщения, а затем может изменить или удалить свои же сообщения.

В канале сообщения вебхука подписаны его именем и аватаркой и помечены меткой «ВЕБХУК». Имя и аватарку можно задать отдельно для каждого сообщения. Так один вебхук может писать, например, от имени «CI» и от имени «Мониторинг».

Как создать вебхук

Вебхуки создаются в приложении Glitch. Откройте настройки текстового канала, раздел «Интеграции», затем «Вебхуки». Там же можно изменить имя и аватарку, скопировать адрес и удалить вебхук. Для всего этого нужно право «Управлять вебхуками» в этом канале.

• Вебхук бывает только у текстового канала сообщества. В голосовом канале, личном чате и группе вебхуков нет.
• В одном канале может быть до 15 вебхуков.
• Если вебхук удалить, его сообщения останутся в канале с прежней подписью.
• Если удалить канал или сообщество, удаляются и все его вебхуки.

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

Все ручки на этой странице принимают ключ прямо в адресе. Заголовок Authorization им не нужен.

Объект вебхука

{
  "id": "1053143547551872",
  "type": 1,
  "guild_id": "1053143874904320",
  "channel_id": "1053143874918656",
  "name": "Сборка",
  "avatar": "dndlYmhvb2tzLzEwNTMxNDM1NDc1NTE4NzIvNWYyYzlhMWI3ZTNkLnBuZw…",
  "avatar_url": "https://glitch-media.s3.regru.cloud/webhooks/1053143547551872/5f2c9a1b7e3d.webp",
  "application_id": null,
  "token": "kO3rYtV0m6…xQ2Zq",
  "url": "https://api.glitchapp.online/v10/webhooks/1053143547551872/kO3rYtV0m6…xQ2Zq"
}

Получить вебхук

GET/webhooks/{webhook.id}/{webhook.token}

Возвращает объект вебхука. Этим удобно проверить при запуске программы, что адрес ещё действует и вебхук пишет в нужный канал.

curl "https://api.glitchapp.online/v10/webhooks/ID/KEY"

Изменить вебхук

PATCH/webhooks/{webhook.id}/{webhook.token}

Меняет имя и аватарку по умолчанию. Поля, которых нет в запросе, не меняются. В ответе приходит обновлённый объект вебхука.

curl -X PATCH "https://api.glitchapp.online/v10/webhooks/ID/KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"Мониторинг\", \"avatar\": \"data:image/png;base64,$(base64 -w0 logo.png)\"}"

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

Удалить вебхук

DELETE/webhooks/{webhook.id}/{webhook.token}

Удаляет вебхук. Ответ 204 без тела. После этого адрес перестаёт работать, на запросы к нему сервер отвечает 404 с кодом 10015. Уже отправленные сообщения остаются в канале.

Получить новый ключ для того же вебхука нельзя. Если адрес нужно сменить, удалите вебхук и создайте новый.

Отправить сообщение

POST/webhooks/{webhook.id}/{webhook.token}

Отправляет сообщение в канал вебхука. Тело принимается в JSON или, если есть файлы, формой multipart/form-data.

Параметры адреса

Номер сообщения нужен, чтобы потом его изменить или удалить. Если программа собирается это делать, отправляйте с wait=true.

Поля тела

В сообщении должно быть хотя бы что-то одно из текста, файла или карточки. Пустое сообщение получит отказ 50006.

Сейчас сервер не ограничивает длину текста, но держите её в пределах 2000 знаков, как в Discord. Такой предел может появиться позже, и тогда длинные сообщения начнут получать отказ.

curl -X POST "https://api.glitchapp.online/v10/webhooks/ID/KEY?wait=true" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Сервер перезапущен",
    "username": "Мониторинг",
    "avatar_url": "https://example.com/monitor.png",
    "allowed_mentions": {"parse": []}
  }'

Файлы

Файлы прикладываются формой multipart/form-data. Сами файлы передаются полями files[0], files[1] и так далее, а остальные поля передаются JSON-строкой в payload_json. Подробнее в разделе Как устроено API.

Что можно приложить к одному сообщению.

• До 10 картинок. PNG, JPEG, WebP или GIF, каждая до 20 МБ. Одна картинка покажется как фото, несколько как альбом. Тип картинки сервер определяет по её содержимому, так что заголовок Content-Type у файла может быть любым.
• Или ровно один файл любого другого типа. Он покажется как документ с именем и размером.

Картинки и другой файл смешивать в одном сообщении нельзя, такой запрос получит отказ. Весь запрос вместе с файлами должен быть не больше 30 МБ. Текст из content у сообщения с файлами становится подписью.

curl -X POST "https://api.glitchapp.online/v10/webhooks/ID/KEY" \
  -F 'payload_json={"content": "До и после"}' \
  -F "files[0]=@before.png" \
  -F "files[1]=@after.png"

Приложенную картинку можно показать внутри карточки, указав attachment://имя_файла. Тогда отдельным вложением она уже не идёт. Пример есть на странице Карточки.

Аватарка по ссылке

Картинку из avatar_url сервер скачивает сам и хранит у себя, поэтому ссылка может потом пропасть, а аватарка в канале останется. Ссылка должна вести на https:// и на картинку PNG, JPEG, WebP или GIF.

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

Получить сообщение

GET/webhooks/{webhook.id}/{webhook.token}/messages/{message.id}

Возвращает сообщение, если его отправил этот вебхук. Если сообщения нет или его отправил кто-то другой, будет 404 с кодом 10008.

Если вебхук переносили в другой канал, его старые сообщения остаются в прежнем канале, и эта ручка находит их и там.

curl "https://api.glitchapp.online/v10/webhooks/ID/KEY/messages/1053147923963904"

Изменить сообщение

PATCH/webhooks/{webhook.id}/{webhook.token}/messages/{message.id}

Меняет текст и карточки сообщения, которое отправил этот вебхук. Поля, которых нет в запросе, не меняются. В ответе приходит изменённое сообщение.

В запросе нужно хотя бы одно из полей content и embeds. Сообщение не может стать совсем пустым. Например, нельзя убрать карточки у сообщения, в котором больше ничего нет.

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

curl -X PATCH "https://api.glitchapp.online/v10/webhooks/ID/KEY/messages/1053147923963904" \
  -H "Content-Type: application/json" \
  -d '{"content": "Сборка 1.4.2 прошла", "embeds": []}'

Правка тратит тот же предел, что и отправка, см. Пределы частоты.

Удалить сообщение

DELETE/webhooks/{webhook.id}/{webhook.token}/messages/{message.id}

Удаляет сообщение, которое отправил этот вебхук. Ответ 204 без тела. Чужие сообщения вебхук удалить не может.

curl -X DELETE "https://api.glitchapp.online/v10/webhooks/ID/KEY/messages/1053147923963904"

Чего у вебхука Glitch нет

Эти параметры Discord получают отказ 50035.

• Ветки и форумы, то есть параметры thread_id, thread_name и applied_tags.
• Озвучивание сообщения, tts: true.
• Флаги сообщения flags, в том числе «тихое» сообщение без уведомлений.
• Кнопки и меню, components.
• Опросы, poll.

Полный список отличий есть на странице Отличия от Discord.