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 | Legacy local event notifications such as ttsAmplitude |
state | Reserved generic app state capability |
integration.auth | Access request flow is supported (available when user is signed in) |
avatar.protocol.v1 | Authenticated avatar subscription and event protocol |
See per-capability details:
Avatar messages use the same JSON envelope. When an avatar subscription negotiates binary-v1, audio chunks are binary WebSocket messages instead; all handshake, subscription, lifecycle, prepared, completed, expression, action, and snapshot messages remain JSON.
Message Types
hello (client -> server)
Identify your client.
{
"type": "hello",
"payload": {
"clientType": "integration",
"clientId": "lumia",
"displayName": "Lumia",
"version": "1.0.0",
"reconnectCredential": "aig_opaque_credential"
}
}Fields:
clientType: must beintegrationclientId: stable ID (slug or reverse-DNS)displayName: shown to the user (not verified)version: semantic version of your clientreconnectCredential: optional opaque credential returned after earlier consent
welcome (server -> client)
Server confirms support and capabilities.
{
"type": "welcome",
"payload": {
"capabilities": ["events", "state", "integration.auth", "avatar.protocol.v1"],
"authorizedScopes": ["avatar.events.read"]
}
}request_access (client -> server)
Request user approval for scopes.
{
"type": "request_access",
"payload": {
"clientId": "lumia",
"displayName": "Lumia",
"requestedScopes": ["rest.full"]
}
}Fields:
requestedScopes: one or more supported scopes, includingrest.fullandavatar.events.read
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. The response contains only the credentials needed by the approved scopes.
{
"type": "access_granted",
"payload": {
"requestId": "req_01HZXN5A",
"apiKey": "sk_live_xxxxx",
"scopes": ["rest.full"],
"channelName": "mychannel"
}
}An avatar-only grant does not expose the REST API key:
{
"type": "access_granted",
"payload": {
"requestId": "req_01HZXN5A",
"scopes": ["avatar.events.read"],
"reconnectCredential": "aig_opaque_credential"
}
}Persist the opaque credential in an application-owned file with operating-system appropriate permissions. Supply it in the next hello so approval survives restarts. A clientId alone is not authorization.
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"
}
}