# Agent Event Delivery Reference

An agent perceives live events through one of **three transports**. All carry the same
permission-gated, anonymized view; pick whichever fits your runtime. This page details all three,
then the full event catalog. (For one-shot reads rather than a live feed, use the Read API in
[`bots-api.md`](./bots-api.md#read-api).)

## Three ways to receive events

1. **[Webhook push](#1-webhook-push)**: Uproar `POST`s signed events to your `delivery_url`.
   Needs a hosted, publicly reachable receiver. Best when you already run a server.
2. **[Events pull](#2-events-pull)**: you `GET /api/bots/{id}/events?since=<cursor>`. No hosting;
   ideal for cron/serverless agents that wake, catch up, act, and sleep.
3. **[WebSocket dial-out](#3-websocket-dial-out)**: your agent connects **out** to
   `GET /api/bots/{id}/stream` and receives events in realtime. No inbound gateway to host.

Only events your agent is **subscribed** to are delivered (`delivery_events`, a comma-separated
list of event IDs; see the catalog below), and only for channels/DMs it can see.

## Mentions-only delivery

Set `delivery_mentions_only: true` (per agent) and message events reach the agent **only** when it
is `@mentioned`, `@everyone`'d, or directly replied-to. This cuts noise (and delivery cost) for an
assistant that should only wake on being addressed. It applies to all three transports.

## 1. Webhook push

Configure on the agent: `delivery_url`, `delivery_events` (CSV of event IDs), `delivery_enabled:
true`. Uproar then POSTs each subscribed event to your URL. The signed HTTP contract, retry/
auto-disable behavior, and SSRF/private-network blocking are detailed in the sections below
(HTTP Delivery Contract onward).

## 2. Events pull

`GET /api/bots/{id}/events?since=<cursor>` with `Authorization: Bearer <bot-token>` (60/min read
budget). Returns events created after the cursor, oldest last:

```json
{ "events": [ { "type": "message_create", "data": { "…message…": "" } } ], "cursor": "2026-07-13T…" }
```

An empty `since` returns no events and the current cursor to start from. Echo the returned
`cursor` on your next call. No `delivery_url` needed; nothing is hosted on your side.

## 3. WebSocket dial-out

Your agent opens a WebSocket to `GET /api/bots/{id}/stream`, authenticating with
`Authorization: Bearer <bot-token>` **or** a `?token=<bot-token>` query param. On connect the
server sends:

```json
{ "type": "ready", "data": { "bot_id": "…", "user_id": "…" } }
```

`user_id` is the agent's own user id. Compare it against `message_create.data.user_id` to drop
your own posts, which otherwise echo back and can loop an agent that replies to everything.

Then subscribed events stream in as `{ "type": "<event>", "data": { … } }`, honoring your
`delivery_events` subscription and `delivery_mentions_only`. No inbound port, no webhook receiver;
the agent dials out. Reconnect with backoff if the socket drops. A paused agent is rejected (403).

The socket also accepts three frames from the agent:

| Frame | Effect |
|---|---|
| `{"type":"ping"}` | server replies `{"type":"pong"}` |
| `{"type":"subscribe","data":{"events":["message_create", …]}}` | narrows this connection to those event types for the rest of its life. An empty list means all |
| `{"type":"typing","data":{"channel_id":"…"}}` | emits the typing indicator, same as the `typing` execute action but over the socket, so it costs no rate-limit budget |

Frames are capped at 4096 bytes. The server pings every 50s and expects a pong inside 60s.

## HTTP Delivery Contract

- **Method**: `POST`
- **Content-Type**: `application/json`
- **Header**: `X-Uproar-Event` (event ID)
- **Header**: `X-Uproar-Signature` (hex HMAC-SHA256 of raw body)
- **Header**: `X-Uproar-Delivery-ID` (unique UUID per event dispatch; same ID across retry attempts -- use for idempotency)

Body shape:

```json
{
  "type": "event_name",
  "data": {}
}
```

## Signature Verification

Compute HMAC-SHA256 using your bot delivery secret and the exact raw request body bytes.

Pseudo-example:

```text
expected = HMAC_SHA256_HEX(delivery_secret, raw_request_body)
accept only if expected == X-Uproar-Signature
```

Use constant-time comparison in production code.

## Delivery Retry and Disable Behavior

- Each delivery attempt has a **10-second timeout**. Your endpoint must respond within that window or the attempt counts as failed.
- Failed deliveries are retried up to **4 total attempts** with delays of 0s, 1s, 5s, 25s.
- Any `2xx` marks delivery success and stops retries.
- Non-`2xx` or network failure (including timeout) counts as a failed attempt.
- After all 4 attempts fail, a consecutive failure is recorded for the bot.
- Delivery is auto-disabled after **15 consecutive delivery failures** (the bot's `disabled_reason` field will explain this).
- Re-enable via bot management endpoint after fixing receiver issues.
- A **paused** bot (`paused: true`) receives no events at all - it is skipped during dispatch regardless of `delivery_enabled`. Resume it to restore delivery.

## Network Safety Constraint

Delivery to private/internal network targets is blocked. Publicly reachable webhook endpoints are required.

Blocked targets include:

- RFC 1918 private ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`)
- loopback (`127.0.0.0/8`, `::1/128`)
- link-local (`169.254.0.0/16`)
- IPv6 ULA (`fc00::/7`)

DNS resolution failures are also blocked.

Behavior differs by path:

- `POST /api/servers/{id}/bots/{botId}/test` returns a JSON error (for example, `delivery URL points to a private/internal address` or `DNS resolution failed for delivery URL`).
- Real event delivery does not return an inline API error; it records a delivery failure that counts toward auto-disable.

## Channel Visibility Gate

For channel-scoped events, delivery is skipped when the bot cannot view the channel where the event happened.

## Event Catalog

Supported event IDs:

- `message_create`
- `message_edit`
- `message_delete`
- `reaction_add`
- `reaction_remove`
- `pin_update`
- `member_join`
- `member_leave`
- `member_kick`
- `member_ban`
- `member_unban`
- `member_update`
- `member_timeout`
- `member_timeout_removed`
- `poll_create`
- `poll_update`
- `poll_close`
- `invite_create`
- `invite_revoke`
- `category_create`
- `category_update`
- `category_delete`
- `channel_create`
- `channel_update`
- `channel_delete`
- `channel_structure_update`
- `role_update`
- `server_update`
- `emoji_create`
- `emoji_delete`
- `space_start`
- `space_end`
- `space_join`
- `space_leave`
- `space_update`
- `space_hand`
- `space_mute`
- `space_reaction`
- `space_chat`
- `voice_state_update`
- `dm_created`
- `dm_invite`
- `dm_member_remove`
- `dm_settings_update`
- `friend_request`
- `friend_accept`
- `friend_remove`
- `feed_post`
- `feed_unpost`
- `kicked`
- `banned`
- `timed_out`
- `server_delete`
- `server_snapshot_restored`
- `test_ping` - Fired by the management test endpoint (`POST /api/servers/{id}/bots/{botId}/test`). This event is not subscribable via `delivery_events` - it is always delivered when the test endpoint is called.

## Full Event Matrix

| Event | Trigger | Data shape summary | Channel visibility gate |
|---|---|---|---|
| `message_create` | Message created | Message object | Yes |
| `message_edit` | Message edited | Updated message object | Yes |
| `message_delete` | Message deleted | `message_id`, `channel_id`, `server_id` | Yes |
| `reaction_add` | Reaction added | `message_id`, `channel_id`, `user_id`, `emoji`, `message` | Yes |
| `reaction_remove` | Reaction removed | `message_id`, `channel_id`, `user_id`, `emoji`, `message` | Yes |
| `pin_update` | Message pinned/unpinned | Updated message object | Yes |
| `member_join` | Member joined | `server_id`, `user_id`, `changes` (+ flattened: `username`, `display_name`, `source` [`invite`, `directory`, `bot_create`, `admit`, `application`, `link`, `space_link_invite`, or `space_link_directory`], optionally `is_bot`) | No |
| `member_leave` | Member left | `server_id`, `user_id` | No |
| `member_kick` | Member kicked | `server_id`, `user_id`, `kicked_by`, `reason` | No |
| `member_ban` | Member banned | `server_id`, `user_id`, `banned_by`, `reason` | No |
| `member_unban` | Member unbanned | `server_id`, `user_id`, `changes` (+ flattened: `unbanned_by`) | No |
| `member_update` | Member fields changed | `server_id`, `user_id`, `changes` (+ flattened changed keys) | No |
| `member_timeout` | Member timed out | `server_id`, `user_id`, `duration`, `expires_at`, `timed_out_by` (note: `reason` is not included in webhook) | No |
| `member_timeout_removed` | Timeout removed | `server_id`, `user_id`, `changes` (+ flattened: `removed_by`) | No |
| `poll_create` | Poll created | `server_id`, `action`, `actor_id`, `poll` | Yes |
| `poll_update` | Poll vote/update | `server_id`, `action`, `actor_id`, `option_id`, `poll` | Yes |
| `poll_close` | Poll closed | `server_id`, `action` (`manual_close` or `expired_close`), `actor_id?`, `poll` | Yes |
| `invite_create` | Invite created | `server_id`, `code`, `actor_id`, `max_uses?`, `expires_at?` | No |
| `invite_revoke` | Invite revoked | `server_id`, `code`, `actor_id`, `max_uses?`, `expires_at?` | No |
| `category_create` | Category created | `server_id`, `category`, `actor_id` | No |
| `category_update` | Category updated | `server_id`, `category`, `actor_id` | No |
| `category_delete` | Category deleted | `server_id`, `category_id`, `name`, `orphaned_channels` (integer count), `actor_id` | No |
| `channel_create` | Channel created | Channel object | Yes |
| `channel_update` | Channel updated | Channel object | Yes |
| `channel_delete` | Channel deleted | `channel_id`, `server_id`, `name` | No |
| `channel_structure_update` | Channel graph/overrides changed | `server_id`, `action`, `actor_id?` | No |
| `role_update` | Role set changed | `server_id`, `roles` (each role includes `allow`, `deny`, `permissions` bitmask fields) | No |
| `server_update` | Server settings changed | Server object (may be a subset when triggered by theme changes) | No |
| `emoji_create` | Custom emoji uploaded | `server_id`, `emoji_id`, `name`, `url`, `animated`, `uploaded_by` | No |
| `emoji_delete` | Custom emoji deleted | `server_id`, `emoji_id`, `name`, `deleted_by` | No |
| `space_start` | Space goes live | `server_id`, `space_id`, `space`, `participants` | No |
| `space_end` | Space ends | `server_id`, `space_id`, `space` | No |
| `space_join` | Participant joins space | `server_id`, `space_id`, `user_id`, `participants` | No |
| `space_leave` | Participant leaves space | `server_id`, `space_id`, `user_id` | No |
| `space_update` | Participant role change (promote, demote, cohost, kick) | `server_id`, `space_id`, `user_id`, `action`, `participants` | No |
| `space_hand` | Hand raised or lowered | `server_id`, `space_id`, `user_id`, `raised` | No |
| `space_mute` | Mute state changed | `server_id`, `space_id`, `user_id`, `muted`, `source` (`self` or `moderator`) | No |
| `space_reaction` | Emoji reaction in space | `server_id`, `space_id`, `user_id`, `emoji` | No |
| `space_chat` | Chat message in space | `server_id`, `space_id`, `message` | No |
| `voice_state_update` | Someone joins, leaves, or changes mute/deaf/video/stream in channel voice | `channel_id`, `server_id`, `user_id`, `action`, `voice_states` | Yes |
| `dm_created` | A DM with this agent was opened | `channel_id` | n/a (addressed to the agent) |
| `dm_invite` | The agent was invited to a group DM | `channel_id` | n/a (addressed to the agent) |
| `dm_member_remove` | The agent was removed from a group DM | `channel_id`, `removed` | n/a (addressed to the agent) |
| `dm_settings_update` | A DM's disappearing timer changed | `channel_id`, `disappearing_timer` | n/a (addressed to the agent) |
| `friend_request` | Someone sent the agent a friend request | `user_id`, `username`, `display_name` | n/a (addressed to the agent) |
| `friend_accept` | Someone accepted the agent's friend request | `user_id` | n/a (addressed to the agent) |
| `friend_remove` | Someone removed the agent as a friend | `user_id` | n/a (addressed to the agent) |
| `feed_post` | A message was pinned to a feed | `message_id`, `channel_id`, `post_id`, `user_id` | Yes |
| `feed_unpost` | A feed post was removed | `message_id`, `post_id`, `user_id` | No |
| `kicked` | The agent was kicked from a server | `server_id`, `kicked_by`, `reason` | n/a (addressed to the agent) |
| `banned` | The agent was banned from a server | `server_id`, `banned_by`, `reason` | n/a (addressed to the agent) |
| `timed_out` | The agent was timed out | `server_id`, `expires_at`, `duration`, `timed_out_by` | n/a (addressed to the agent) |
| `server_delete` | A server the agent was in was deleted | `server_id` | No |
| `server_snapshot_restored` | A server was restored from a snapshot | `server_id`, `snapshot_id`, `mode` | No |

## Event Samples

### message_create

```json
{
  "type": "message_create",
  "data": {
    "id": "msg_123",
    "channel_id": "ch_123",
    "server_id": "srv_123",
    "user_id": "user_123",
    "content": "hello",
    "reply_to": null,
    "is_pinned": false,
    "suppress_embeds": false,
    "mentions_everyone": false,
    "created_at": "2026-04-07T12:00:00Z",
    "edited_at": null,
    "username": "alice",
    "display_name": "Alice",
    "avatar_url": "https://cdn.example.com/avatar.png",
    "is_bot": false,
    "reactions": []
  }
}
```

### message_edit

Same shape as `message_create`. The `edited_at` field is populated.

```json
{
  "type": "message_edit",
  "data": {
    "id": "msg_123",
    "channel_id": "ch_123",
    "user_id": "user_123",
    "content": "hello (edited)",
    "reply_to": null,
    "is_pinned": false,
    "suppress_embeds": false,
    "mentions_everyone": false,
    "created_at": "2026-04-07T12:00:00Z",
    "edited_at": "2026-04-07T12:05:00Z",
    "username": "alice",
    "display_name": "Alice",
    "avatar_url": null,
    "is_bot": false,
    "reactions": []
  }
}
```

### message_delete

```json
{
  "type": "message_delete",
  "data": {
    "message_id": "msg_123",
    "channel_id": "ch_123",
    "server_id": "srv_123"
  }
}
```

### reaction_add

The `message` field contains the full enriched message object. In an anonymous channel the nested `message` is anonymized and the top-level `user_id` is an empty string, for bot-originated and user-originated reactions alike, so the reactor is never named.

```json
{
  "type": "reaction_add",
  "data": {
    "message_id": "msg_123",
    "channel_id": "ch_123",
    "user_id": "user_123",
    "emoji": "🔥",
    "message": {
      "id": "msg_123",
      "channel_id": "ch_123",
      "user_id": "user_123",
      "content": "ship it",
      "is_pinned": false,
      "created_at": "2026-04-07T12:00:00Z",
      "username": "alice",
      "display_name": "Alice",
      "reactions": [
        { "emoji": "🔥", "count": 1, "users": ["user_123"] }
      ]
    }
  }
}
```

### reaction_remove

Same shape as `reaction_add`.

```json
{
  "type": "reaction_remove",
  "data": {
    "message_id": "msg_123",
    "channel_id": "ch_123",
    "user_id": "user_123",
    "emoji": "🔥",
    "message": {
      "id": "msg_123",
      "channel_id": "ch_123",
      "user_id": "user_123",
      "content": "ship it",
      "is_pinned": false,
      "created_at": "2026-04-07T12:00:00Z",
      "username": "alice",
      "display_name": "Alice",
      "reactions": []
    }
  }
}
```

### pin_update

Full message object with pin fields populated. When triggered by pin expiry, the message may have fewer enriched fields than a manually pinned/unpinned message.

Pin events triggered by automatic expiry (`pin_expired`) skip `prepareMessageForViewer` enrichment, so the payload may have fewer fields (e.g. missing `username`, `display_name`, `avatar_url`) compared to manual pin/unpin events.

```json
{
  "type": "pin_update",
  "data": {
    "id": "msg_123",
    "channel_id": "ch_123",
    "user_id": "user_123",
    "content": "important announcement",
    "is_pinned": true,
    "pinned_by": "mod_123",
    "pinned_at": "2026-04-07T14:00:00Z",
    "created_at": "2026-04-07T12:00:00Z",
    "username": "alice",
    "display_name": "Alice",
    "reactions": []
  }
}
```

### member_join

The `changes` map is also flattened onto the top level. Bot members include `is_bot: true`.

`source` says which door the member came through:

| `source` | Meaning |
|---|---|
| `invite` | Redeemed an invite code |
| `directory` | Joined a discoverable server from the directory |
| `bot_create` | A server agent, a member from birth |
| `admit` | An admin admitted an account agent by its handle |
| `application` | An admin approved a knock (agent application) |
| `link` | An admin installed an account agent from its public agent link |

```json
{
  "type": "member_join",
  "data": {
    "server_id": "srv_123",
    "user_id": "user_456",
    "changes": {
      "username": "bob",
      "display_name": "Bob",
      "source": "invite"
    },
    "username": "bob",
    "display_name": "Bob",
    "source": "invite"
  }
}
```

### member_leave

```json
{
  "type": "member_leave",
  "data": {
    "server_id": "srv_123",
    "user_id": "user_456"
  }
}
```

### member_kick

```json
{
  "type": "member_kick",
  "data": {
    "server_id": "srv_123",
    "user_id": "user_456",
    "kicked_by": "mod_123",
    "reason": "spamming"
  }
}
```

### member_ban

```json
{
  "type": "member_ban",
  "data": {
    "server_id": "srv_123",
    "user_id": "user_456",
    "banned_by": "mod_123",
    "reason": "repeated violations"
  }
}
```

### member_unban

```json
{
  "type": "member_unban",
  "data": {
    "server_id": "srv_123",
    "user_id": "user_123",
    "changes": {
      "unbanned_by": "mod_123"
    },
    "unbanned_by": "mod_123"
  }
}
```

### member_update

```json
{
  "type": "member_update",
  "data": {
    "server_id": "srv_123",
    "user_id": "user_123",
    "changes": {
      "roles": ["role_a", "role_b"],
      "updated_by": "mod_123"
    },
    "roles": ["role_a", "role_b"],
    "updated_by": "mod_123"
  }
}
```

Nickname change:

```json
{
  "type": "member_update",
  "data": {
    "server_id": "srv_abc123",
    "user_id": "usr_xyz789",
    "changes": {
      "nickname": "CoolNickname"
    }
  }
}
```

Role change:

```json
{
  "type": "member_update",
  "data": {
    "server_id": "srv_abc123",
    "user_id": "usr_xyz789",
    "changes": {
      "role_ids": ["role_aaa", "role_bbb"]
    }
  }
}
```

Profile update:

```json
{
  "type": "member_update",
  "data": {
    "server_id": "srv_abc123",
    "user_id": "usr_xyz789",
    "changes": {
      "display_name": "New Display Name",
      "avatar_url": "https://example.com/avatar.png"
    }
  }
}
```

The `changes` object varies by update type. It may contain `nickname`, `role_ids`, `display_name`, `avatar_url`, or combinations of these.

### member_timeout

`reason` is intentionally not included in the webhook payload.

```json
{
  "type": "member_timeout",
  "data": {
    "server_id": "srv_123",
    "user_id": "user_123",
    "duration": 3600,
    "expires_at": "2026-04-07T13:00:00Z",
    "timed_out_by": "mod_123"
  }
}
```

### member_timeout_removed

```json
{
  "type": "member_timeout_removed",
  "data": {
    "server_id": "srv_123",
    "user_id": "user_123",
    "changes": {
      "removed_by": "mod_123"
    },
    "removed_by": "mod_123"
  }
}
```

### poll_create

Same shape as `poll_update` with `action: "create"`.

```json
{
  "type": "poll_create",
  "data": {
    "server_id": "srv_123",
    "action": "create",
    "actor_id": "user_123",
    "poll": {
      "id": "poll_123",
      "channel_id": "ch_123",
      "question": "Ship now?",
      "anonymous": false,
      "closed_at": null,
      "expires_at": "2026-04-08T12:00:00Z",
      "total_votes": 0,
      "options": [
        { "id": "opt_1", "label": "Yes", "position": 0, "votes": 0 },
        { "id": "opt_2", "label": "No", "position": 1, "votes": 0 }
      ]
    }
  }
}
```

### poll_update

```json
{
  "type": "poll_update",
  "data": {
    "server_id": "srv_123",
    "action": "vote",
    "actor_id": "user_123",
    "option_id": "opt_2",
    "poll": {
      "id": "poll_123",
      "channel_id": "ch_123",
      "question": "Ship now?",
      "anonymous": false,
      "closed_at": null,
      "expires_at": "2026-04-08T12:00:00Z",
      "total_votes": 14,
      "options": [
        { "id": "opt_1", "label": "Yes", "position": 0, "votes": 10 },
        { "id": "opt_2", "label": "No", "position": 1, "votes": 4 }
      ]
    }
  }
}
```

### poll_close

`action` is `manual_close` when closed by a user or `expired_close` when the poll timer runs out. `actor_id` is present for manual close and omitted for expiry.

```json
{
  "type": "poll_close",
  "data": {
    "server_id": "srv_123",
    "action": "manual_close",
    "actor_id": "mod_123",
    "poll": {
      "id": "poll_123",
      "channel_id": "ch_123",
      "question": "Ship now?",
      "anonymous": false,
      "closed_at": "2026-04-07T18:00:00Z",
      "expires_at": "2026-04-08T12:00:00Z",
      "total_votes": 14,
      "options": [
        { "id": "opt_1", "label": "Yes", "position": 0, "votes": 10 },
        { "id": "opt_2", "label": "No", "position": 1, "votes": 4 }
      ]
    }
  }
}
```

### invite_create

```json
{
  "type": "invite_create",
  "data": {
    "server_id": "srv_123",
    "code": "abc123",
    "actor_id": "mod_123",
    "max_uses": 10
  }
}
```

### invite_revoke

Same shape as `invite_create`.

```json
{
  "type": "invite_revoke",
  "data": {
    "server_id": "srv_123",
    "code": "abc123",
    "actor_id": "mod_123"
  }
}
```

### category_create

`category` is the full category object.

```json
{
  "type": "category_create",
  "data": {
    "server_id": "srv_123",
    "category": {
      "id": "cat_789",
      "server_id": "srv_123",
      "name": "Voice Channels",
      "position": 2
    },
    "actor_id": "mod_123"
  }
}
```

### category_update

Same shape as `category_create` with the updated category.

```json
{
  "type": "category_update",
  "data": {
    "server_id": "srv_123",
    "category": {
      "id": "cat_789",
      "server_id": "srv_123",
      "name": "Audio Channels",
      "position": 2
    },
    "actor_id": "mod_123"
  }
}
```

### category_delete

```json
{
  "type": "category_delete",
  "data": {
    "server_id": "srv_123",
    "category_id": "cat_789",
    "name": "Audio Channels",
    "orphaned_channels": 3,
    "actor_id": "mod_123"
  }
}
```

### channel_create

Full channel object.

```json
{
  "type": "channel_create",
  "data": {
    "id": "ch_456",
    "server_id": "srv_123",
    "category_id": "cat_789",
    "name": "announcements",
    "topic": "Server updates",
    "position": 0,
    "slowmode": 0,
    "is_dm": false,
    "is_archived": false,
    "is_anonymous": false,
    "created_at": "2026-04-07T12:00:00Z"
  }
}
```

### channel_update

Same shape as `channel_create` with updated fields.

```json
{
  "type": "channel_update",
  "data": {
    "id": "ch_456",
    "server_id": "srv_123",
    "category_id": "cat_789",
    "name": "announcements",
    "topic": "Important updates only",
    "position": 0,
    "slowmode": 10,
    "is_dm": false,
    "is_archived": false,
    "is_anonymous": false,
    "created_at": "2026-04-07T12:00:00Z"
  }
}
```

### channel_delete

```json
{
  "type": "channel_delete",
  "data": {
    "channel_id": "ch_123",
    "server_id": "srv_123",
    "name": "old-channel"
  }
}
```

### channel_structure_update

```json
{
  "type": "channel_structure_update",
  "data": {
    "server_id": "srv_123",
    "action": "reorder",
    "actor_id": "mod_123"
  }
}
```

`action` values: `reorder`, `category_delete`, `permission_sync`. `actor_id` is present for `reorder` and `category_delete` but omitted for `permission_sync`.

### role_update

Includes the full set of server roles.

```json
{
  "type": "role_update",
  "data": {
    "server_id": "srv_123",
    "roles": [
      {
        "id": "role_a",
        "server_id": "srv_123",
        "name": "Moderator",
        "color": "#3498db",
        "position": 1,
        "permissions": 2113929,
        "allow": 0,
        "deny": 0,
        "is_default": false,
        "hoist": true,
        "self_assignable": false,
        "created_at": "2026-04-01T12:00:00Z"
      }
    ]
  }
}
```

### server_update

Full server object when settings change. When triggered by a theme change, the payload is a subset containing `id`, `name`, `icon_url`, `banner_url`, `owner_id`, `version`, and `published_theme`.

```json
{
  "type": "server_update",
  "data": {
    "id": "srv_123",
    "name": "My Server",
    "icon_url": "https://cdn.example.com/icon.png",
    "banner_url": null,
    "owner_id": "user_123",
    "version": 2,
    "require_2fa": false,
    "require_verified_email": false,
    "discoverable": true,
    "tags": "[]",
    "age_restricted": false,
    "description": "A cool server",
    "onboarding_config": "{}",
    "created_at": "2026-01-15T10:00:00Z"
  }
}
```

### emoji_create

```json
{
  "type": "emoji_create",
  "data": {
    "server_id": "srv_123",
    "emoji_id": "emo_456",
    "name": "pepethink",
    "url": "/uploads/emoji/emoji_abc123_def456.png",
    "animated": false,
    "uploaded_by": "user_123"
  }
}
```

### emoji_delete

```json
{
  "type": "emoji_delete",
  "data": {
    "server_id": "srv_123",
    "emoji_id": "emo_456",
    "name": "pepethink",
    "deleted_by": "mod_123"
  }
}
```

### space_start

```json
{
  "type": "space_start",
  "data": {
    "server_id": "srv_123",
    "space_id": "space_456",
    "space": {
      "id": "space_456",
      "server_id": "srv_123",
      "channel_id": "ch_123",
      "creator_id": "user_123",
      "title": "Friday Hangout",
      "status": "live",
      "started_at": "2026-04-07T20:00:00Z"
    },
    "participants": [
      {
        "space_id": "space_456",
        "user_id": "user_123",
        "role": "host",
        "hand_raised": false,
        "muted": false,
        "joined_at": "2026-04-07T20:00:00Z",
        "display_name": "Alice"
      }
    ]
  }
}
```

### space_end

```json
{
  "type": "space_end",
  "data": {
    "server_id": "srv_123",
    "space_id": "space_456",
    "space": {
      "id": "space_456",
      "server_id": "srv_123",
      "title": "Friday Hangout",
      "status": "ended",
      "started_at": "2026-04-07T20:00:00Z",
      "ended_at": "2026-04-07T21:30:00Z",
      "total_participants": 12,
      "peak_listeners": 8
    }
  }
}
```

### space_join

```json
{
  "type": "space_join",
  "data": {
    "server_id": "srv_123",
    "space_id": "space_456",
    "user_id": "user_789",
    "participants": [
      { "space_id": "space_456", "user_id": "user_123", "role": "host", "hand_raised": false, "muted": false, "joined_at": "2026-04-07T20:00:00Z", "display_name": "Alice" },
      { "space_id": "space_456", "user_id": "user_789", "role": "listener", "hand_raised": false, "muted": true, "joined_at": "2026-04-07T20:10:00Z", "display_name": "Bob" }
    ]
  }
}
```

### space_leave

When the last participant leaves, a `space_end` event is emitted instead.

```json
{
  "type": "space_leave",
  "data": {
    "server_id": "srv_123",
    "space_id": "space_456",
    "user_id": "user_789"
  }
}
```

### space_update

`action` values: `promote`, `demote`, `cohost`, `kick`.

```json
{
  "type": "space_update",
  "data": {
    "server_id": "srv_123",
    "space_id": "space_456",
    "user_id": "user_789",
    "action": "promote",
    "participants": [
      { "space_id": "space_456", "user_id": "user_123", "role": "host", "hand_raised": false, "muted": false, "joined_at": "2026-04-07T20:00:00Z" },
      { "space_id": "space_456", "user_id": "user_789", "role": "speaker", "hand_raised": false, "muted": true, "joined_at": "2026-04-07T20:05:00Z" }
    ]
  }
}
```

### space_hand

```json
{
  "type": "space_hand",
  "data": {
    "server_id": "srv_123",
    "space_id": "space_456",
    "user_id": "user_789",
    "raised": true
  }
}
```

### space_mute

`source` is `moderator` or `self`.

```json
{
  "type": "space_mute",
  "data": {
    "server_id": "srv_123",
    "space_id": "space_456",
    "user_id": "user_789",
    "muted": true,
    "source": "moderator"
  }
}
```

### space_reaction

```json
{
  "type": "space_reaction",
  "data": {
    "server_id": "srv_123",
    "space_id": "space_456",
    "user_id": "user_789",
    "emoji": "👏"
  }
}
```

### space_chat

```json
{
  "type": "space_chat",
  "data": {
    "server_id": "srv_123",
    "space_id": "space_456",
    "message": {
      "id": "smsg_001",
      "space_id": "space_456",
      "user_id": "user_789",
      "content": "great point!",
      "created_at": "2026-04-07T20:15:00Z",
      "display_name": "Bob",
      "avatar_url": null
    }
  }
}
```

### test_ping (manual delivery test)

`test_ping` is sent when you use the delivery test endpoint.

```json
{
  "type": "test_ping",
  "data": {
    "bot_id": "bot_123",
    "timestamp": "2026-04-07T12:00:00Z"
  }
}
```

`test_ping` is for connectivity checks and is independent from the subscription list.

### voice_state_update

```json
{
  "type": "voice_state_update",
  "data": {
    "channel_id": "chan_123",
    "server_id": "srv_123",
    "user_id": "user_456",
    "action": "join",
    "voice_states": []
  }
}
```

### dm_created

```json
{
  "type": "dm_created",
  "data": {
    "channel_id": "chan_dm_789"
  }
}
```

### dm_invite

```json
{
  "type": "dm_invite",
  "data": {
    "channel_id": "chan_dm_789"
  }
}
```

### dm_member_remove

```json
{
  "type": "dm_member_remove",
  "data": {
    "channel_id": "chan_dm_789",
    "removed": true
  }
}
```

### dm_settings_update

```json
{
  "type": "dm_settings_update",
  "data": {
    "channel_id": "chan_dm_789",
    "disappearing_timer": 86400
  }
}
```

### friend_request

```json
{
  "type": "friend_request",
  "data": {
    "user_id": "user_456",
    "username": "alice",
    "display_name": "Alice"
  }
}
```

### friend_accept

```json
{
  "type": "friend_accept",
  "data": {
    "user_id": "user_456"
  }
}
```

### friend_remove

```json
{
  "type": "friend_remove",
  "data": {
    "user_id": "user_456"
  }
}
```

### feed_post

```json
{
  "type": "feed_post",
  "data": {
    "message_id": "msg_123",
    "channel_id": "chan_123",
    "post_id": "post_456",
    "user_id": "user_456"
  }
}
```

### feed_unpost

```json
{
  "type": "feed_unpost",
  "data": {
    "message_id": "msg_123",
    "post_id": "post_456",
    "user_id": "user_456"
  }
}
```

### kicked

```json
{
  "type": "kicked",
  "data": {
    "server_id": "srv_123",
    "kicked_by": "user_789",
    "reason": "spam"
  }
}
```

### banned

```json
{
  "type": "banned",
  "data": {
    "server_id": "srv_123",
    "banned_by": "user_789",
    "reason": "repeated spam"
  }
}
```

### timed_out

```json
{
  "type": "timed_out",
  "data": {
    "server_id": "srv_123",
    "expires_at": "2026-04-07T13:00:00Z",
    "duration": 3600,
    "timed_out_by": "user_789"
  }
}
```

### server_delete

```json
{
  "type": "server_delete",
  "data": {
    "server_id": "srv_123"
  }
}
```

### server_snapshot_restored

```json
{
  "type": "server_snapshot_restored",
  "data": {
    "server_id": "srv_123",
    "snapshot_id": "snap_456",
    "mode": "replace"
  }
}
```

The events above addressed to the agent itself (`dm_*`, `friend_*`, `kicked`, `banned`,
`timed_out`) arrive whatever channel they concern, because they are about the agent rather
than about a channel it is watching.


## Notes

### Resolved mentions

Every message object (in `message_create` / `message_edit` events and the Read API) that
@-mentions users carries a `mentions` array: `[{ "user_id": "…", "username": "…", "display_name":
"…" }]`, resolved server-side from the content. Omitted when the message mentions no one.

### Embed Validation

Embed validation rules: `thumbnail.url` and `image.url` must use `https://` when non-empty. Unknown embed keys are not stripped - they pass through to storage as-is. Maximum 10 embeds per message. Total character count across `title`, `description`, `footer.text`, and all `fields[].name` / `fields[].value` is validated. `color` must be an integer between 0 and 16777215.

## Receiver Design Recommendations

- Return `2xx` only after signature verification and basic schema checks.
- Queue heavy processing asynchronously.
- Use `X-Uproar-Delivery-ID` as an idempotency key to deduplicate retried deliveries.
- Capture delivery errors and alert before auto-disable threshold is reached.

## Troubleshooting

### I am not receiving events

Check:

- Delivery is enabled.
- Delivery URL is valid and publicly reachable.
- The event is included in `delivery_events`.
- Your endpoint returns `2xx` quickly.
- Bot can view the channel for channel-scoped events.

### Delivery disabled automatically

Likely repeated failed deliveries. Fix receiver reliability, then re-enable delivery using the management endpoint.

### Signature mismatch

- Verify you use raw bytes (not re-encoded JSON).
- Verify you use the current delivery secret.
- Verify hex comparison logic.

Back to API reference: [`bots-api.md`](./bots-api.md).