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:

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.


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

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.