# Prebuilt actions

Each custom tab can have up to six prebuilt actions. Each action is a webhook URL Oaura calls on the visitor's behalf — never the browser directly. The shape of the JSON map on the tab row:

```json
{
  "get_items":    { "enabled": true, "url": "https://your-n8n.com/webhook/get-items",    "connector_id": null },
  "item_clicked": { "enabled": true, "url": "https://your-n8n.com/webhook/item-clicked", "connector_id": null },
  "create_item":  { "enabled": false, "url": "", "connector_id": null },
  "update_item":  { "enabled": false, "url": "", "connector_id": null },
  "delete_item":  { "enabled": false, "url": "", "connector_id": null }
}
```

Each entry:

| Field          | Type         | Meaning                                                                                                                                                                                                                                                                                                          |
| -------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`      | boolean      | The action is wired up. The widget will surface its UI control only when this is true *and* `url` is non-empty.                                                                                                                                                                                                  |
| `url`          | string       | Absolute HTTPS URL of your webhook. `http://localhost` is allowed for development.                                                                                                                                                                                                                               |
| `connector_id` | uuid \| null | Optional reference to a [connector](https://github.com/tillforty/oaura-documentation/blob/main/connectors/overview.md). When set, Oaura looks up that connector's credential and attaches it as an `Authorization: Bearer …` (for bearer-token credentials) or as a custom header (for header-auth credentials). |

## The five actions

| Key            | HTTP method | Routed via                                                                                                                                                                  | Purpose                                                                                                                                           |
| -------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_items`    | `GET`       | `tab-fetch` edge function                                                                                                                                                   | Fetch the list rendered at the top of the tab.                                                                                                    |
| `item_clicked` | `GET`       | `tab-action` edge function                                                                                                                                                  | Fetch enriched detail for one row when the visitor opens it.                                                                                      |
| `create_item`  | `POST`      | `tab-action` edge function                                                                                                                                                  | Send a reply in a messaging thread. **Only ever fires from the messaging composer** — there is no UI surface for `create_item` on `default` tabs. |
| `update_item`  | `POST`      | Mixed: `tab-action` from inside a messaging thread (mark-read, per-message edits); **direct from the browser** when fired by the per-row menu or the generic detail screen. | Modify an existing item.                                                                                                                          |
| `delete_item`  | `POST`      | Mixed: `tab-action` from inside a messaging thread (per-message delete); **direct from the browser** when fired by the per-row menu or the generic detail screen.           | Permanently delete an item.                                                                                                                       |

For the full implementation reference — schemas, request shapes, examples — see [Default tabs](/oaura/tabs/default.md) or [Messaging tabs](/oaura/tabs/messaging.md).

> **Why "direct from the browser" for some paths?** Historical artifact. The per-row menu and the generic detail screen predate the `tab-action` edge function and still call your webhook directly with `fetch()`. The routing will be normalised in a future release; for now, any webhook wired to `update_item` or `delete_item` must accept calls from both surfaces — see each action's page for the exact body shape per path.

## Action ↔ category matrix

Not every action makes sense on every category. The widget surfaces controls only where there's a UI:

| Action         | `default`                                                                                       | `messaging`                                                                                                                                                                                |
| -------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `get_items`    | Renders the list. Required.                                                                     | Renders the conversation list. Required.                                                                                                                                                   |
| `item_clicked` | Opens the generic detail view. Without it, the row is non-clickable.                            | Opens `MessagingView`. Required for a usable messaging tab.                                                                                                                                |
| `create_item`  | **No UI.** The widget has no built-in "new" button. Wiring this on a default tab has no effect. | Drives the reply composer at the bottom of the thread.                                                                                                                                     |
| `update_item`  | Per-row "Update" menu item; button on the detail screen. Both fire direct from the browser.     | Used internally by `MessagingView` to auto-write read-receipts when the visitor opens a conversation, and for any per-message edits surfaced by the thread UI. Both fire via `tab-action`. |
| `delete_item`  | Per-row "Delete" menu item; button on the detail screen. Both fire direct.                      | Per-message delete inside `MessagingView`. Fires via `tab-action`.                                                                                                                         |

## What Oaura adds to every call

Whatever URL you put in `url`, the widget routes most actions through an edge function that:

1. Verifies the agent's API key.
2. Verifies the visitor's identity (`x-end-user-token`) per the agent's `identity_mode`.
3. Looks up the tab row, checks it belongs to this agent, and confirms it's reachable in the active environment.
4. Builds a fresh URL: takes your `url`, appends a known set of query params (caller context + verified identity), adds the credential header from `connector_id` if present, and fires the request.
5. Records a `widget_issues` row on non-2xx upstream responses so failures surface in the Oaura dashboard.

See [Request format](/oaura/tabs/request-format.md) for the exact query params and headers your webhook receives, and [Response format](/oaura/tabs/response-format.md) for what Oaura accepts back.

## Wiring an action

In the dashboard:

1. Open the agent, scroll to **Tabs**.
2. Expand the tab. Open **Prebuilt actions**.
3. Toggle the action on.
4. Paste the absolute HTTPS URL of your webhook.
5. Optional: pick a connector to attach a credential header.
6. Save.

The widget picks up the change on the next `validate-widget` call (which happens on every page load).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tillforty.com/oaura/tabs/prebuilt-actions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.