Messaging & Support

The MessagingService class (accessed via client.messaging) handles real-time customer ↔ store communication. It manages threaded conversations, message delivery, read state, and full thread lifecycle management.

Security Model

Messaging threads carry sensitive customer information — order inquiries, complaints, contact details, and uploaded attachments. To prevent one customer from reading or changing another customer’s conversation, every customer-facing messaging endpoint requires a signed customer session token (xAuthToken) issued by client.authentication. Ownership is enforced on every call:

Applies to	Rule
List / create operations	The `customer_id` you supply in the query or request body must match the `customer_id` on your session token.
Thread reads & writes	The thread must belong to the customer on the session token. Applies to `getThread`, `updateThread`, `getThreadMessages`, `sendMessage`, and `markThreadRead`.
Per-message edit & delete	You can only edit or delete messages the customer personally authored — not store or system messages.

Obtain a customer session via client.authentication.login(...) or client.authentication.verifyOtp(...) and pass customerSession.access_token as xAuthToken on every call below. If you authenticate shoppers with your own identity provider rather than through Galactic Core, send xExternalAuth (a signed identity assertion) or xIdpToken (your provider’s own token, which Galactic Core forwards to the store’s configured verifier) in place of xAuthToken. The examples below use xAuthToken, but every one of these endpoints accepts any of the three — send exactly one.

Each Thread object returned by listThreads and getThread includes an unread_count_customer field. Sum these client-side to compute a customer’s total unread count — no separate endpoint is needed.

Thread Discovery & Filtering

`listThreads`

Retrieve message threads with advanced server-side filtering. Pinned threads are automatically returned at the top of the result set.

const { threads, pagination } = await client.messaging.listThreads({
  xAuthToken: customerSession.access_token, // Must match customerId claim
  customerId: 'cust_123',
  status: 'active',           // active | resolved | closed | escalated | pending
  priority: 'high',           // low | normal | high | urgent
  archived: false,            // Filter by archive state
  unread: true,               // Only show threads with unread messages
  limit: 20,
  fields: 'id,subject,status,is_pinned,unread_count_store'
});

Response

{
  "threads": [
    {
      "id": "06084af6-7334-43d6-82c0-935f92335a25",
      "subject": "Question about my order",
      "status": "active",
      "priority": "normal",
      "thread_type": "order_inquiry",
      "last_message_at": "2026-06-20T11:28:58.338+00:00",
      "last_message_by": "customer",
      "unread_count_customer": 0,
      "unread_count_store": 1,
      "is_archived": false,
      "is_muted": false,
      "is_pinned": false
    }
  ],
  "pagination": { "limit": 50, "next_cursor": null, "has_more": false }
}

The customerId query parameter must match the customer_id on xAuthToken, otherwise the request is rejected.

Computing total unread

Each thread returned by listThreads includes unread_count_customer. Sum these client-side to display a “new messages” badge:

const { threads } = await client.messaging.listThreads({
  customerId: customer.id,
  xAuthToken: customerSession.access_token
});

const totalUnread = threads.reduce((sum, t) => sum + (t.unread_count_customer || 0), 0);
// returns e.g. 3   (each thread carries its own unread_count_customer)

To fetch only threads with unread messages, pass ?unread=true as a filter.

`getThread`

Retrieve high-level metadata for a single thread.

const thread = await client.messaging.getThread({
  xAuthToken: customerSession.access_token, // Must own this thread
  id: 'thread-uuid-123',
  fields: 'subject,priority,status,is_muted,is_archived'
});

Response

{
  "id": "06084af6-7334-43d6-82c0-935f92335a25",
  "customer_id": "88ad3683-d291-4c70-8f8b-9903a42bde1b",
  "customer_name": "Jane Doe",
  "customer_email": "jane.doe@tybritelabs.com",
  "customer_phone": null,
  "store_id": "ef7b07d3-424b-4b03-b1d4-30a2d2073b61",
  "store_name": "Galactic Test Store",
  "order_id": null,
  "product_id": null,
  "subject": "Question about my order",
  "thread_type": "order_inquiry",
  "status": "active",
  "priority": "normal",
  "last_message_at": "2026-06-20T11:28:58.338+00:00",
  "last_message_by": "customer",
  "unread_count_customer": 0,
  "unread_count_store": 1,
  "is_archived": false,
  "is_muted": false,
  "is_pinned": false
}

The thread must belong to the customer on your session token, otherwise the request is rejected.

`updateThread` 🔒

Update thread state including status, priority, or lifecycle flags.

Requires a Secret Key (for merchant lifecycle changes) or a customer xAuthToken belonging to the thread owner (for customer-driven actions like muting or archiving their own conversation). A customer request must own the thread, otherwise it is rejected.

