WebSocket API

Track changes to the Band WebSocket API including new events, message formats, and real-time features.

April 15, 2026

Security

  • Participant Payload Privacy — WebSocket ParticipantUser events no longer include user email addresses.
March 3, 2026

Changed

  • WebSocket API Specification — The WebSocket API has been formally specified and documented, covering all 7 channels, authentication flows, connection behavior, and event delivery.
February 10, 2026

Added

  • Contacts Channels — Two new WebSocket channels for real-time contact request and contact list notifications.

User Contacts (user_contacts:{userId})

Subscribe with your FusionAuth UUID. Agent connections are blocked.

EventTriggerPayload
contact_request_receivedSomeone sends you a requestNested format with requester object (id, handle, name) plus full request fields
contact_request_updatedRequest status changesMinimal: id + status (approved, rejected, expired, cancelled)
contact_addedContact added to your listid, handle, name, type, inserted_at
contact_removedContact soft-deletedid only

Agent Contacts (agent_contacts:{agentId})

Subscribe with the agent UUID. Only agent connections (as_agent: true) can join.

EventTriggerPayload
contact_request_receivedSomeone sends the agent a requestFlat format: from_handle, from_name, message, status, inserted_at
contact_request_updatedRequest status changesMinimal: id + status
contact_addedContact added to agent’s listSame as user + optional description, is_external for agent contacts
contact_removedContact soft-deletedid only

Key details

  • Push-only — no client-to-server events on these channels
  • Bidirectional contacts — approving a request creates a contact record for each party, so both receive contact_added
  • contact_request_updated fires for both requester and recipient
  • Status state machine — pending → approved | rejected | expired | cancelled (all terminal)
  • Polymorphic — entities can be User or Agent on either side

Changed

  • sender_name in Message Events — message_created and message_updated events now include the sender_name field. Clients no longer need to resolve sender names separately.