---
title: "Record an in-app event"
method: POST
path: "/in-app/messages/{messageId}/events"
tags: ["In-app"]
---

# Record an in-app event

`POST /in-app/messages/{messageId}/events`

## Request

- Base URL: `https://api.sequenzy.com/api/v1`
- URL: `https://api.sequenzy.com/api/v1/in-app/messages/{messageId}/events`
- Auth: HTTP bearer

Records that the app displayed, clicked, dismissed or read an item. The first report of each type sets its timestamp; repeats change nothing except clickCount, and recorded is false. Clicks, dismissals and reads also mark the item displayed. Messages leave the open feed once displayed, clicked or dismissed; cards once dismissed. Requires the subscribers:write scope.

## Path parameters

- `messageId` string, required

## Request body

- object
  - `type` 'displayed' | 'clicked' | 'dismissed' | 'read', required

## Response `200`

Event recorded (or already recorded)

- object
  - `success` boolean
  - `recorded` boolean: True when this report set the timestamp; false for a repeat.
  - `message` InAppMessage: One item in a contact's in-app feed, with merge tags already resolved.
    - `id` string
    - `kind` 'message' | 'card': message: modal, banner or fullscreen, shown once. card: stays in the card feed until dismissed.
    - `format` 'modal' | 'banner' | 'fullscreen' | 'null', nullable: How a message is shown; null for cards.
    - `position` 'top' | 'bottom' | 'center' | 'null', nullable: Banners: top or bottom. Modals: bottom (a sheet rising from the bottom edge) or center. Null for full screens and cards.
    - `eyebrow` string: Short line above the title, such as "3 days left"; empty when the step has none.
    - `title` string
    - `body` string: Plain text; may contain line breaks.
    - `imageUrl` string, nullable
    - `imagePlacement` 'top' | 'background' | 'null', nullable: Modals and full screens with an image: top (image above the text) or background (image fills the message, text on a dark scrim over it). Null otherwise.
    - `buttons` object[]
      - `label` string
      - `action` 'open_url' | 'dismiss'
      - `url` string, nullable: https URL or app deep link for open_url buttons; null for dismiss.
    - `data` object: String key/values set on the step for your app's own logic.
    - `style` InAppStyle: Colors, corners and font to draw the item with. Resolved from the step's style preset and overrides against your brand (Email design settings) when the item was created. Colors are
      - `preset` 'brand' | 'soft' | 'bold' | 'dark'
      - `backgroundColor` string
      - `textColor` string: Title color.
      - `mutedTextColor` string: Body text color.
      - `buttonColor` string: Fill of the first link button. Other buttons are outlined in the text color.
      - `buttonTextColor` string
      - `cornerRadius` integer
      - `buttonRadius` integer
      - `fontFamily` string: CSS font stack from your brand settings.
    - `pinned` boolean: Cards only. Pinned cards sort first.
    - `sequenceId` string, nullable
    - `stepId` string, nullable: The sequence step (node) that created it.
    - `createdAt` string, date-time
    - `expiresAt` string, date-time, nullable: After this the item leaves the open feed. Messages default to 30 days; cards never expire unless the step sets it.
    - `displayedAt` string, date-time, nullable
    - `clickedAt` string, date-time, nullable
    - `clickCount` integer
    - `dismissedAt` string, date-time, nullable
    - `readAt` string, date-time, nullable

## Other responses

- `401`: Unauthorized
- `403`: Missing subscribers:write scope
- `404`: Item not found in this workspace
- `422`: Unknown event type
- `500`: Server error

## Changes

- **2026-10-20** `54f67ac2d016`: 1 warning, 2 info
  - added the new `center` enum value to the `message/position` response property for the response status `200`
  - added the optional property `message/eyebrow` to the response with the `200` status
  - added the optional property `message/imagePlacement` to the response with the `200` status
- **2026-10-16** `db3873ca3d4d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sequenzy/apis/sequenzy-api/changes/in-app/messages/:messageId/events/post.md)

---

[API](https://skmtc.dev/sequenzy/apis/sequenzy-api.md) - [All operations](https://skmtc.dev/sequenzy/apis/sequenzy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sequenzy/apis/sequenzy-api/revisions/3d816357b738?raw)