await client.messaging.updateThread({
  xAuthToken: customerSession.access_token, // Required when called with a publishable key
  id: 'thread-uuid-123',
  requestBody: {
    status: 'resolved',
    priority: 'normal',
    archived: true,
    pinned: false,
    muted: true
  }
});
// returns { thread: { id, status: 'resolved', priority: 'normal', is_archived: true, is_muted: true, is_pinned: false, … } }

`markThreadRead` 🔒

Marks all customer messages in the thread as read and resets the store unread count to 0.

await client.messaging.markThreadRead({
  xAuthToken: customerSession.access_token, // Must own this thread
  id: 'thread-uuid-123'
});
// returns { success: true, thread_id: '06084af6-7334-43d6-82c0-935f92335a25' }

The caller must own the thread. The id must be a valid UUID — malformed values return 400.

Message Operations

`getThreadMessages`

Fetch paginated history for a thread. Deleted messages are automatically excluded.

Param	Type	Description
`limit`	`number`	Max messages per page (default 50).
`cursor`	`string`	Base64-encoded `created_at` for next page.
`order`	`string`	`asc` (oldest first) or `desc` (newest first).

const { messages, pagination } = await client.messaging.getThreadMessages({
  xAuthToken: customerSession.access_token, // Must own this thread
  id: 'thread-uuid-123',
  limit: 50,
  order: 'desc' // Get newest first
});

Response

{
  "messages": [
    {
      "id": "33e2c744-37a9-42df-a9df-447715526a41",
      "message_content": "Thanks! Also, can I add gift wrapping to this order?",
      "message_type": "text",
      "sender_type": "customer",
      "sender_id": "88ad3683-d291-4c70-8f8b-9903a42bde1b",
      "sender_name": "Jane Doe",
      "attachments": [],
      "metadata": {},
      "message_status": "sent",
      "read_at": null,
      "is_edited": false,
      "is_deleted": false,
      "created_at": "2026-06-20T11:29:02.467216+00:00",
      "updated_at": "2026-06-20T11:29:02.467216+00:00"
    }
  ],
  "pagination": { "limit": 50, "next_cursor": null, "has_more": false }
}

Only the thread’s owning customer (or a Secret Key holder) can read its messages.

`sendMessage` 🔒

Reply to an existing conversation.

await client.messaging.sendMessage({
  xAuthToken: customerSession.access_token, // Must own this thread
  id: 'thread-uuid-123',
  requestBody: {
    message: "We've received your request and are looking into it."
  }
});
// returns { message: { id: '33e2c744-37a9-42df-a9df-447715526a41', created_at: '2026-06-20T11:29:02.467216+00:00' } }

The caller must own the thread. Returns 201 with the newly persisted message body on success.

`editMessage` 🔒

Update the content of one of the customer’s own messages. Sets is_edited: true and records edited_at. Works with a publishable key plus the customer’s xAuthToken (a customer-self write, same browser-origin pattern as cart/wishlist) — the session token proves ownership of the message.

await client.messaging.editMessage({
  xAuthToken: customerSession.access_token, // Must be the original sender
  id: 'cc64ce9a-51ba-4860-ba1a-85f14899f5bf',
  requestBody: {
    message_content: "Thanks! Also — can I add gift wrapping and a note?"
  }
});

Response

{
  "message": {
    "id": "cc64ce9a-51ba-4860-ba1a-85f14899f5bf",
    "message_content": "Thanks! Also — can I add gift wrapping and a note?",
    "is_edited": true,
    "edited_at": "2026-06-21T10:16:33.064+00:00",
    "updated_at": "2026-06-21T10:16:33.082663+00:00"
  }
}

You can only edit or delete messages the customer personally authored. Store and system messages cannot be modified.

`deleteMessage` 🔒

Soft-deletes one of the customer’s own messages. The message is hidden from list responses but retained for audit trails. Works with a publishable key plus the customer’s xAuthToken (the session token proves ownership). Returns success, the message_id, and the deleted_at timestamp.

await client.messaging.deleteMessage({
  xAuthToken: customerSession.access_token, // Must be the original sender
  id: 'cc64ce9a-51ba-4860-ba1a-85f14899f5bf'
});
// returns { success: true, message_id: 'cc64ce9a-51ba-4860-ba1a-85f14899f5bf', deleted_at: '2026-06-21T10:16:33.419Z' }

Same ownership check as editMessage — you can only delete a message you authored. Soft delete only; the row is retained for audit.

`createConversation` 🔒

Initiate a new support ticket with an initial message.

