Envelopes

The WebSocket gateway expects incoming JSON frames shaped like:

Types: Envelopes

WebSocket request envelope

The WebSocket gateway expects incoming JSON frames shaped like:

{
  "action": "send_message",
  "userbot_id": 1,
  "chat_id": -1001234567890,
  "text": "Hello"
}

Observed behavior in code:

  • action selects the command or gateway-side action
  • open_client is handled directly in the WebSocket consumer
  • all other actions are forwarded as command payloads

WebSocket live response envelope

Most outbound frames use this wrapper:

{
  "type": "chat_update",
  "userbot_id": 1,
  "payload": {
    "userbot_id": 1,
    "type": "send_message",
    "result": {}
  }
}

Error variant:

{
  "type": "chat_update",
  "userbot_id": 1,
  "payload": {
    "userbot_id": 1,
    "type": "send_message_error",
    "error": "chat_id is required"
  }
}

Command envelope

Source: backend/tg_client/messaging/envelopes.py

Relevant shape after CommandEnvelope.to_command_payload():

{
  "command": "send_message",
  "userbot_id": 1,
  "command_id": "<derived id>",
  "_meta": {
    "subject": "prod.eu1.tg.cmd_hi.s000.acc.1.send_message",
    "nats_msg_id": "1:send_message:<command_id>",
    "flow": "cmd_hi",
    "schema_version": "v1",
    "correlation_id": "<uuid>",
    "trace_id": "<uuid>",
    "issued_at": "<iso8601>",
    "command_id": "<command_id>",
    "shard": "s000",
    "priority": "cmd_hi",
    "expected_owner_epoch": 42
  }
}

Event envelope

Source: backend/tg_client/messaging/envelopes.py

EventEnvelope.to_live_payload() adds:

  • userbot_id
  • type
  • _meta.subject
  • _meta.live_subject
  • correlation/trace metadata

Needs verification based on code

  • there is no versioned JSON schema registry for envelopes
  • _meta fields are stable in code but not validated by a schema library