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

# Record In-App Event

> Report that an in-app item was displayed, clicked, dismissed or read

Reports what happened to an in-app item in your app. These reports power the step stats in Sequenzy and decide what stays in the feed. Requires the `subscribers:write` scope.

* `displayed`: the item was shown. Messages leave the open feed after this, so each one shows once.
* `clicked`: a button or the item itself was clicked. Every click counts in `clickCount`.
* `dismissed`: the contact closed it. Cards leave the feed after this.
* `read`: a card was opened or scrolled into view.

Clicks, dismissals and reads also count as a display. The first report of each type sets its timestamp; repeats change nothing and return `recorded: false`, so retrying is safe. The exception is `clickCount`, which every `clicked` report increments, so send `clicked` once per click.

## Request

<ParamField path="messageId" type="string" required>
  Item ID from [List In-App Messages](./list-messages).
</ParamField>

<ParamField body="type" type="string" required>
  `displayed`, `clicked`, `dismissed` or `read`.
</ParamField>

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/in-app/messages/iam_123/events" \
  --header "Authorization: Bearer $SEQUENZY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "type": "dismissed" }'
```

## Response

<ResponseField name="recorded" type="boolean">
  True when this report set the timestamp; false when it was already recorded.
</ResponseField>

<ResponseField name="message" type="object">
  The item after the update, in the [list](./list-messages) shape.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "recorded": true,
    "message": {
      "id": "iam_123",
      "kind": "message",
      "format": "banner",
      "displayedAt": "2026-10-11T09:05:00.000Z",
      "dismissedAt": "2026-10-11T09:05:00.000Z",
      "clickCount": 0
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Invalid API key"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "API key is missing required scope: subscribers:write"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "In-app message not found."
  }
  ```

  ```json 422 theme={null}
  {
    "type": "validation",
    "on": "body",
    "property": "/type",
    "message": "Expected union value"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.