Spixi Message Protocol

A SpixiMessage is the application-level payload carried within the encrypted data field of a StreamMessage. It represents the actual command or content being sent between users, such as a chat message, a file transfer request, or a contact request.

Serialization Structure

A SpixiMessage is serialized as a binary structure using a BinaryWriter. Fields are written sequentially and read back with a BinaryReader.

Field	Data Type	Required	Description
type	int32	Yes	The SpixiMessageCode that defines the purpose and structure of the data field.
dataLength	int32	Yes	The byte length of the data field. A value of 0 indicates no payload.
data	byte[]	No	The SpixiMessage payload for this message type. Present only if dataLength > 0.
channel	int32	No	An identifier for a specific chat channel. Defaults to 0 if not present. Read only if remaining bytes are available.
groupAddress	IxiBytes	No	The address of the group this message belongs to. Present only for group messages. Read only if remaining bytes are available.
groupSenderAddress	IxiBytes	No	The address of the original sender within a group. Used by the group owner when forwarding messages to other participants, and when hideParticipantAddresses mode is active. Sender can set this value to their address and send it to the group owner, to indicate that it needs to be forwarded to other group participants (this is useful when the sender doesn't have all group participants added as contacts). Read together with groupAddress.

[!NOTE] The channel, groupAddress, and groupSenderAddress fields are optional during deserialization for backward compatibility. The deserializer checks for remaining bytes before attempting to read each field.

---

Spixi Message Codes

The type field determines how the data payload should be interpreted. The following codes are defined.

Chat & Streaming

Code	Name	Description
0	chat	A standard text chat message.
53	chatStream	A streaming chat message with incremental content delivery.

Profile

Code	Name	Description
1	getNick	Requests the nickname of a contact.
2	nick	Provides the nickname of a contact.
24	avatar	Sends an avatar image.
25	getAvatar	Requests the avatar for a contact.

Messaging Status & Reactions

Code	Name	Description
8	msgRead	Confirmation that a message has been read by the recipient.
9	msgReceived	Confirmation that a message has been delivered to the recipient's device.
33	msgDelete	A request to delete a previously sent message.
34	msgReaction	Adds a reaction (e.g., an emoji) to a specific message.
35	msgTyping	Indicates that the user is currently typing a message.
36	msgError	Reports an error in processing a previous message.
39	msgReport	Reports a message for moderation or abuse (e.g. for group servers/bots).

Contact & Group Management

Code	Name	Description
19	acceptAddBot	A specialized request that the peer who accepted the contact request is a bot.
37	leave	A notification that a user is leaving a group chat.
38	leaveConfirmed	Confirmation that the leave request was processed.
40	requestAdd2	A request to add a user as a contact.
41	acceptAdd2	Accepts a contact request.
42	keys2	Exchanges session keys for end-to-end encryption.
26	getPubKey	Requests the public key of a contact.
27	pubKey	Provides a public key in response to a request.
52	createGroup	Instructs participants to join a peer-to-peer group chat.

Transactions

Code	Name	Description
49	transactionRequest	A request to initiate a transaction with a peer.
48	transactionSend	Sends transaction data to a peer.
46	transactionSendRequest	A request to send a transaction via the peer's node.
47	transactionSendResponse	The response to a transactionSendRequest.

Secure Connections

Code	Name	Description
50	openSecureConnection	Opens a direct secure (IXI Socket) connection with a peer.
51	closeSecureConnection	Closes an active secure connection.

File Transfer

Code	Name	Description
10	fileData	A chunk of a file's binary data.
11	requestFileData	Requests a specific chunk of a file.
12	fileHeader	Contains metadata about a file being sent (name, size, type).
13	acceptFile	The recipient agrees to accept an incoming file transfer.
23	fileFullyReceived	Confirmation that all chunks of a file have been received.

Voice/Video Calls

Code	Name	Description
14	requestCall	Initiates a voice or video call.
15	acceptCall	Accepts an incoming call request.
16	rejectCall	Rejects an incoming call request.
17	callData	A chunk of real-time audio or video data.

Generic Application Layer

Code	Name	Description
21	appData	Generic data for a mini-app or service.
22	appRequest	A generic request to a mini-app or service.
28	appRequestAccept	Accepts an appRequest.
29	appRequestReject	Rejects an appRequest.
30	appRequestError	Signals an error occurred during an appRequest.
31	appEndSession	Terminates a session with a mini-app.
43	getAppProtocols	Requests the list of app protocols supported by the peer.
44	appProtocols	Provides the list of supported app protocols.
45	appProtocolData	Generic data for a specific, named app protocol.

Bot Interaction

Code	Name	Description
20	botGetMessages	A request used by a bot to fetch messages from a channel.
32	botAction	A generic action or command sent to a bot.

Deprecated

Code	Name	Description
3	requestAdd	Legacy contact request. Superseded by requestAdd2 (40).
4	acceptAdd	Legacy contact accept. Superseded by acceptAdd2 (41).
5	sentFunds	Legacy funds notification. Deprecated in favor of transactionRequest (49).
6	requestFunds	Legacy payment request. Deprecated in favor of transactionSend (48).
7	keys	Legacy key exchange. Superseded by keys2 (42).
18	requestFundsResponse	Legacy response to requestFunds.

Reserved

Code	Name	Description
240-255	reserved	The range 0xF0 to 0xFF is reserved for custom, user-defined applications.