Bitrix24 Open Channel RAG Chatbot Guide

This guide describes how to implement a Retrieval-Augmented Generation (RAG) chatbot for Bitrix24 Open Channels using an n8n workflow and a webhook-based integration. It explains the complete data flow and component interactions, including webhook handling, event routing, document ingestion, embeddings with Ollama, vector storage in Qdrant, and the retriever plus LLM chain that produces accurate, context-aware responses.

1. Solution Overview

The RAG chatbot architecture combines Bitrix24 Open Channels with an n8n workflow that orchestrates:

• Incoming Bitrix24 webhook events (message, join, install, delete)
• Credential extraction and token validation
• Message processing and routing to a Question & Answer retrieval chain
• Document ingestion, text splitting, embeddings generation, and vector storage in Qdrant
• LLM-based response generation grounded in retrieved documents
• Reply delivery back to Bitrix24 via imbot.message.add

The result is a Bitrix24 chatbot that can answer user questions using your internal knowledge base, with reduced hallucinations and better traceability of where answers come from.

2. Why RAG for Bitrix24 Open Channels

Retrieval-Augmented Generation combines an LLM with an external knowledge source. For Bitrix24 Open Channels (chat, social integrations, or support queues), this provides:

• Grounded answers: Responses are based on your company documentation, not only on the LLM’s pretraining.
• Lower hallucination risk: The LLM is constrained by retrieved context, which can be logged and audited.
• Operational efficiency: Agents and end users get instant access to relevant documents without manually searching.

3. High-level Architecture & Data Flow

At a high level, the n8n workflow processes Bitrix24 events and delegates message content to a RAG pipeline:

1. Bitrix24 sends a webhook event to the n8n Webhook node (Bitrix24 Handler).
2. The workflow extracts credentials and validates tokens.
3. A Switch node routes events by type (message, join, install, delete).
4. For message events, the user message is sent to a QA retrieval chain.
5. The retriever queries Qdrant with embeddings generated by Ollama to obtain relevant document chunks.
6. An LLM (for example Google Gemini) uses this context to generate a grounded answer.
7. The workflow formats the response and calls imbot.message.add to post back to Bitrix24.

A separate subworkflow handles document ingestion and vectorization. It periodically fetches files from Bitrix24 storage, converts them into embeddings, and stores them in Qdrant.

4. Node-by-node Breakdown

4.1 Webhook Node: Bitrix24 Handler

The entry point for all Bitrix24 events is an n8n Webhook node configured as follows:

• HTTP Method: POST
• Path: bitrix24/openchannel-rag-bothandler.php
• Response format: JSON payload

Bitrix24 is configured to send Open Channel and app events to this URL. The node passes the raw request body to downstream nodes where event type, tokens, and payload data are parsed.

4.2 Credentials & Token Validation

After the webhook, a combination of a Set node and an If node handles credential extraction and token validation:

• The Set node stores:
  • CLIENT_ID
  • CLIENT_SECRET
  • Access and application tokens from the incoming Bitrix24 payload
• The If node compares the incoming application token against the expected value. This is used to:
  • Reject unauthorized or malformed calls
  • Prevent abuse of the public webhook URL

On token validation failure, the workflow routes to an Error Response node that returns an HTTP 401 JSON response. This early exit avoids unnecessary calls to the vector store or LLM and protects your infrastructure from unauthorized access.

4.3 Event Routing with Switch Node

Once the request is validated, a Switch node inspects body.event in the incoming payload. Typical values include:

• ONIMBOTMESSAGEADD – user sent a message to the bot
• ONIMBOTJOINCHAT – bot was added to a chat
• ONAPPINSTALL – application was installed
• ONIMBOTDELETE – bot was removed or deleted

The Switch node routes each event type to a dedicated processing branch, for example:

• Process Message for ONIMBOTMESSAGEADD
• Process Join for ONIMBOTJOINCHAT
• Process Install for ONAPPINSTALL
• Optional cleanup logic for ONIMBOTDELETE

This separation keeps the workflow maintainable and makes it easier to extend behavior for specific event types.

4.4 Process Message: RAG Retrieval & QA Chain

The Process Message branch is responsible for extracting message metadata, running the RAG pipeline, and sending the final answer back to Bitrix24.

A typical implementation includes:

• A Function or Set node that extracts from the payload:
  • DIALOG_ID
  • SESSION_ID
  • BOT_ID
  • USER_ID
  • The original user message, often stored as MESSAGE_ORI
• Passing MESSAGE_ORI, along with authentication and domain parameters, into a Question and Answer Chain implemented via n8n nodes that connect to:
  • A vector store retriever backed by Qdrant
  • An LLM (for example Google Gemini) that uses retrieved context

The data flow in this branch is:

1. Take the user message from MESSAGE_ORI.
2. Call the vector store retriever to fetch top-K relevant document chunks from Qdrant.
3. Inject the retrieved context and user question into the LLM chain.
4. Receive a structured JSON response from the LLM that includes DIALOG_ID, AUTH, DOMAIN, and MESSAGE.
5. Use those fields to call imbot.message.add and send the answer back to Bitrix24.

4.5 Embeddings & Vector Store (Qdrant + Ollama)

