SapaganDocs sapagan.com

API reference

In-app

In-app templates and settings, and the two calls the app SDK makes.

In-app templates and settings, and the two calls the app SDK makes.

POST /v1/broadcasts/{id}/end#

End a live in-app campaign now

The campaign becomes sent and the app is given its messages no more. In-app campaigns only; 409 when it is not live.

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring (uuid) required
curl -X POST "$SAPAGAN_URL/v1/broadcasts/user-42/end" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "id": "user-42",
  "status": "<status>"
}

GET /v1/inapp-templates#

The in-app starters this workspace is offered and the organisation's in-app templates

Marketplace starters (they open a product) are listed only in a marketplace workspace; so are the organisation's templates that open a store, catalog, product or voucher.

Accepted keys Server key

curl -X GET "$SAPAGAN_URL/v1/inapp-templates" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "marketplace": true,
  "starters": [
    {
      "key": "<key>",
      "audience": "general",
      "ids": {
        "en": "<en>",
        "id": "user-42"
      },
      "name": {
        "en": "<en>",
        "id": "user-42"
      },
      "description": {
        "en": "<en>",
        "id": "user-42"
      },
      "content": {
        "en": {},
        "id": {}
      }
    }
  ],
  "organisation": [
    {
      "id": "user-42",
      "name": "order_placed",
      "description": "<description>",
      "workspaceId": "<workspaceId>",
      "marketplaceOnly": true,
      "createdBy": "<createdBy>",
      "createdAt": "<createdAt>",
      "updatedAt": "<updatedAt>",
      "content": {}
    }
  ]
}

POST /v1/inapp-templates#

Save an in-app campaign or in-app content as a template of the organisation (operator)

Give broadcastId (one of this workspace's in-app campaigns) or content (in-app content). Its end (rules.endsAt, rules.expiresAfterHours) is left out. The in-app rules check it for this workspace (400 invalid_content); names are unique per organisation (409 name_taken). Every workspace of the organisation sees it (one that opens a product, marketplaces only). Audited.

Accepted keys Server key

Request body

FieldTypeNotes
name requiredstringmin 1, max 120
descriptionstringmax 500
broadcastIdstringmax 100
contentobject
curl -X POST "$SAPAGAN_URL/v1/inapp-templates" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_placed"
  }'

Responses

201 Created, 400 Invalid request, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 201

{
  "id": "user-42",
  "name": "order_placed",
  "description": "<description>",
  "workspaceId": "<workspaceId>",
  "marketplaceOnly": true,
  "createdBy": "<createdBy>",
  "createdAt": "<createdAt>",
  "updatedAt": "<updatedAt>",
  "content": {}
}

GET /v1/inapp-templates/{id}#

One in-app template to use here, with what the in-app rules refuse in this workspace

id is a starter (starter:<key>:<en|id>) or one of the organisation's templates. issues is empty when the content can be used here as it is.

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required
curl -X GET "$SAPAGAN_URL/v1/inapp-templates/user-42" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "id": "user-42",
  "source": "starter",
  "name": "order_placed",
  "description": "<description>",
  "locale": "en",
  "content": {},
  "issues": [
    {
      "field": "<field>",
      "message": "<message>"
    }
  ]
}

PATCH /v1/inapp-templates/{id}#

Rename an in-app template, or change its description (operator)

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
namestringmin 1, max 120
descriptionstringmax 500
curl -X PATCH "$SAPAGAN_URL/v1/inapp-templates/user-42" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_placed",
    "description": "<description>"
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "id": "user-42",
  "name": "order_placed",
  "description": "<description>",
  "workspaceId": "<workspaceId>",
  "marketplaceOnly": true,
  "createdBy": "<createdBy>",
  "createdAt": "<createdAt>",
  "updatedAt": "<updatedAt>",
  "content": {}
}

DELETE /v1/inapp-templates/{id}#

Remove an in-app template (operator)

