Message Reference
Envelope
All messages use the same envelope:
{
"type": "hello",
"payload": {}
}Capabilities
The welcome message returns the capabilities supported by the server:
| Capability | Description |
|---|---|
events | Event notifications (future use) |
state | App state snapshots (future use) |
integration.auth | Access request flow is supported (available when user is signed in) |
See per-capability details:
Message Types
hello (client -> server)
Identify your client.
{
"type": "hello",
"payload": {
"clientType": "integration",
"clientId": "lumia",
"displayName": "Lumia",
"version": "1.0.0"
}
}Fields:
clientType: must beintegrationclientId: stable ID (slug or reverse-DNS)displayName: shown to the user (not verified)version: semantic version of your client
welcome (server -> client)
Server confirms support and capabilities.
{
"type": "welcome",
"payload": {
"capabilities": ["events", "state", "integration.auth"]
}
}request_access (client -> server)
Request user approval for scopes.
{
"type": "request_access",
"payload": {
"clientId": "lumia",
"displayName": "Lumia",
"requestedScopes": ["rest.full"]
}
}Fields:
requestedScopes: array of scopes; v1 supportsrest.fullonly
access_pending (server -> client, optional)
Indicates a consent prompt is waiting for user input.
{
"type": "access_pending",
"payload": {
"requestId": "req_01HZXN5A"
}
}access_granted (server -> client)
User approved; channel API key is issued.
{
"type": "access_granted",
"payload": {
"requestId": "req_01HZXN5A",
"apiKey": "sk_live_xxxxx",
"scopes": ["rest.full"],
"channelName": "mychannel"
}
}access_denied (server -> client)
User denied the request.
{
"type": "access_denied",
"payload": {
"requestId": "req_01HZXN5A",
"reason": "user_denied"
}
}error (server -> client)
Typed error response.
{
"type": "error",
"payload": {
"code": "invalid_scope",
"message": "Unsupported scope: rest.write"
}
}