Messaging

Subscribe to a thread's new messages in realtime (WebSocket)

Opens a WebSocket connection that streams a conversation’s new messages to you live, with no polling. As soon as either side posts a message, every connected subscriber of that thread receives it.

This is a WebSocket upgrade, not a normal request — send the standard upgrade headers (Upgrade: websocket). The connection is served on the API’s own domain; the server responds 101 Switching Protocols and then pushes one JSON frame per new message:

{ "type": "message.created", "payload": { "thread_id": "…", "message": { … } } }

Authentication. Because a browser WebSocket cannot set request headers, supply the credentials as query parameters on the connection URL (they may also be sent as headers from non-browser clients):

api_key — your publishable key (a publishable key is fine; this is a browser-origin read).
one customer credential, proving the caller owns the thread:
- auth_token — the session token of a customer signed in through Galactic Core (equivalently the x-auth-token header),
- external_auth — a signed identity assertion for a customer authenticated with your own identity provider (equivalently the x-external-auth header), or
- idp_token — a raw token from your own identity provider that Galactic Core forwards to the store’s Auth verifier to validate (equivalently the x-idp-token header).

The server validates the credential and confirms the customer is the thread’s participant before accepting the socket; an unauthorized or non-participant connection is closed. Use the subscribeToThread helper in the SDK to manage the connection (it returns an unsubscribe function), or open the WebSocket yourself.

Send the text frame ping at intervals to keep an idle connection alive; the server replies pong.

GET

messaging

threads

{id}

Subscribe to a thread's new messages in realtime (WebSocket)

curl --request GET \
  --url https://api.tybritelabs.com/v1/messaging/threads/{id}/subscribe \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.tybritelabs.com/v1/messaging/threads/{id}/subscribe"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.tybritelabs.com/v1/messaging/threads/{id}/subscribe', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tybritelabs.com/v1/messaging/threads/{id}/subscribe",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tybritelabs.com/v1/messaging/threads/{id}/subscribe"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.tybritelabs.com/v1/messaging/threads/{id}/subscribe")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "details": "The 'email' field is required"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "This operation requires a secret key. Publishable keys have read-only access."
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this API key. Please slow down and try again shortly.",
    "remaining": 0,
    "reset": 1706198400
  }
}

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred"
  }
}

Authorizations

Authorization

string

header

required

API Key Authentication

Use your API key in the Authorization header:

Authorization: Bearer tybrite_sk_live_YOUR_KEY

Key Types:

Secret Keys (Server-Side Only):

Format: tybrite_sk_live_* (production) or tybrite_sk_test_* (sandbox)
Full read/write access to all endpoints
⚠️ NEVER expose in client-side code or public repositories
Required for: write operations, authentication, payment verification, AI recommendations

Publishable Keys (Client-Safe):

Format: tybrite_pk_live_* (production) or tybrite_pk_test_* (sandbox)
Read-only access (GET requests only, plus POST semantic search)
✅ Safe for client-side JavaScript, mobile apps, and public code
Allowed for: browsing products, search, CMS content, pricing queries

Endpoint-Specific Requirements:

Authentication endpoints (/v1/auth/*): Secret key required
Payment verification (POST /v1/payments/verify): Secret key required
AI Recommendations (POST /v1/recommendations): Secret key required
Semantic Search (POST /v1/search): Both key types allowed (read-only operation)
All write operations: Secret key required
All read operations: Both key types allowed

Using a publishable key for restricted operations returns 403 Forbidden.

Headers

x-auth-token

string

Header form of auth_token, for non-browser clients that can set request headers on the handshake.

x-external-auth

string

Header form of external_auth.

x-idp-token

string

Header form of idp_token.

Path Parameters

string<uuid>

required

The conversation to receive realtime messages for.

Query Parameters

api_key

string

Your publishable key, supplied as a query parameter for the WebSocket handshake (browsers cannot set the Authorization header on a WebSocket). May also be sent as the Authorization: Bearer header from non-browser clients.

auth_token

string

Session token of a customer signed in through Galactic Core. Supply this (or external_auth) to authorize the subscription. May also be sent as the x-auth-token header.

external_auth

string

Signed identity assertion for a customer authenticated with your own identity provider. Supply exactly one customer credential (auth_token, external_auth, or idp_token) to authorize the subscription. May also be sent as the x-external-auth header.

idp_token

string

A raw token from your own identity provider (e.g. a Firebase ID token). Galactic Core forwards it to the store's configured Auth verifier, which validates it and returns the identity. Fail-closed: if the verifier rejects the token or is unreachable, the connection is not authorized. Supply exactly one customer credential (auth_token, external_auth, or idp_token). May also be sent as the x-idp-token header.

Response

Switching Protocols — the WebSocket is established. New-message frames follow on the socket.

Subscribe to a thread's new messages in realtime (WebSocket)

curl --request GET \
  --url https://api.tybritelabs.com/v1/messaging/threads/{id}/subscribe \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.tybritelabs.com/v1/messaging/threads/{id}/subscribe"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.tybritelabs.com/v1/messaging/threads/{id}/subscribe', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tybritelabs.com/v1/messaging/threads/{id}/subscribe",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tybritelabs.com/v1/messaging/threads/{id}/subscribe"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.tybritelabs.com/v1/messaging/threads/{id}/subscribe")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "details": "The 'email' field is required"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "This operation requires a secret key. Publishable keys have read-only access."
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this API key. Please slow down and try again shortly.",
    "remaining": 0,
    "reset": 1706198400
  }
}

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred"
  }
}

Reference

System

Products

Taxonomy

Orders

Payments

Cart & Wishlist

Marketplace

Recommendations

Discovery

Events

Tax

Analytics

Search

Authentication

Customers

Gift Cards

Promotions

CMS

Pricing

Messaging

Shipping

GC Connect

Reviews

Returns

Disputes

B2B

Webhooks

Ingestion

Sandbox

Subscribe to a thread's new messages in realtime (WebSocket)

Authorizations

Headers

Path Parameters

Query Parameters

Response