In-app assistant

travel.tech's in-app assistant is a chat surface where a traveler can search,
get trip help, and escalate to a live agent. It is reached two ways: a
WebSocket gateway at /v1/ws for real-time streaming, and an HTTP
surface under /v1/assistant/* as a fallback for clients that cannot hold
a WebSocket connection. Neither surface appears in the
OpenAPI reference — /v1/ws is not an HTTP
route at all, and the HTTP fallback routes are intentionally thin wrappers
around the same session/orchestrator logic the WebSocket gateway uses. This
guide is the only place both are documented.

Authentication

Both surfaces use the same traveler bearer JWT as
every other /v1 endpoint. The WebSocket gateway carries it differently,
since a WS handshake has no per-message header:

1. The client opens the connection with no credential in the URL or
   handshake.
2. The first frame the client sends must be an auth event carrying
   the JWT. The server waits up to 5 seconds for it.
3. The server verifies the token and closes the connection if it is
   missing, malformed, or the first frame is anything other than auth.

The HTTP fallback routes take the JWT the normal way, as
Authorization: Bearer <token>. Consumer HMAC signing
(Authentication § Consumer HMAC) applies to the
HTTP routes as usual; the WebSocket handshake itself is not HMAC-signed,
only the auth frame's JWT is checked.

WebSocket protocol (/v1/ws)

Connecting and authenticating

const ws = new WebSocket("wss://api.travel.tech/v1/ws");

ws.addEventListener("open", () => {
  ws.send(JSON.stringify({ event: "auth", data: { token: travelerJwt } }));
});

ws.addEventListener("message", (raw) => {
  const { event, data } = JSON.parse(raw.data);
  if (event === "auth.ok") {
    ws.send(JSON.stringify({ event: "session.start", data: {} }));
  }
  // ... dispatch on `event` below
});

A failed authentication closes the socket with one of two codes:

Client → server events

ping is also accepted at any time and answered with pong.

Server → client events

Worked example: sending a message

// client -> server
{"event": "message.send", "data": {"sessionId": "sess_123", "content": "What's my next trip?"}}

// server -> client (zero or more, while the reply is composed)
{"event": "message.stream.token", "data": {"sessionId": "sess_123", "delta": "Your next trip is..."}}

// server -> client (exactly one, the finished turn)
{
  "event": "message.new",
  "data": {
    "id": "msg_456",
    "sessionId": "sess_123",
    "role": "ASSISTANT",
    "content": "Your next trip is Milan → London, departing May 25.",
    "richCards": [
      {
        "type": "trip_ref",
        "data": {
          "tripId": "018f2c3e-1234-7abc-8def-000000000001",
          "name": "Milan → London",
          "status": "upcoming",
          "temporalClassification": "upcoming",
          "startsAt": "2026-05-25T08:00:00Z",
          "endsAt": "2026-05-25T10:00:00Z",
          "destinations": ["London"],
          "stageCount": 1,
          "bookingCount": 1
        }
      }
    ],
    "toolCalls": [],
    "searchContext": [],
    "attachments": [],
    "createdAt": "2026-05-25T10:30:00Z",
    "turnId": "turn_789"
  }
}

richCards is a discriminated union — flight_option, car_option,
stay_option, stay_fare, train_option, alert, trip_ref,
booking_ref, travel_document, or booking_confirmation — each carrying
whichever domain payload matches its type. A stay_fare card is one rate
of one property: the rate fields of POST /v1/stays/fares plus the
property's propertyId, searchSolutionId, checkIn and checkOut. A
booking_confirmation card is a booking waiting on the traveler: it carries
taskId, the Confirm and Cancel options, a summary of what would be
booked, and expiresAt when a deadline is set. Render each card type
distinctly; do not assume every message carries the same card shape.

WebSocket error codes

Sent on error (connection-level) or message.error (turn-level) frames:

HTTP fallback (/v1/assistant/*)

Use this surface only when a client genuinely cannot hold a WebSocket
connection. It reuses the same session and orchestrator state as /v1/ws,
so a session started over one transport is fully visible and continuable
over the other.

curl -X POST "$TRAVELTECH_BASE_URL/v1/assistant/messages" \
  -H "Authorization: Bearer $TRAVELER_JWT" \
  -H "TravelTech-Consumer: $CONSUMER" \
  -H "TravelTech-Timestamp: $TIMESTAMP" \
  -H "TravelTech-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "sess_123", "content": "Show me my next trip"}'

The response body is the same Message shape as the WebSocket message.new
frame's data.

Requesting a live-agent handoff

Either surface can escalate a session to a human agent. Over WebSocket,
send handoff.request; over HTTP, POST /v1/assistant/handoffs with
action: "request". Once a handoff is active, the live agent's replies
arrive as handoff.message (WebSocket) or are visible through
GET /v1/assistant/sessions/{sessionId}/handoffs (HTTP). Use
action: "callback" to ask the agent to phone the traveler instead of
continuing in text.

Reporting issues

This page is maintained by the BizAway integration team. To request changes
or report an error, contact your BizAway integration contact. Edits made
directly in the ReadMe dashboard are overwritten on the next publish.