Skip to main content
See the full parameter and response reference for GET in-app messages, POST log event, and GET capabilities.

Prerequisites

Authenticate with the Storefront API using a Bearer access token. See Integrate with Masivo.
These endpoints work with CLIENT and SERVER API keys. Use a SERVER key when fetching messages from your backend; CLIENT keys are suitable for embedded apps that call Masivo directly.

1. Check capabilities

const response = await fetch(
  "https://app.masivo.ai/api/storefront/v1/inapp/capabilities",
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "x-account-id": accountId
    }
  }
);
const { data } = await response.json();
// { inappEnabled: true, eventTypes: ["PURCHASE", "APP_OPEN"] }

2. Fetch eligible messages

const customerId = "user_abc123";
const params = new URLSearchParams({ limit: "5", trigger: "APP_OPEN" });
const response = await fetch(
  `https://app.masivo.ai/api/storefront/v1/customers/${customerId}/inapp-messages?${params}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "x-account-id": accountId
    }
  }
);
const { data } = await response.json();
const messages = data.messages;
Only pending messages that are scheduled, not expired, and under their impression cap are returned.

3. Log impression events

const messageId = messages[0].id;
const payload = { action: "shown" as const };

await fetch(
  `https://app.masivo.ai/api/storefront/v1/customers/${customerId}/inapp-messages/${messageId}/events`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "x-account-id": accountId,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  }
);
For button clicks:
const clickPayload = {
  action: "clicked",
  metadata: { button_id: "primary" }
};

Message content fields

FieldDescription
typeSurface type: modal, fullscreen, slideup, banner
content.titleHeadline
content.bodyMain copy
content.image_urlOptional hero image
content.buttonsAction buttons with action: dismiss, deeplink, url, custom
display_rules.max_impressionsServer-enforced show limit
display_rules.min_interval_secondsMinimum gap between shown events
trigger.eventWhen set, pass the same value as the trigger query param

Common errors

StatusCauseExample details
404Message not found for customerIn-app message not found
422Invalid action or query paramsValidation message from Zod