REST: Webhooks
Incoming and outgoing webhooks of a channel (Owner and Administrators only). Generated from mnema-talk v3.3.13 (cca4f0fdb723).
List a channel's outgoing webhooks
GET /api/admin/channels/{id}/outgoing-webhooks
Owner or Administrator only. Secrets are never listed.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Channel ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Outgoing webhooks, oldest first. | Outgoing[] |
| 400 | Invalid input (INVALID_INPUT). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: only the Owner and members with the Administrator permission may do this. | ErrorResponse |
| 404 | NOT_FOUND: the channel does not exist or is hidden from the caller. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Create an outgoing webhook
POST /api/admin/channels/{id}/outgoing-webhooks
Owner or Administrator only. The answer carries the signing secret, shown only once. Events of that channel are POSTed to the URL as signed JSON; see doc/webhooks.md. At most 10 per channel.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Channel ID. |
Request body (application/json, required): CreateOutgoingRequest
| Field | Type | Description |
|---|---|---|
events (required) | string[] | |
name (required) | string | |
url (required) | string | URL receives the events: http or https, public addresses only unless the operator allowed more (WEBHOOK_ALLOW_PRIVATE_TARGETS). |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | Created. | CreatedOutgoing |
| 400 | Invalid input (INVALID_INPUT): bad name, URL (also: a forbidden address) or events. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the channel does not exist or is hidden from the caller. | ErrorResponse |
| 409 | CONFLICT: the maximum number of outgoing webhooks is reached. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
CreatedOutgoing
| Field | Type | Description |
|---|---|---|
channel_id (required) | string (uuid) | ChannelID is the channel the webhook belongs to; it receives that channel's events only. |
consecutive_failures (required) | integer | |
created_at (required) | string (date-time) | |
created_by (required) | string | null | CreatedBy is the administrator who created it, kept for the record (null once that account is gone). It grants nothing. |
events (required) | string[] | Events are the subscribed event types (see doc/webhooks.md). |
id (required) | string (uuid) | |
last_attempt_at (required) | string | null | |
last_error (required) | string | null | LastError is a short code for the latest failure ("timeout", "blocked_address", "http_500", ...); null after a success. |
last_status (required) | integer | null | LastStatus is the HTTP status of the latest attempt (null: none yet, or no response). |
last_success_at (required) | string | null | |
name (required) | string | |
secret (required) | string | Secret signs every delivery (see X-Mnema-Signature in doc/webhooks.md). |
status (required) | string | Status is "active", "disabled" (switched off by an administrator) or "auto_disabled" (switched off after repeated failures). |
url (required) | string | |
url_set_at (required) | string (date-time) | |
url_set_by (required) | string | null | URLSetBy and URLSetAt record who last set the URL and when, so stale webhooks are easy to spot. The URL receives the channel's events until an administrator changes or deletes the webhook. |
List a channel's webhooks
GET /api/admin/channels/{id}/webhooks
Owner or Administrator only. The tokens are never listed.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Channel ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Webhooks, oldest first. | Webhook[] |
| 400 | Invalid input (INVALID_INPUT): bad ID. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: only the Owner and members with the Administrator permission may do this. | ErrorResponse |
| 404 | NOT_FOUND: the channel does not exist or is hidden from the caller. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Create a webhook
POST /api/admin/channels/{id}/webhooks
Owner or Administrator only. The webhook belongs to the channel and posts with exactly its settings (see the allow_* fields; defaults: everyone-mentions off, the rest on), whoever holds the URL. The answer carries the secret URL; it is shown only once. At most 15 webhooks per channel.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Channel ID. |
Request body (application/json, required): CreateRequest
| Field | Type | Description |
|---|---|---|
allow_attachments | boolean | |
allow_embeds | boolean | |
allow_everyone | boolean | |
allow_identity_override | boolean | |
allow_user_mentions | boolean | |
name (required) | string |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | Created. | CreatedWebhook |
| 400 | Invalid input (INVALID_INPUT). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the channel does not exist or is hidden from the caller. | ErrorResponse |
| 409 | CONFLICT: the channel has the maximum number of webhooks. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
CreatedWebhook
| Field | Type | Description |
|---|---|---|
allow_attachments (required) | boolean | AllowAttachments lets a post carry files (default on). |
allow_embeds (required) | boolean | AllowEmbeds lets a post carry embeds (default on). |
allow_everyone (required) | boolean | AllowEveryone lets @all and @here notify people (default off). It also takes "everyone" in the sender's allowed_mentions. |
allow_identity_override (required) | boolean | AllowIdentityOverride lets a post set its own username (default on). Avatars from other hosts are never used. |
allow_user_mentions (required) | boolean | AllowUserMentions lets @username notify members (default on, as with allowed_mentions.parse = users). |
avatar_url | string | AvatarURL is the API URL of the avatar; omitted when none is set. |
channel_id (required) | string (uuid) | |
created_at (required) | string (date-time) | |
created_by (required) | string | null | CreatedBy is the administrator who created it, kept for the record (null once that account is gone). It grants nothing. |
id (required) | string (uuid) | |
name (required) | string | |
token (required) | string | Token is the secret part of the URL. It is stored hashed and cannot be shown again; regenerate the token to get a new URL. |
updated_at (required) | string (date-time) | |
url (required) | string | URL is the full execute URL, token included. |
Delete an outgoing webhook
DELETE /api/admin/outgoing-webhooks/{id}
Events still waiting to be delivered to it are dropped.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Outgoing webhook ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Deleted. | |
| 400 | Invalid input (INVALID_INPUT). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such outgoing webhook. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Change an outgoing webhook
PATCH /api/admin/outgoing-webhooks/{id}
Rename it, change its URL or events, switch it on or off. Switching it on clears an automatic switch-off. Records who set the URL and when (url_set_by, url_set_at).
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Outgoing webhook ID. |
Request body (application/json, required): UpdateOutgoingRequest
| Field | Type | Description |
|---|---|---|
enabled | boolean | |
events | string[] | |
name | string | |
url | string |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated. | Outgoing |
| 400 | Invalid input (INVALID_INPUT). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such outgoing webhook. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Outgoing
| Field | Type | Description |
|---|---|---|
channel_id (required) | string (uuid) | ChannelID is the channel the webhook belongs to; it receives that channel's events only. |
consecutive_failures (required) | integer | |
created_at (required) | string (date-time) | |
created_by (required) | string | null | CreatedBy is the administrator who created it, kept for the record (null once that account is gone). It grants nothing. |
events (required) | string[] | Events are the subscribed event types (see doc/webhooks.md). |
id (required) | string (uuid) | |
last_attempt_at (required) | string | null | |
last_error (required) | string | null | LastError is a short code for the latest failure ("timeout", "blocked_address", "http_500", ...); null after a success. |
last_status (required) | integer | null | LastStatus is the HTTP status of the latest attempt (null: none yet, or no response). |
last_success_at (required) | string | null | |
name (required) | string | |
status (required) | string | Status is "active", "disabled" (switched off by an administrator) or "auto_disabled" (switched off after repeated failures). |
url (required) | string | |
url_set_at (required) | string (date-time) | |
url_set_by (required) | string | null | URLSetBy and URLSetAt record who last set the URL and when, so stale webhooks are easy to spot. The URL receives the channel's events until an administrator changes or deletes the webhook. |
Recent deliveries of an outgoing webhook
GET /api/admin/outgoing-webhooks/{id}/deliveries
The last 50 attempts, newest first. Only status codes and short error codes are kept, never the receiver's response.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Outgoing webhook ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Attempts. | Delivery[] |
| 400 | Invalid input (INVALID_INPUT). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: only the Owner and members with the Administrator permission may do this. | ErrorResponse |
| 404 | NOT_FOUND: no such outgoing webhook. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Rotate an outgoing webhook's secret
POST /api/admin/outgoing-webhooks/{id}/secret
The old secret stops signing at once. The answer carries the new secret, shown only once. Nothing else changes.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Outgoing webhook ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | New secret. | CreatedOutgoing |
| 400 | Invalid input (INVALID_INPUT). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such outgoing webhook. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
CreatedOutgoing
| Field | Type | Description |
|---|---|---|
channel_id (required) | string (uuid) | ChannelID is the channel the webhook belongs to; it receives that channel's events only. |
consecutive_failures (required) | integer | |
created_at (required) | string (date-time) | |
created_by (required) | string | null | CreatedBy is the administrator who created it, kept for the record (null once that account is gone). It grants nothing. |
events (required) | string[] | Events are the subscribed event types (see doc/webhooks.md). |
id (required) | string (uuid) | |
last_attempt_at (required) | string | null | |
last_error (required) | string | null | LastError is a short code for the latest failure ("timeout", "blocked_address", "http_500", ...); null after a success. |
last_status (required) | integer | null | LastStatus is the HTTP status of the latest attempt (null: none yet, or no response). |
last_success_at (required) | string | null | |
name (required) | string | |
secret (required) | string | Secret signs every delivery (see X-Mnema-Signature in doc/webhooks.md). |
status (required) | string | Status is "active", "disabled" (switched off by an administrator) or "auto_disabled" (switched off after repeated failures). |
url (required) | string | |
url_set_at (required) | string (date-time) | |
url_set_by (required) | string | null | URLSetBy and URLSetAt record who last set the URL and when, so stale webhooks are easy to spot. The URL receives the channel's events until an administrator changes or deletes the webhook. |
Send a test event
POST /api/admin/outgoing-webhooks/{id}/test
Delivers a PING event once, right now, and answers with the attempt. It does not retry and does not count towards the automatic switch-off. Works while the webhook is switched off.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Outgoing webhook ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The attempt (success or the failure code). | Delivery |
| 400 | Invalid input (INVALID_INPUT). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such outgoing webhook. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Delivery
| Field | Type | Description |
|---|---|---|
attempt (required) | integer | |
created_at (required) | string (date-time) | |
duration_ms (required) | integer | |
error (required) | string | null | Error is a short code, never the response or the raw network error. |
event_id (required) | string (uuid) | |
event_type (required) | string | |
id (required) | string (uuid) | |
status_code (required) | integer | null | |
success (required) | boolean |
Delete a webhook
DELETE /api/admin/webhooks/{id}
Its URL stops working at once. Messages it posted stay.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Webhook ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Deleted. | |
| 400 | Invalid input (INVALID_INPUT). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such webhook. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Change a webhook
PATCH /api/admin/webhooks/{id}
Owner or Administrator only. Rename it and change its allow_* settings; omitted fields stay. Earlier messages keep the name they were posted under.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Webhook ID. |
Request body (application/json, required): UpdateRequest
| Field | Type | Description |
|---|---|---|
allow_attachments | boolean | |
allow_embeds | boolean | |
allow_everyone | boolean | |
allow_identity_override | boolean | |
allow_user_mentions | boolean | |
name | string |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated. | Webhook |
| 400 | Invalid input (INVALID_INPUT). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such webhook. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Webhook
| Field | Type | Description |
|---|---|---|
allow_attachments (required) | boolean | AllowAttachments lets a post carry files (default on). |
allow_embeds (required) | boolean | AllowEmbeds lets a post carry embeds (default on). |
allow_everyone (required) | boolean | AllowEveryone lets @all and @here notify people (default off). It also takes "everyone" in the sender's allowed_mentions. |
allow_identity_override (required) | boolean | AllowIdentityOverride lets a post set its own username (default on). Avatars from other hosts are never used. |
allow_user_mentions (required) | boolean | AllowUserMentions lets @username notify members (default on, as with allowed_mentions.parse = users). |
avatar_url | string | AvatarURL is the API URL of the avatar; omitted when none is set. |
channel_id (required) | string (uuid) | |
created_at (required) | string (date-time) | |
created_by (required) | string | null | CreatedBy is the administrator who created it, kept for the record (null once that account is gone). It grants nothing. |
id (required) | string (uuid) | |
name (required) | string | |
updated_at (required) | string (date-time) |
Set a webhook's avatar
POST /api/admin/webhooks/{id}/avatar
multipart/form-data with an image in field 'avatar' (max 5 MB). Replaces the previous one.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Webhook ID. |
Request body (multipart/form-data, required): object
| Field | Type | Description |
|---|---|---|
avatar (required) | string (binary) | Image file, at most 5 MB. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated. | Webhook |
| 400 | Invalid input (INVALID_INPUT). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such webhook. | ErrorResponse |
| 413 | PAYLOAD_TOO_LARGE: file exceeds the limit. | ErrorResponse |
| 415 | UNSUPPORTED_MEDIA_TYPE: the file type is not allowed. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
| 503 | UNAVAILABLE: file storage is not available. | ErrorResponse |
Webhook
| Field | Type | Description |
|---|---|---|
allow_attachments (required) | boolean | AllowAttachments lets a post carry files (default on). |
allow_embeds (required) | boolean | AllowEmbeds lets a post carry embeds (default on). |
allow_everyone (required) | boolean | AllowEveryone lets @all and @here notify people (default off). It also takes "everyone" in the sender's allowed_mentions. |
allow_identity_override (required) | boolean | AllowIdentityOverride lets a post set its own username (default on). Avatars from other hosts are never used. |
allow_user_mentions (required) | boolean | AllowUserMentions lets @username notify members (default on, as with allowed_mentions.parse = users). |
avatar_url | string | AvatarURL is the API URL of the avatar; omitted when none is set. |
channel_id (required) | string (uuid) | |
created_at (required) | string (date-time) | |
created_by (required) | string | null | CreatedBy is the administrator who created it, kept for the record (null once that account is gone). It grants nothing. |
id (required) | string (uuid) | |
name (required) | string | |
updated_at (required) | string (date-time) |
Regenerate a webhook's token
POST /api/admin/webhooks/{id}/token
The old URL stops working at once. The answer carries the new secret URL; it is shown only once. Nothing else about the webhook changes.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Webhook ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | New token and URL. | CreatedWebhook |
| 400 | Invalid input (INVALID_INPUT). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: no such webhook. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
CreatedWebhook
| Field | Type | Description |
|---|---|---|
allow_attachments (required) | boolean | AllowAttachments lets a post carry files (default on). |
allow_embeds (required) | boolean | AllowEmbeds lets a post carry embeds (default on). |
allow_everyone (required) | boolean | AllowEveryone lets @all and @here notify people (default off). It also takes "everyone" in the sender's allowed_mentions. |
allow_identity_override (required) | boolean | AllowIdentityOverride lets a post set its own username (default on). Avatars from other hosts are never used. |
allow_user_mentions (required) | boolean | AllowUserMentions lets @username notify members (default on, as with allowed_mentions.parse = users). |
avatar_url | string | AvatarURL is the API URL of the avatar; omitted when none is set. |
channel_id (required) | string (uuid) | |
created_at (required) | string (date-time) | |
created_by (required) | string | null | CreatedBy is the administrator who created it, kept for the record (null once that account is gone). It grants nothing. |
id (required) | string (uuid) | |
name (required) | string | |
token (required) | string | Token is the secret part of the URL. It is stored hashed and cannot be shown again; regenerate the token to get a new URL. |
updated_at (required) | string (date-time) | |
url (required) | string | URL is the full execute URL, token included. |
Execute a webhook
POST /api/webhooks/{id}/{token}
Posts a message into the webhook's channel as the webhook (the widely used execute format). Authenticated by the secret in the URL only: no cookie or CSRF origin is needed, and cookies are ignored. Send JSON, or multipart/form-data with the JSON in the payload_json part and up to 10 files in further parts (same size limit and type checks as member uploads). Errors are JSON with a message and a code ({"message","code"}); 429 carries retry_after. Limits: about 5 requests per 2 seconds per webhook and 30 per minute per channel. See doc/webhooks.md for what is supported and ignored.
Authentication: none
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Webhook ID. |
token | path | string | yes | Webhook token. |
wait | query | boolean | no | Answer 200 with the created message instead of 204. |
thread_id | query | string (uuid) | no | ID of a root message of the channel: the post becomes a reply in its thread. |
Request body (application/json, required): ExecutePayload
| Field | Type | Description |
|---|---|---|
allowed_mentions (required) | AllowedMentions | AllowedMentions limits who is notified. Default: members mentioned by @username are, @all and @here are not. |
avatar_url (required) | string | AvatarURL is accepted and ignored: Mnema Talk never loads pictures from other hosts. Set the avatar on the webhook instead. |
content (required) | string | Content is the message text (Markdown), at most 4000 characters. |
embeds (required) | Embed[] | Embeds are rich cards (at most 10). |
username (required) | string | Username overrides the webhook's name for this message. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The created message (wait=true). | Message |
| 204 | Posted. | |
| 400 | Invalid payload (50035) or empty message (50006). | Error |
| 401 | Invalid Webhook Token (50027). | Error |
| 404 | Unknown Webhook (10015) or unknown thread (10003). | Error |
| 413 | Request entity too large (40005). | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
| 500 | Server failure. | Error |
Message
| Field | Type | Description |
|---|---|---|
attachments (required) | MediaAttachment[] | |
avatar_url | string | |
channel_id (required) | string (uuid) | |
components | ActionRow[] | Components are the buttons and select menus of a bot's message, in action rows (doc/bots.md, Message components). Only bots set them. |
content (required) | string | |
created_at (required) | string (date-time) | |
direct_mentions | string (uuid)[] | DirectMentions are the users of Mentions this message addresses by name or through a role, not only by @all or @here: those a mute lets through. A name the sender's mention policy left as plain text is not in it. The server always sends it; it is optional so that a client can tell an older server (no field: read the text) from an empty list. |
display_name (required) | string | |
embeds | Embed[] | Embeds are the rich cards of a webhook message (a subset). |
expires_at | string (date-time) | ExpiresAt is when the server deletes the message: the end of the lifetime its sender chose (doc/timed-messages.md). Absent on a message without one. Clients hide the message at that moment on their own clock. |
forward | ForwardRef | Forward is set when the message forwards another one. It says so and nothing more: no id and no text of the original travels with the message, because readers differ in what they may see. Each reader gets the original (with its ids) from GET /api/messages/{id}/forward. |
id (required) | string (uuid) | |
is_bot | boolean | IsBot is true for messages posted by a webhook. Their author is a hidden bot account; DisplayName is the webhook's name or the username the sender gave for this message. |
is_edited (required) | boolean | |
is_locked | boolean | IsLocked marks a forum post as locked: only moderators can post replies. |
is_pinned (required) | boolean | |
is_resolved | boolean | IsResolved marks a forum post as solved or answered. |
is_webhook | boolean | IsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label). |
last_activity_at | string (date-time) | LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time. |
mention_roles | string (uuid)[] | MentionRoles are the roles this message mentions (@Role); the client draws them as role pills. A role that was deleted since drops out. The server always sends it; it is optional for clients that build messages themselves. |
mentions (required) | string (uuid)[] | Mentions are the users this message mentions (@username, @all, @here). |
nonce | string (uuid) | Nonce is the id the author's client put on this send. Only the message_create event and the reply to that send carry it, so the client can replace its pending copy; history never does. |
number (required) | integer | Number is the message's short, stable link number (/m/4821). |
parent_id | string (uuid) | |
pinned_at | string (date-time) | PinnedAt and PinnedBy say when and by whom a pinned message was pinned; both are absent on an unpinned message (PinnedBy also when the member is gone). |
pinned_by | UserRef | |
poll | Poll | Poll is set when the message is a poll; its content is the question. |
reactions (required) | ReactionSummary[] | |
reply_count (required) | integer | |
reply_to | ReplyPreview | |
reply_to_id | string (uuid) | |
tags | ForumTag[] | Tags are the forum tags attached to a forum post (up to 5 tags). |
title | string | Title is the required title of a root post in a forum channel (max 100 characters). |
updated_at (required) | string (date-time) | |
user_id (required) | string (uuid) | |
username (required) | string |