Skip to content

Bridge Protocol (v1)

The bridge protocol is the internal API between each Go bridge host (apps/bridge-host) and the Node gateway (apps/gateway). Both run exclusively on the server’s internal network using JSON over HTTP authenticated with a shared bearer token (TRIODITIS_INTERNAL_TOKEN).

bridge host ── POST /v1/events ──────────────► gateway ──► Convex
bridge host ◄── POST /v1/commands ─────────── gateway ◄── Convex outbox
bridge host ── GET /v1/keys/:userId ────────► gateway (recipient public keys)

The gateway listens on GATEWAY_INTERNAL_ADDR (default 127.0.0.1:8601). Each bridge host has a stable hostId (BRIDGE_HOST_ID, default <network>-1) and listens on BRIDGE_HOST_ADDR (default 127.0.0.1:8611). The gateway routes commands only to configured addresses in BRIDGE_HOSTS (whatsapp-1=http://127.0.0.1:8611,...) and refuses HTTP redirects.

Identifier Description
network Slug: whatsapp, signal, gmessages, telegram, meta, instagram, discord, fake
userId Trioditis member ID (Convex members row)
loginId Opaque bridgev2 login ID (l_...), unique per network; "" before login completes
portalId Opaque chat/portal ID (p_...), unique per network (network IDs like phone numbers never leak)
eventId Deterministic hash per remote message part; serves as the dedup key
ghostId Opaque remote contact ID (g_...), unique per network
clientMessageId Client-generated ID carried end-to-end for outbound sends

POST /v1/events

{
"hostId": "whatsapp-1",
"network": "whatsapp",
"events": [{ "seq": 1042, "type": "message", "userId": "...", "loginId": "l_...", "at": 1732200000000 }]
}
  • seq increments strictly by 1 per event per host and survives restarts.
  • Events arrive in order. 200 {"ackedThrough": 1042} means every event through 1042 has been committed to Convex (or quarantined).
  • Delivery is at-least-once; the bridge host resends from ackedThrough + 1. Convex deduplicates on eventId and (hostId, seq).
  • ackedThrough may be lower than the batch’s last seq if Convex stopped early to stay inside transaction limits.
  • 409 {"expectedSeq": n} instructs the host to resend starting at n.
  • Heartbeats: On startup and every 30 seconds, the host posts an empty batch (events: []) to register liveness and learn ackedThrough. Hosts silent for over 2 minutes stop receiving commands.
  • Size limits: Max 100 events and 8 MiB JSON per batch (gateway rejects bodies over 32 MiB). Individual events over 1 MiB are quarantined.

Every event includes seq, type, userId, loginId, and at (ms):

Type Fields Notes
message portalId, eventId, networkTs, sender, sealed, historical, replyTo?, threadRoot?, clientMessageId?, mentionsMe? sender is {"self": true} or {"ghostId": "..."}. sealed uses kind message, object ID eventId
edit portalId, eventId, targetEventId, networkTs, sender, sealed, clientMessageId? Sealed with edit’s own eventId
reaction portalId, eventId, targetEventId, sender, key, networkTs key is the unsealed emoji (variation selectors stripped)
reactionRemove portalId, targetEventId, sender, key Removes an active reaction
redaction portalId, targetEventId, sender, networkTs Deleted for everyone
receipt portalId, sender, upToEventId, networkTs Read receipt
typing portalId, sender, typing, timeoutMs Ephemeral typing indicator
chat portalId, kind, sealed, parentPortalId?, deleted?, isRequest? Upsert (dm, group, channel, space); sealed holds name/topic/avatar (max 8 KiB)
chatCollage portalId, sealed The members whose pictures make a group’s picture when it has none (kind chat, object ID <portalId>/collage, {"ghosts": [...]}: up to 4, never the person, pictured first; empty for a DM). Sealed to the person only, apart from chat, which it never replaces; sent only when the choice changes (max 8 KiB)
contact ghostId, sealed Upsert; sealed holds name/handle/avatar (max 8 KiB)
loginState state, error? CONNECTING, CONNECTED, TRANSIENT_DISCONNECT, BAD_CREDENTIALS, UNKNOWN_ERROR, LOGGED_OUT
loginStep loginSessionId, step Interactive login stepper update
sendStatus clientMessageId, status, eventId?, error? submitted, sent, delivered, read, failed, unknown
backfillDone portalId, direction, more History import progress

POST /v1/commands

{
"commandId": "...",
"type": "send",
"userId": "...",
"loginId": "l_...",
"notAfter": 1732286400000
}
  • Responds 202 once durably queued in trioditis_command, or 4xx with {"error": "<code>"}.
  • commandId is idempotent: duplicate submissions return 202 without re-executing.
  • Size caps: Sealed messages/edits in events max 256 KiB (auto-truncated with truncated: true); chat/contact metadata and collages max 8 KiB; client outbound sends and login input max 64 KiB; login steps max 64 KiB; hostId max 64 chars.
  • Deadlines: Sends carry notAfter (24 hours); login commands expire after 10 minutes (expired). Payloads are deleted from the host as soon as execution finishes.
Type Fields Outcome event
send portalId, clientMessageId, sealed (outbound), notAfter, replyTo? sendStatus, then echoed message
edit portalId, targetEventId, clientMessageId, sealed (outbound), notAfter? sendStatus, then edit
react / unreact portalId, targetEventId, key reaction / reactionRemove
redact portalId, targetEventId redaction
markRead portalId, upToEventId none
typing portalId, typing none
loginStart loginSessionId, network, flowId? loginStep
loginSubmit loginSessionId, stepId, sealed (outbound, <loginSessionId>/<stepId>) loginStep
loginCancel loginSessionId loginStep (cancelled)
logout — loginState (LOGGED_OUT)
backfill portalId, beforeEventId?, limit (1–500) historical: true messages, then backfillDone
  • submitted is emitted on connector handoff, sent on network confirmation, failed only when the network definitively refuses, and unknown whenever an outcome is ambiguous (including restarts mid-send). The bridge host never retries a send automatically.
  • notAfter is enforced before handoff (with an 11-minute safety margin) and again when reading media attachments (2-minute margin). Past handoff to bridgev2, notAfter is best-effort—for example, a stalled WhatsApp whatsmeow send lock can delay transmission past notAfter, in which case the actual outcome (sent or unknown) is always reported truthfully.

Protocol errors never contain free-text strings:

  • Error codes: network_rejected, not_connected, timeout, invalid_command, expired, unsupported, rate_limited, bad_credentials, login_failed, internal
  • Quarantine reasons: missing_target, missing_chat, foreign_login, foreign_host, unknown_login_session, unknown_send, malformed_envelope, too_large, invalid_event

A loginStep event carries a step payload rendered generically by the client:

{
"stepId": "...",
"type": "displayAndWait | userInput | cookies | complete | cancelled | error",
"instructions": "...",
"display": { "type": "qr | code | emoji | nothing", "data": "..." },
"fields": [{ "id": "phone", "type": "phoneNumber", "name": "Phone number" }],
"cookies": { "url": "...", "fields": [] },
"loginId": "... (on complete)",
"error": "... (on error)"
}

Displayed pairing data (QR codes, pairing codes) is scrubbed from the bridge host’s journal once acknowledged by the gateway. Submitted user credentials are always sealed to BRIDGE_PUBLIC_KEY.

GET /v1/keys/:userId returns:

{
"identity": { "kid": "...", "publicKey": "..." },
"agentAccess": { "kid": "...", "publicKey": "..." },
"agentGrantedPortals": ["p_..."]
}

The bridge host caches keys for 60 seconds in memory (and persists the member’s identity key in its database so sealing continues if the gateway is briefly down). Users who haven’t completed identity key setup receive 409, blocking loginStart until keys are ready.