Communication permissions control whether an approved app can contact a user through Onyx.
Sign-in alone does not grant messaging access. The app must have the right consent, trust posture, and available communication action before it can send.
Reachability
Reachability describes whether the app can communicate with the user.
Reachability can depend on:
- user consent
- app approval
- account trust state
- communication permission
- thread state
- feature availability
- regional limits
The app should check reachability before creating a conversation or sending a message.
Available Actions
The current state determines which actions are available.
An approved app may be able to:
- view identity connection state
- request communication consent
- create an app-linked conversation
- send an approved message
- receive delivery status
- receive webhook events
If an action is unavailable, the app should show the reason or guide the user to the required step.
Login Versus Messaging
Login confirms account access.
Messaging requires separate permission.
This separation protects users from apps that authenticate successfully but have not earned permission to contact them.
Delivery Status
Delivery status helps the app understand what happened after send.
Status can reflect:
- allowed
- blocked
- restricted
- unsupported
- consent required
- trust insufficient
- thread unavailable
Partners should use status and reason codes instead of retrying blindly.
User Control
Users can limit or revoke communication permissions.
After revocation, the app should stop sending messages and update its own state. If the user reconnects later, request permission again.
Partner Behavior
Partners should:
- check permission before sending
- keep messages tied to the approved purpose
- avoid unsolicited communication
- honor blocked or muted states
- keep recovery paths clear
Communication access is a privilege attached to consent, not a side effect of login.