const { thread, message } = await client.messaging.createConversation({
  xAuthToken: customerSession.access_token, // Required when body.customer_id is supplied
  requestBody: {
    customer_id: 'cust_123', // Must match token claim
    customer_name: 'Jane Doe',
    customer_email: 'jane@tybritelabs.com',
    subject: "Missing Item - Order #8821",
    message: "My package arrived but the headphones were missing.",
    priority: 'high',
    thread_type: 'order_inquiry',
    order_id: 'order-uuid-abc',  // Optional: link to an order
    product_id: 'product-uuid'   // Optional: link to a specific product
  }
});

Response

{
  "thread": {
    "id": "06084af6-7334-43d6-82c0-935f92335a25",
    "subject": "Missing Item - Order #8821",
    "status": "active",
    "priority": "high",
    "thread_type": "order_inquiry",
    "order_id": "order-uuid-abc",
    "product_id": null
  },
  "message": {
    "id": "c423c11e-ab5f-40ab-8e17-429a39710d60",
    "created_at": "2026-06-20T11:28:58.245993+00:00"
  }
}

Whenever body.customer_id is supplied, it must match the customer_id on xAuthToken. Returns 201 with both the new thread and the initial message.

thread_type is inferred when it is not supplied: order_inquiry when order_id is present, product_inquiry when product_id is present, and general otherwise. The response echoes the resolved thread_type along with order_id and product_id, so a storefront can confirm the classification its own request produced without a follow-up read.

Data Schemas

`Thread` Structure

Field	Type	Description
`id`	`uuid`	Unique thread identifier.
`subject`	`string`	Thread title/topic.
`status`	`enum`	`active`, `resolved`, `closed`, `escalated`, `pending`.
`priority`	`enum`	`low`, `normal`, `high`, `urgent`.
`is_archived`	`boolean`	Hidden from main list.
`is_muted`	`boolean`	Notifications disabled.
`is_pinned`	`boolean`	Always at top of list.
`unread_count_store`	`number`	Messages awaiting store reply.

`Message` Structure

Field	Type	Description
`id`	`uuid`	Unique message identifier.
`message_content`	`string`	The text body.
`sender_type`	`enum`	`customer`, `store`, `system`.
`is_edited`	`boolean`	Whether content was changed.
`is_deleted`	`boolean`	Whether message is soft-deleted.

Performance Tip: When building a chat UI, use getThreadMessages with order: 'desc' to load the most recent activity first, then use the next_cursor to load history as the user scrolls up.

Realtime messaging

A thread’s new messages arrive as they are sent over a WebSocket, rather than on the interval a getThreadMessages poll would impose. The subscribeToThread helper is exported from the SDK package root and uses the runtime’s built-in WebSocket, so it runs on browsers, Deno, Bun, and Node 22+ with no additional dependency.

`subscribeToThread`

Opens a WebSocket to the thread and calls onMessage for every new message — including the store’s replies — as it arrives. Pass your publishable key plus one customer credential (the signed-in customer’s session token, or a bring-your-own-auth assertion). It returns an unsubscribe function.

import { subscribeToThread } from '@tybrite-labs/sdk';

const unsubscribe = subscribeToThread({
  apiKey: 'tybrite_pk_live_...',
  threadId,
  authToken: customerSession.access_token, // a signed-in Galactic Core customer
  onMessage: (message) => {
    console.log('New message:', message);
  },
  onPresence: ({ type, participant, participants }) => {
    // Someone joined or left THIS conversation.
    console.log(type, participant, participants);
  },
});

// later, when leaving the conversation:
unsubscribe();

Option	Type	Description
`apiKey`	`string`	Your publishable key (`tybrite_pk_*`).
`threadId`	`string`	The conversation to subscribe to.
`authToken`	`string`	The signed-in customer’s session token. Supply this or `externalAuth`.
`externalAuth`	`string`	A signed bring-your-own-auth identity assertion. Supply this or `authToken`.
`onMessage`	`(message) => void`	Called with each new message as it arrives.
`onPresence`	`({ type, participant, participants }) => void`	Optional — called when a participant joins (`type: 'join'`) or leaves (`type: 'leave'`) this conversation. `participants` is the current connected set (each `{ pid, role }`). Use it for a “seller is online” indicator.
`onTyping`	`({ participant, isTyping }) => void`	Optional — the other participant started/stopped typing. Ephemeral (never stored).
`onRead`	`({ participant, at }) => void`	Optional — the other participant read the conversation (a “seen” receipt); `at` is when.
`onClose`	`({ code, reason }) => void`	Optional — called if the connection closes.
`baseUrl`	`string`	Optional — defaults to `https://api.tybritelabs.com`.

The value subscribeToThread returns is a callable unsubscribe function (call it to disconnect) that also carries two senders for publishing your own state:

const sub = subscribeToThread({ /* …options… */ });
sub.sendTyping(true);   // tell the other participant you're typing (call sendTyping(false) to stop)
sub.markRead();         // mark the conversation read — sends a live "seen" cue AND persists it
sub();                  // unsubscribe / disconnect

