# Response format

Oaura is lenient about what `get_items` returns. You can return a bare array; you can return an object with the items under any one of several common keys; you can wrap the whole thing in a single-element outer array (as n8n does by default). All of these resolve to the same `items[]` the widget renders.

`item_clicked`, `create_item`, `update_item`, `delete_item` are even more lenient — return whatever you like; the widget displays what it understands and ignores the rest. The schemas below document what each category understands; everything else is treated as opaque metadata.

## `get_items` shapes

All of these are accepted. The first column is what you return; the second is what the widget actually does with it.

| You return                                                             | Oaura treats it as                                                                 |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `[ {…}, {…}, … ]`                                                      | `items = [ {…}, {…} ]`                                                             |
| `{ "items": [ … ] }`                                                   | `items = the value of "items"`                                                     |
| `{ "data": [ … ] }`                                                    | same — `data` is recognised                                                        |
| `{ "results": [ … ] }`                                                 | same — `results` is recognised                                                     |
| `{ "records": [ … ] }`                                                 | same — `records` is recognised                                                     |
| `{ "rows": [ … ] }`                                                    | same — `rows` is recognised                                                        |
| `[ { "items": [ … ], "view": "list", "badge": { "color": "blue" } } ]` | Single-element outer array auto-unwrapped before parsing. n8n's default behaviour. |
| `{ "items": […], "view": …, "badge": …, "anything_else": … }`          | Items rendered, view+badge applied, extra keys ignored.                            |
| `null` or `""`                                                         | Empty list, no error.                                                              |

If the response is none of the above (e.g. a bare object that isn't a wrapper), it's wrapped: `items = [the object]`. This is rarely what you want for a list tab but lets you serve a one-item list from a non-list endpoint.

## Object-wrapper fields

The object-wrapper form is the canonical one. Recommended for anything beyond a trivial list.

```json
{
  "items": [ /* see schemas */ ],
  "view":  "list",
  "badge": { "color": "blue" }
}
```

### `items` (required)

The list itself. See [Default tabs](/oaura/tabs/default.md) or [Messaging tabs](/oaura/tabs/messaging.md) for the full schema per category.

### `view` (messaging only)

| Value              | Effect                                                                                                                                                                                                                                           |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `"list"` (default) | Normal list rendering.                                                                                                                                                                                                                           |
| `"direct"`         | Skip the list. The widget auto-opens `item_clicked` on `items[0]` and the visitor lands directly in the conversation. Use this for single-thread tabs ("Talk to the team") where the list adds no value. The back button is hidden in this mode. |

`view` is ignored on `default` tabs.

### `badge`

Controls the colour of the unread badge on the tab strip. The count is derived from the items themselves (unread count for messaging, item count for default) — you only supply the colour.

```json
{ "badge": { "color": "blue" } }
```

Accepted colours: `green`, `yellow`, `red`, `blue`, `gray`, `purple`, `orange`, `teal`, `pink`, `brown`. Unknown colours fall back to gray.

For the flat-array shape, the widget reads the badge from `items[0].badge` if present — useful when your data source attaches badges per-item and you want the first item's badge to drive the strip.

## `item_clicked`, `create_item`, `update_item`, `delete_item` responses

All four accept any JSON. The widget normalises:

* A single-element outer array → unwrapped to the first element. (n8n default.)
* An object → used as-is.
* A non-JSON or empty body → treated as `{ "rawText": "<text>" }`.

For messaging `item_clicked`, the widget extracts:

* `conversationId` or `id` from the response — used to subscribe to the per-conversation realtime channel. If neither is present, it falls back to the `id` it sent in the request.

For all actions, the response is shown to the visitor as the result of their action. Default tabs render the response as a key-value detail screen; messaging tabs use it to populate `MessagingView`.

## Failures

If your webhook returns a non-2xx status, the edge function:

* Records a `widget_issues` row so the failure shows up in the Oaura dashboard for the operator.
* Returns `{ ok: false, status, details, error }` to the widget with HTTP 200 (so the widget's `fetch` doesn't itself fail).
* The widget shows an error state in the tab and keeps the previous items cached.

If your webhook is unreachable (DNS, connection refused, timeout), same flow but with HTTP 502 to the widget.

The actual response body is captured and truncated to the first 2 000 characters in `widget_issues` for diagnosis. Don't include secrets in error responses.


---

# 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/response-format.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.