App conversations let approved partners communicate with users inside controlled Onyx conversation surfaces.
The app must pass consent, reachability, trust, and message policy checks before sending. A successful login does not bypass those checks.
App-Linked Threads
An app-linked thread connects one approved app to one user conversation context.
Threads can help partners send:
- account updates
- service messages
- transaction updates
- support follow-ups
- approved notifications
The user should understand which app is speaking.
Pre-Send Checks
Before sending, the app should run a pre-send check.
The check can confirm:
- consent exists
- the user is reachable
- the app is approved
- the message intent is allowed
- the thread can receive messages
- the feature is available
If the check fails, use the returned reason to choose the next action.
Message Intent
Message intent helps Onyx evaluate delivery policy.
Intent can include:
- informational
- transactional
- sensitive
Sensitive messages can require stronger checks.
Partners should choose the intent that matches the message, not the intent most likely to pass.
Thread States
Thread state can affect delivery.
Thread states can include:
- active
- muted
- archived
- blocked
- closed
A blocked or closed thread should not receive new app messages unless policy allows a recovery path.
Delivery Outcomes
A message can return:
- allowed
- blocked
- restricted
- unsupported
- consent required
- trust insufficient
The app should show a clear state to the partner system and avoid repeated sends that do not change the outcome.
Content Boundaries
Partners should send messages tied to the approved user relationship.
Do not use app conversations for spam, unrelated marketing, identity pressure, or unsupported payment requests.