markRead() both sends the instant “seen” cue over the socket and persists your read position via POST /v1/messaging/threads/{id}/read, so the receipt survives a reconnect. The connection is authorized server-side: the customer credential is validated and confirmed to be the thread’s participant before the socket is accepted, so a customer only ever receives their own thread’s messages. The same call works for both Galactic-Core-authenticated customers (pass authToken) and bring-your-own-auth customers (pass externalAuth).

This is a WebSocket, not a request that counts toward your monthly request quota.

Raw WebSocket protocol (without the SDK)

If you’re not using the TypeScript SDK — a mobile app, another language, or your own client — connect to the WebSocket directly and speak the frame protocol below. Everything the subscribeToThread helper does (messages, presence, typing, read receipts) is available on the raw socket. Connect (browsers/WS handshakes can’t set headers, so credentials go in the query string):

wss://api.tybritelabs.com/v1/messaging/threads/{threadId}/subscribe
  ?api_key=tybrite_pk_live_...
  &auth_token=<customer session token>      # OR:
  &external_auth=<bring-your-own-auth assertion>

The server validates the credential + participant membership before accepting the socket, then keeps it open. All frames are JSON strings, except the heartbeat (a bare ping/pong). Server → client frames (things you receive):

`type`	`payload`	Meaning
`message.created`	`{ thread_id, message }`	A new message (yours or the store’s).
`presence.join`	`{ participant: { pid, role }, participants: [...] }`	Someone connected to this conversation; `participants` is the current set.
`presence.leave`	`{ participant, participants }`	Someone disconnected.
`presence.typing`	`{ participant: { pid, role }, is_typing }`	The other party started/stopped typing.
`presence.read`	`{ participant, at }`	The other party read the conversation (`at` = ISO timestamp).

Client → server frames (things you send):

Frame	Purpose
`ping` (bare string)	Heartbeat; the server replies `pong`. Send every ~25s to keep the connection alive.
`{ "type": "typing", "payload": { "is_typing": true } }`	Publish your own typing state (send `false` when you stop). Ephemeral — never stored.
`{ "type": "read", "payload": { "at": "<ISO>" } }`	Publish a live “seen” cue. Also call `POST /v1/messaging/threads/{id}/read` to persist your read position so it survives a reconnect.

pid is the participant id (the shopper’s customer id, or store for the merchant); role is customer or store. Presence is per-conversation — it reflects who’s connected to this thread, not global online state. Build a “seller is online” dot from presence.join/leave, a typing bubble from presence.typing, and read ticks from presence.read.

Response Codes

Code	Meaning
`200`	Success on reads, `updateThread` patches, and `markThreadRead`.
`201`	Success on `createConversation` and `sendMessage` — a new resource was persisted.
`400`	Invalid request body, or a malformed UUID supplied to `markThreadRead` (or any thread/message ID path param).
`401`	Missing or invalid `xAuthToken`, or missing/invalid API key.
`403`	Customer token does not own the target thread or message.
`404`	Thread or message not found (or filtered out by store scoping).
`429`	Rate limit exceeded.
`500`	Internal server error — safe to retry idempotent reads.

Get Started

Core Commerce

Discovery

Checkout & Logistics

Marketplace

B2B (Wholesale)

Account & Support

System & Store

Integrations

Security Model

Thread Discovery & Filtering

`listThreads`

Computing total unread

`getThread`

`updateThread` 🔒

`markThreadRead` 🔒

Message Operations

`getThreadMessages`

`sendMessage` 🔒

`editMessage` 🔒

`deleteMessage` 🔒

`createConversation` 🔒

Data Schemas

`Thread` Structure

`Message` Structure

Realtime messaging

`subscribeToThread`

Raw WebSocket protocol (without the SDK)

Response Codes

​Security Model

​Thread Discovery & Filtering

​listThreads

​Computing total unread

​getThread

​updateThread 🔒

​markThreadRead 🔒

​Message Operations

​getThreadMessages

​sendMessage 🔒

​editMessage 🔒

​deleteMessage 🔒

​createConversation 🔒

​Data Schemas

​Thread Structure

​Message Structure

​Realtime messaging

​subscribeToThread

​Raw WebSocket protocol (without the SDK)

​Response Codes

Security Model

Thread Discovery & Filtering

`listThreads`

Computing total unread

`getThread`

`updateThread` 🔒

`markThreadRead` 🔒

Message Operations

`getThreadMessages`

`sendMessage` 🔒

`editMessage` 🔒

`deleteMessage` 🔒

`createConversation` 🔒

Data Schemas

`Thread` Structure

`Message` Structure

Realtime messaging

`subscribeToThread`

Raw WebSocket protocol (without the SDK)

Response Codes