The RAG pipeline relies on embeddings and a vector database to retrieve relevant context. The example setup uses:

• A document loader (for example a PDF loader) to read files and extract text.
• A Recursive Character Text Splitter to break long documents into overlapping chunks. The overlap is tuned so that each chunk preserves enough context without becoming too large.
• An embeddings model provided by Ollama, using nomic-embed-text to convert each text chunk into a vector representation.
• A Qdrant collection (for example bitrix-docs) as the vector store that persists these embeddings along with metadata.

At query time, the retriever node uses the same embeddings model to embed the user query and then performs a similarity search against the Qdrant collection to find top-K relevant chunks.

5. Subworkflow: Document Ingestion & Vectorization

Document ingestion is handled as a separate subworkflow, which can be scheduled or triggered on demand. This subworkflow performs the following tasks:

• List storages: Uses disk.storage.getlist to enumerate available Bitrix24 storages.
• Locate target folder: Finds the specific folder where source documents are stored and then lists its child items.
• Download files: Retrieves each file and passes it to the Default Data Loader (for example a PDF loader) to extract raw text.
• Split text: Applies the Recursive Character Text Splitter to create overlapping text chunks suitable for retrieval.
• Create embeddings: Calls the Ollama embeddings model (nomic-embed-text) for each chunk.
• Store vectors: Inserts the resulting embeddings into the configured Qdrant collection, attaching metadata such as document identifiers or file paths.
• Move processed files: Moves successfully processed files to a dedicated vector-storage folder to avoid double-processing on subsequent runs.

This separation of concerns makes it easier to manage ingestion independently from the real-time chatbot workflow and simplifies debugging of indexing issues.

6. Prompt Design, Output Format & Safety

The LLM in the RAG chain must produce a response that the workflow can parse reliably. To achieve this, the system prompt is designed to:

• Constrain the LLM to use only retrieved context for answers.
• Instruct the model not to fabricate information when the answer is unknown.
• Enforce a strict JSON output structure.

The workflow expects a JSON object with the following keys:

• DIALOG_ID
• AUTH
• DOMAIN
• MESSAGE

This strict output format is critical. Downstream nodes assume this schema when constructing the imbot.message.add request. If the LLM returns additional text, comments, or a different structure, parsing may fail and the message will not be delivered correctly.

7. Security Considerations & Best Practices

When deploying an n8n-based Bitrix24 RAG chatbot in production, pay particular attention to security and operational safeguards:

• Token validation: Always validate the application token and any access tokens before processing events. Reject requests that do not match expected values.
• Secure secret storage: Store CLIENT_SECRET, application tokens, and other sensitive values in n8n credentials or a secrets manager instead of plain Set nodes.
• Rate limiting: Limit the rate of calls to your embeddings model and Qdrant instance to avoid performance degradation or unexpected costs.
• Data protection: Avoid ingesting or storing personally identifiable information (PII) in the vector store unless you have appropriate compliance and retention controls in place.

8. Deployment Checklist

Use the following checklist when moving this workflow into a stable environment:

1. n8n hosting: Run n8n on a reliable platform such as Docker or n8n Cloud. Ensure HTTPS is configured for webhook endpoints.
2. Webhook registration: Expose the webhook path externally and configure it in your Bitrix24 app installation routine. The Process Install branch typically calls imbot.register to register the bot and its webhook.
3. Vector infrastructure: Provision Qdrant and Ollama (or another embeddings provider) and configure their connection parameters via environment variables or n8n credentials.
4. Initial seeding: Use the ingestion subworkflow to index your company documents into Qdrant and verify that retrieval returns expected results.

9. Testing & Troubleshooting

9.1 Webhook and Message Flow Testing

Before going live, validate the workflow end-to-end using tools like Postman or curl:

• Send a sample ONIMBOTMESSAGEADD event to the webhook URL. Confirm that:
  • The token validation step returns the correct HTTP status (200 for valid, 401 for invalid).
  • The Process Message branch receives MESSAGE_ORI and returns a JSON payload with a populated MESSAGE field.
  • The node responsible for sending responses successfully calls imbot.message.add and the reply appears in Bitrix24.

9.2 Common Issues & How to Address Them

• 401 Invalid token:
  • Verify that the application token in Bitrix24 matches the one stored in n8n.
  • Check that the workflow maps the incoming token from the payload correctly before comparison.
• No documents returned by retriever:
  • Confirm that your Qdrant collection contains vectors for the relevant documents.
  • Increase the topK value in the retriever node to broaden the search.
• Hallucinations or off-topic answers:
  • Strengthen the system prompt to emphasize using only provided context.
  • Increase context size or adjust chunking parameters to provide more relevant text per query.
  • Optionally include source snippets or citations in the MESSAGE field to make grounding more visible to users.

10. Optimization & Advanced Configuration

Once the basic workflow is stable, several parameters can be tuned for better performance and answer quality.

• Chunk size and overlap: Adjust the Recursive Character Splitter configuration to balance:
  • Context completeness (larger chunks, more overlap)
  • Noise and retrieval efficiency (smaller chunks, less overlap)
• topK setting: Tune the number of retrieved chunks (