> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ollim.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Embeds and buttons

> Send structured information through Discord embeds with interactive buttons and inquiry actions.

The agent communicates structured information — task lists, calendar events, email digests, status updates — through Discord embeds. Each embed can include interactive buttons that trigger actions directly or route prompts back to the agent. Buttons survive bot restarts, so you can click them any time.

## Overview

The agent decides when and what to send — you don't create embeds manually. Buttons either perform a direct operation (complete a task, delete an event) or open a conversation with the agent through the inquiry system.

Embeds sent from [background forks](/scheduling/background-forks) or [interactive forks](/core-usage/forks) are tagged with a footer indicating their source.

## What embeds include

Each embed has a title and can include body text, a color-coded accent bar, structured fields, and up to five interactive buttons.

<Accordion title="Developer reference: discord_embed parameters">
  | Parameter     | Type    | Required | Default  | Description                                                                                            |
  | ------------- | ------- | -------- | -------- | ------------------------------------------------------------------------------------------------------ |
  | `title`       | string  | Yes      | —        | Embed heading                                                                                          |
  | `description` | string  | No       | —        | Body text below the title                                                                              |
  | `color`       | string  | No       | `"blue"` | Embed accent color                                                                                     |
  | `fields`      | array   | No       | `[]`     | Structured name/value pairs                                                                            |
  | `buttons`     | array   | No       | `[]`     | Interactive buttons attached below the embed                                                           |
  | `critical`    | boolean | No       | `false`  | Bypasses per-session limit, busy check, and [ping budget](/scheduling/ping-budget) in background forks |
</Accordion>

### Colors

| Value    | Meaning                                  |
| -------- | ---------------------------------------- |
| `blue`   | Informational (default)                  |
| `green`  | Success / completion                     |
| `red`    | Urgent / error                           |
| `yellow` | Warning                                  |
| `purple` | Accent — also used for fork entry embeds |

### Fields

Fields render as labeled sections within the embed — inline fields appear side-by-side, non-inline fields stack vertically.

### Buttons

Each button has a label and an optional style (defaults to grey).

| Style       | Appearance               |
| ----------- | ------------------------ |
| `primary`   | Blurple (Discord accent) |
| `secondary` | Grey                     |
| `success`   | Green                    |
| `danger`    | Red                      |

Embeds can have up to **5 buttons**. Buttons that delete the embed message are labeled "Close".

## Button actions

Buttons fall into two categories: direct actions that execute immediately, and inquiry buttons that route a prompt back through the agent.

<Tabs>
  <Tab title="Direct actions">
    Direct actions perform a single operation and respond with a temporary message only you can see. No agent involvement. If something goes wrong (for example, a Google API error), the error reason is shown the same way.

    | Button        | What it does                       |
    | ------------- | ---------------------------------- |
    | Mark complete | Marks a Google Tasks item complete |
    | Delete task   | Deletes a Google Tasks item        |
    | Delete event  | Deletes a Google Calendar event    |
    | Close         | Deletes the embed message          |
  </Tab>

  <Tab title="Inquiry buttons">
    Inquiry buttons store a prompt and route it back through the agent when clicked. If the button was sent by a background fork, clicking it opens an [interactive fork](/core-usage/forks) that resumes that session; otherwise the prompt is processed in your current session.
  </Tab>
</Tabs>

<Accordion title="Developer reference: action string formats">
  Button behavior is determined by an `action` string encoded in the button. Direct actions use patterns like `task_done:<task_id>`, `task_del:<task_id>`, `event_del:<event_id>`, and `dismiss`. Inquiry buttons use the format `agent:<prompt>`, where `<prompt>` is the instruction the agent receives when clicked.
</Accordion>

## Inquiry buttons

When the agent sends an inquiry button, it stores a prompt behind the scenes. Clicking the button sends that prompt to the agent, and the agent responds in your conversation.

If the button was sent by a background fork, clicking it opens an interactive fork that resumes from that fork's session — so you can continue where the background task left off. Otherwise the prompt is processed in your current session.

Inquiry buttons expire after **7 days**. If you click an expired button, you'll see an expiration notice.

<Accordion title="Developer detail: how inquiry buttons work internally">
  When the agent creates an inquiry button, the prompt text is persisted to disk with a unique ID. The button's custom ID encodes this reference. When you click:

  1. Discord dispatches the interaction to the bot
  2. The bot retrieves and removes the stored prompt
  3. If the button came from a background fork, an interactive fork is created to resume that session
  4. The prompt is sent to the agent, which streams its response

  Inquiry prompts are stored in `~/.ollim-bot/state/inquiries.json` with a 7-day TTL. Expired entries are cleaned up on read.
</Accordion>

## Fork embeds

Forks produce their own embeds at entry and exit, separate from the embeds the agent sends during conversation.

### Fork entry

When a fork starts (via `/fork`, an agent action, or an inquiry button), a purple "Forked Session" embed appears with three buttons:

| Button       | Style   | Action                                                 |
| ------------ | ------- | ------------------------------------------------------ |
| Save Context | Green   | Promotes fork context to the main session              |
| Report       | Blurple | Exits the fork and sends a summary to the main session |
| Exit Fork    | Red     | Discards the fork cleanly                              |

### Fork exit

When a fork ends, a "Fork Ended" embed is sent with a color indicating the exit strategy:

| Exit strategy  | Color |
| -------------- | ----- |
| Save           | Green |
| Report         | Blue  |
| Exit (discard) | Grey  |

## Persistence

Buttons remain functional across bot restarts:

* **Direct action buttons** (task operations, dismiss, fork controls) never expire — their data is encoded in the button itself.
* **Agent inquiry buttons** expire after 7 days — the stored prompt is cleaned up after that.

## Background fork behavior

Embeds sent from the main session or interactive forks are always delivered. In [background forks](/scheduling/background-forks), embeds are subject to additional constraints:

* **Ping budget** — each embed consumes one ping from the [ping budget](/scheduling/ping-budget). When the budget is exhausted, the embed is blocked and the agent is told to use reporting instead.
* **`critical: true`** — bypasses budget limits and busy checks. Use for things you'd be devastated to miss.
* **`allow-ping: false`** — when set in the background fork config, embeds are disabled entirely. `critical: true` does not override this.
* **Busy state** — when you're mid-conversation, non-critical embeds from background forks are blocked. The agent reports findings to the main session instead.

<Warning>Background fork embeds include a "bg" footer to distinguish them from main session messages. Interactive fork embeds show "fork".</Warning>

## Next steps

<Columns cols={2}>
  <Card title="Forks" icon="code-branch" href="/core-usage/forks">
    Interactive and background fork lifecycle, exit strategies, and idle timeout.
  </Card>

  <Card title="Ping budget" icon="gauge" href="/scheduling/ping-budget">
    How the ping budget controls background fork notifications.
  </Card>

  <Card title="Discord tools" icon="wrench" href="/extending/mcp-tools">
    Full reference for all Discord tools including discord\_embed.
  </Card>

  <Card title="Slash commands" icon="terminal" href="/core-usage/slash-commands">
    Discord slash commands for managing forks, permissions, and more.
  </Card>
</Columns>