Messages already made from it are not affected. Audited, with the content it had.

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required
curl -X DELETE "$SAPAGAN_URL/v1/inapp-templates/user-42" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "id": "user-42",
  "removed": true
}

POST /v1/inapp/events#

Report an in-app message shown, clicked or dismissed (app SDK)

Recorded once per delivery and event; a click or dismissal records the show too when it was not reported. Always 202: recorded is false for a repeat and, identically, for an unknown or foreign delivery or a profileId that is not the recipient.

Accepted keys Track key App key

Request body

FieldTypeNotes
deliveryId requiredstring
event required"shown" | "clicked" | "dismissed"
at requiredstring (date-time)
profileId requiredstringmin 1, max 200
buttonIndexinteger or nullmin 0, max 1
platform"android" | "ios" | "web"
curl -X POST "$SAPAGAN_URL/v1/inapp/events" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryId": "<deliveryId>",
    "event": "shown",
    "at": "2026-11-17T09:30:00+07:00",
    "profileId": "user-42"
  }'

Responses

202 Accepted, 400 Invalid request, 429 Rate limited. Errors use the error body.

Example response 202

{
  "recorded": true
}

GET /v1/inapp/messages#

The in-app messages the app may show this person now (app SDK)

The app's ingest key plus the person's token in X-Sapagan-User-Token: an identity token signed by your backend or your registered session JWT (required in production workspaces; its subject must be userId). Messages come rendered for the person with the rules the SDK applies on the device; denyScreens lists screens (exact, ignoring case, or a prefix ending in *) on which nothing is ever shown. ETag and If-None-Match give 304 when nothing changed.

Accepted keys Track key App key

Parameters

NameInTypeNotes
userIdquerystring required
appIdquerystring
platformquery"android" | "ios" | "web"
curl -X GET "$SAPAGAN_URL/v1/inapp/messages?userId=%3CuserId%3E" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 304 Not modified, 400 Invalid request, 401 Unauthorized, 403 Forbidden, 429 Rate limited, 503 Unavailable. Errors use the error body.

Example response 200

{
  "messages": [
    {
      "id": "user-42",
      "messageId": "<messageId>",
      "format": "banner_top",
      "slot": "<slot>",
      "title": "Pesanan dikirim",
      "body": "Pesanan #1042 sedang dalam perjalanan.",
      "imageUrl": "<imageUrl>",
      "link": "<link>",
      "buttons": [
        {
          "label": "Order service",
          "style": "primary",
          "action": "link",
          "link": "<link>"
        }
      ],
      "dismissible": true,
      "trigger": {
        "kind": "app_open"
      },
      "priority": 1,
      "perSessionCap": 1,
      "perDayCap": 1,
      "expiresAt": "<expiresAt>"
    }
  ],
  "denyScreens": [
    "<denyScreens>"
  ],
  "refreshAfterSeconds": 1
}

GET /v1/workspace/inapp-settings#

The workspace's in-app settings (screens never shown on)

Accepted keys Server key

curl -X GET "$SAPAGAN_URL/v1/workspace/inapp-settings" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK. Errors use the error body.

Example response 200

{
  "denyScreens": [
    "<denyScreens>"
  ],
  "apps": {}
}

PUT /v1/workspace/inapp-settings#

Change the in-app settings (owner); audited with the reason

denyScreens: screens of every app on which no in-app message is shown (a name as the app sends it, ignoring case, or a prefix ending in *); checkout* and payment* are always kept. apps: more screens per app id ({"<appId>": {"denyScreens": [...]}}).

Accepted keys Server key

Request body

FieldTypeNotes
denyScreensstring[]up to 100 items
appsobject
reason requiredstringmin 1, max 500
curl -X PUT "$SAPAGAN_URL/v1/workspace/inapp-settings" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Checked with the owner"
  }'

Responses

200 OK, 400 Invalid request. Errors use the error body.

Example response 200

{
  "denyScreens": [
    "<denyScreens>"
  ],
  "apps": {},
  "changed": true
}