In-app messages API
Management routes require X-OP-API-Key. Device fetch, compiled HTML, and IAM
receipts require X-OP-SDK-Key (plus X-OP-Device-Key on the shared sample app).
Management
| Method | Path | Purpose |
|---|---|---|
POST | /v1/apps/{app}/in-app-messages | Create a draft definition |
GET | /v1/apps/{app}/in-app-messages | List definitions; filter by lifecycle/search |
GET | /v1/apps/{app}/in-app-messages/{iam} | Definition and report summary |
PATCH | /v1/apps/{app}/in-app-messages/{iam} | Update a draft |
POST | /v1/apps/{app}/in-app-messages/{iam}/{action} | set-live, pause, resume, end, archive, or restore |
DELETE | /v1/apps/{app}/in-app-messages/{iam} | Delete a draft only |
The action route accepts exactly those six values and nothing else.
Duplicating a definition and sending a test are console-only actions — they
exist in the product but are not wired to this route, so POST …/duplicate and
POST …/test return 404 unknown in-app action.
The structured definition contains layout, blocks, triggers, audience,
dismissal, scheduling, frequency, and optional Liquid fields. Only drafts are
editable; lifecycle transitions are explicit actions.
Device fetch
Code
Returns { "in_app_messages": [...] }, capped at 25 active definitions. Each
definition contains stable ids, placement, triggers, duration, redisplay rules,
and either resolved structured blocks or an html_path.
Code
Returns a self-contained document with Liquid already resolved, a narrow native bridge, safe-area-aware placement, and carousel page-change events.
Receipts
Use the ordinary POST /v1/ingest route with one of:
Code
Code
A third type, iam_page_impression, is accepted by the ingest route and
additionally carries the stable carousel page id/index. No shipping SDK emits
it. iOS, Android and Unity send only iam_impression and iam_click, so
carousel page rows exist as a server-side capability with no client behind it
yet — do not build a report on them.
Duplicate click ids from the same device are ignored by the SDK before transmission.