# Events your app hears

> The events Tamr's AI waiter SDK sends your app: ready, state, order.placed, order.cancelled, payment.completed, checkout, open_dish, bookings, staff calls and logs.

Source: https://tamr.link/docs/sdks/events

`on(type, listener)` subscribes to what the waiter page tells your app, and returns a function that removes the listener. These events are for your app's screen. **For your backend, use [webhooks](https://tamr.link/docs/webhooks)**, the source of truth: your app may be closed when something happens.

| Event | When |
| --- | --- |
| `ready` | The chat is ready: the restaurant, branch, conversation id and capabilities. |
| `state` | What the chat is doing, on every change: `view` (`welcome` or `conversation`), `busy`, `itemCount`. |
| `order.placed` | Orders go to Tamr: the diner's order reached the restaurant's team. |
| `order.cancelled` | Orders go to Tamr: an order it told you was placed ended unserved (`orderId`, `status`: `declined`, `cancelled` or `expired`). Typed from the next release; heard through `on` today. |
| `payment.completed` | Orders go to Tamr: Tamr Pay took the payment. |
| `checkout` | The app's cart: the diner wants to check out. Open your checkout. |
| `open_dish` | The diner tapped a dish: show your page for it. |
| `booking.made`, `booking.changed` | The waiter booked, moved or cancelled a table. |
| `waiter.called` | The diner asked for staff, or the waiter escalated. |
| `review.submitted` | The diner rated an order's dishes after `requestReview`. From the next release. |
| `close` | The diner closed the chat. |
| `log` | Debug mode only: one line of the page's trace. |

The waiter's cart proposals are not events: you answer them with `onCartAdd`, `onCartUpdate` and `onCartRemove`. See [Ordering modes](https://tamr.link/docs/guides/ordering).

## What an event carries

Each event is a message with a type and its data, as the contract's fixtures hold it. An `order.placed`:

order.placed:

```json
{
  "v": 1,
  "id": "msg_0055",
  "type": "order.placed",
  "ts": 1792310455000,
  "data": {
    "orderId": "ord_0001",
    "number": 17,
    "status": "sent",
    "branch": "achrafieh",
    "table": "12",
    "currency": "LBP",
    "subtotal": "355000",
    "lines": [
      {
        "dishId": "dish_kafta",
        "externalId": "SKU-1042",
        "title": "Kafta plate",
        "variantLabel": null,
        "quantity": 2,
        "unitPrice": "145000"
      },
      {
        "dishId": null,
        "externalId": null,
        "title": "Fattoush",
        "variantLabel": "Large",
        "quantity": 1,
        "unitPrice": "65000"
      }
    ]
  }
}
```

## Unknown events

New event types may arrive in later versions without a new SDK: ignore what you don't know. Kotlin and Swift types are deliberately not exhaustive, so keep an `else` or `default` branch.
