Lotse, called from your server.From PHP, Node, Python or curl.

The other direction: webhooks

OpenAPI 3.1 description

userId reaches verified installs only

Without that rule, anyone could call identify("u_42") in their own copy of your app and receive the order updates of u_42. So a push to a userId goes only to installs whose identify carried a valid user hash. If the user has none, the answer is 422 identity_verification_required.

installId always works

Only your backend knows an install id, because your app reported it there with Lotse.instance.installId. Use it when your project does not verify identities.

No device is no error

If no install of the target can be reached, the answer is still 201, with "status": "no_devices", and the webhook message.failed follows. GET /v1/messages/{id} shows the deliveries and whether the push was opened.

SDK 0.2.0 or later

From 0.2.0 the SDK opens the targetPath of a tapped message and reports push_open with its messageId. With an older SDK the notification still shows, and a tap only opens the app.

Visible like campaigns

Messages are listed in the console under Campaigns, tab Messages, and push_sent and push_open land in the event stream. Title and text are deleted after 30 days, the message after 90.

import crypto from 'node:crypto';

// HMAC-SHA256 of the user id, trimmed as Lotse stores it, keyed with the
// whole identity secret (lt_is_…), as lower-case hex.
const userHash = crypto
  .createHmac('sha256', process.env.LOTSE_IDENTITY_SECRET)
  .update(userId.trim())
  .digest('hex');

await Lotse.instance.identify(userId, userHash: userHash);

On the install seen last

Lotse resolves the user when the event arrives: it lands on the install of the user seen most recently, among those that existed at the time of the event. Funnels, segments, journey triggers and goals and campaign conversions count it like an event from the app.

Users without an install

An unknown userId creates a user without an install, up to 100,000 per project. Such events count in the event explorer, not in segments or journeys, and an install that comes later does not take them over.

Time

ts is optional and defaults to now. It may lie up to 30 days back and 5 minutes ahead of the server clock. Outside that the call is refused, so a wrong clock shows at once.

Duplicates

Give each event an id of up to 128 visible ASCII characters, such as order-1042. An id the project has stored before is skipped and costs nothing; the answer counts it under duplicates.

Names and props

Names have up to 100 characters, props are up to 20 pairs of strings of up to 200 characters, as in the SDK. Server events count against the same 500,000 events per project and day.

Names that Lotse and its SDK write themselves are reserved:

• session_start
• identify
• push_sent
• push_open
• link_click
• attribution_match
• survey_answered
• feedback_submitted
• feature_voted
• feature_unvoted
• rage_tap

{
  "error": "forbidden",
  "message": "This server key lacks the scope messages:send. Scopes are fixed when a key is created: create a key with it in the Lotse console."
}

400invalid_input

A field is missing, unknown, or has a wrong type or value. The message names the field.

401unauthorized

No key, or one that is unknown, revoked or expired.

403forbidden

The key lacks the scope of the route, and the message names it. Or the request came from a browser.

403project_suspended

The project is suspended. Reading and deleting still work.

404not_found

No such path, or nothing with that id in your project.

405method_not_allowed

The path takes other methods; the header Allow lists them.

409conflict

Not possible in the current state, such as a slug that is taken, or an Idempotency-Key used for another request.

413invalid_input

The body is larger than 64 KiB, or 256 KiB for /v1/events.

422identity_verification_required

A push to a userId without a verified install.

429quota_exceeded

A quota of the project, the same as in the console, such as the links of its plan, 5,000 on Free. Comes without Retry-After.

429rate_limited

A budget of calls or writes is used up. Retry-After says how many seconds to wait.

500internal_error

A failure on the Lotse server. Try again later.

503unavailable

Work that could not be finished right now, such as starting a send. Repeat the same request after Retry-After: it does what is missing and nothing twice.

Every call with a valid key that did not get a 2xx stays in the console for 7 days, under Developers, Request log: time, key, method, path, status, code and duration, never a body or a header. Refusals by a budget are only sampled. A user id in the path is not kept.