Handle server messages

WebSocket server messages are JSON objects with a type field. Handle messages as they arrive rather than waiting for a single full answer.

`info`

An info message reports progress and can provide identifiers:

{
  "type": "info",
  "threadId": "[THREAD_ID]",
  "messageId": "[MESSAGE_ID]"
}

Save threadId for follow-up questions. Save messageId if your implementation supports feedback for a specific answer. Identifiers can also arrive in a delta or response message, so update your stored values whenever they are present.

`delta`

A delta message contains the next part of the answer:

{
  "type": "delta",
  "text": "Our return policy allows returns within",
  "threadId": "[THREAD_ID]",
  "contextId": "[CONTEXT_ID]",
  "messageId": "[MESSAGE_ID]"
}

Append each text value to a buffer for the current question and update the assistant message in the interface. A client must also handle a delta message without text by treating the value as an empty string.

`response`

A response message contains the final answer metadata and, where no deltas were sent, the complete answer:

{
  "type": "response",
  "threadId": "[THREAD_ID]",
  "messageId": "[MESSAGE_ID]",
  "answer": "",
  "confidence": "high",
  "confidenceScore": 0.95,
  "sources": [
    {
      "url": "https://example.com/returns",
      "title": "Return policy",
      "score": 0.98
    }
  ],
  "originalQuestion": "What is your return policy?",
  "rewrittenQuestion": "What is the return policy?",
  "questionValidation": "valid"
}

After a streamed answer, answer is often an empty string. Use the accumulated delta text in that case. If no deltas were received, use answer:

function mergeAnswer(streamedAnswer, responseAnswer) {
  return streamedAnswer.length > 0 ? streamedAnswer : (responseAnswer ?? '');
}

Render sources and other metadata from the response message after applying this rule. Do not replace already-rendered streamed text with an empty answer value.

confidence can be high, medium, or low. The corresponding score ranges are approximately:

high: 0.7–1.0;
medium: 0.4–0.69; and
low: 0.0–0.39.

Treat confidence as guidance rather than a guarantee of accuracy. Keep source links available so visitors can verify important information.

When questionValidation is invalid, the agent returns its configured default response instead of generating an answer. An invalid or default response can still arrive in a delta and/or answer, so use the same merge rule.

`complete`

A complete message indicates that processing has finished:

{
  "type": "complete",
  "message": "Search completed successfully!"
}

Clear the per-question streaming buffer and allow the visitor to submit another question. You can re-enable input after the response message if your interface should allow input before complete arrives, but do not submit a second question until your client has finished handling the current turn.

`error`

An error message indicates that the current turn could not be completed:

{
  "type": "error",
  "error": "Description of what went wrong",
  "step": "generateAnswer"
}

If step is cancelled, the previous in-flight turn was superseded. Ignore this message and continue handling the current turn. For other errors, discard partial answer text, end the current loading state, and show a useful retry message. Do not show raw service errors, session IDs, DXP Organization IDs, or internal diagnostic details to visitors.

Help Center

Menu