Skip to main content

Flow: Message Processing

End-to-end sequence for an inbound user message through to bot response. Services: hbf-webchat, Azure Direct Line (current) / open-bot-framework (planned), hbf-bot, hbf-core, hbf-nlp, helvia-rag-pipelines

Sequence Diagram​

Step-by-Step​

  1. Widget init (hbf-webchat → hbf-core): The webchat widget fetches deployment configuration from hbf-core's public API. This returns the token URL, bot ID, and UI settings.

  2. Connection (hbf-webchat → Direct Line or OBF): The widget connects to one of two gateways:

    • Azure Direct Line (current): Obtains a Direct Line token via the configured tokenUrl, then opens a WebSocket stream.
    • OBF (planned, not yet in use): Will call POST /v3/directline/tokens/generate on open-bot-framework, then open a WebSocket on port 1992.

  3. User message (webchat → gateway → hbf-bot): The user's message is wrapped in a Bot Framework activity with channel data (webchat_id, domain, version). Azure DL delivers it via its webhook mechanism. When OBF is enabled, it will forward as an HTTP POST to the bot's configured endpoint.

  4. Agent config (hbf-bot → hbf-core): hbf-bot loads the bot deployment via hbf-core-api, retrieving the agent's workflow definition, NLP pipeline configuration, and subscriber state.

  5. NLP processing (hbf-bot → hbf-nlp → helvia-rag-pipelines): hbf-bot sends the user's query to hbf-nlp. hbf-nlp resolves the pipeline type (RAG, NLP spec, or Dialogflow) and routes accordingly. For RAG queries, hbf-nlp calls helvia-rag-pipelines which embeds the query, performs vector search, and generates a response.

  6. Outbound (hbf-bot → gateway → webchat): hbf-bot constructs the response activity. With Azure DL (current), it uses the Bot Framework ConnectorClient. When OBF is enabled, it will POST to OBF's serviceUrl which streams the reply via WebSocket.

Variant: Other Channels​

For non-webchat channels (Facebook, WhatsApp, Viber, Slack, Teams, Instagram):

  • Step 1-2 are replaced by the channel's own connection mechanism.
  • Step 3: The channel platform sends a webhook directly to hbf-bot's channel-specific endpoint (e.g., POST /api/fb-events).
  • Steps 4-5 are identical.
  • Step 6: hbf-bot sends the response via the channel's API (Facebook Graph API, Viber API, etc.) instead of Direct Line.

Contracts​

hbf-bot → hbf-nlp (POST /tenants/{tenantId}/process):

Request:  { "query": "string", "subscriberId": "string", "sessionId": "string", "language": "string", "messageId": "string", "detectLanguage": true, "saveMissedQuestion": true, "variables": {} }
Response: { "intent": "string", "entities": [], "response": "string", "pipelineResults": {} }

hbf-nlp → helvia-rag-pipelines (POST /pipelines/{pipelineId}:process):

Request:  { "query": "string", "query_language": "en", "session_id": "string", "max_results": 5, "previous_messages": [{ "role": "user", "content": "..." }], "parameters": {} }
Response: { "answer": "string", "sources": [], "confidence": 0.95 }