How It Works
The complete bot pipeline: from receiving a WhatsApp message to the bot responding automatically.
How It Works
When a client sends you a message via WhatsApp, Trochai's bot runs an intelligent processing pipeline that takes just a few seconds. This page explains each stage of the process.
Pipeline overview
The bot follows these steps every time a client sends a message:
Message reception
Meta (WhatsApp) sends the message to Trochai through a secure webhook. The system validates message authenticity using HMAC signature verification and stores it in the database.
Message batching (debounce)
Instead of responding to each individual message, the bot waits briefly to group consecutive messages. This is important because many people send multiple messages in a row. The system waits for 15 seconds of silence or a maximum of 1 minute from the first message to create a complete "batch."
Batch processing
An automated process checks every minute for batches that are ready to process. When it finds a ready batch, it concatenates all messages and sends them to the AI pipeline.
Status verification
Before processing, the bot verifies:
- That the bot is enabled at the global level (organization settings)
- That the bot is enabled for that specific conversation
- That the organization has available AI messages in their plan
Intent classification
The bot analyzes the client's message and determines what they want to do. It classifies the message into one of 8 possible intents: search for a property, schedule a visit, ask about financing, etc.
If the bot is not confident about the intent (confidence below 70%), it automatically escalates the conversation to a human agent.
Filter extraction and search
For property-related intents, the bot extracts search criteria mentioned by the client (location, price, bedrooms, property type) and runs a hybrid search combining structured filters with semantic search.
Response generation
With the classified intent, search results, and conversation history, the bot generates a natural response in Spanish (or English, depending on configuration). The response includes property details with links, project information, and follow-up questions.
WhatsApp delivery
The response is sent to the client through Meta's WhatsApp API. It is also saved in the database as a bot-sent message, visible in the inbox.
Debounce: Why the bot waits before responding
It is very common for clients to send messages like this:
Hi I'm looking for a house In Escazu With 3 bedrooms
Without the debounce system, the bot would respond 4 times to each individual message. With debounce, the bot waits for the client to finish typing and groups everything into a single intelligent request.
How debounce works:
| Parameter | Value | Description |
|---|---|---|
| Silence window | 15 seconds | If the client doesn't send another message in 15 seconds, the batch is considered complete |
| Maximum wait | 1 minute | Maximum time from the first message. If the client keeps typing, the batch is processed anyway |
| Check frequency | Every minute | An automated process checks for batches ready to process |
While the bot is collecting messages, a "collecting messages..." indicator appears in the inbox. When it starts generating the response, the indicator changes to "typing..." so agents know the bot is working.
"Typing..." indicator in WhatsApp
As soon as the bot starts processing a client's message, Trochai sends WhatsApp a "typing..." indicator that the client sees in their chat — the same one shown when a real person is typing. This confirms that their message was received and that a reply is on the way.
- Shown for every bot reply, before intent classification begins.
- Stays visible until the bot sends its response (up to ~25 seconds, per Meta's limit).
- Does not consume AI credits and cannot be turned off individually — it's part of the bot's standard behavior.
AI Engine
The bot uses OpenAI (GPT) as the primary engine for generating responses, and the text-embedding-3-small model to create semantic search vectors (embeddings). If OpenAI experiences temporary issues, the system automatically switches to an alternative provider to maintain uninterrupted service.
Conversation context
The bot maintains conversation context to give coherent responses. In each interaction, the bot:
- Reads the last 10 messages from the conversation history
- Distinguishes between messages from the user, the bot, and human agents
- Uses the history to understand context (for example, if the client already asked about a specific property)
This enables natural interactions like:
Client: I'm looking for an apartment in Escazu Bot: [shows 3 options] Client: Does the second one have parking? Bot: [responds about the second apartment]
Responses optimized for WhatsApp
Bot responses are optimized for the WhatsApp experience:
- Controlled length: Maximum ~500 characters to maintain readability
- Compatible formatting: Only uses bold (WhatsApp-compatible), no complex markdown
- Direct links: Includes links to property and project detail pages
- Friendly tone: Uses emojis moderately to make the conversation more natural
Bot security
The bot includes multiple security layers:
- Anti-prompt injection: The bot ignores manipulation attempts in client messages (such as instructions to change its behavior)
- Data isolation: The bot only accesses your organization's properties and data. It never shares information between organizations
- Token limits: Client messages are truncated to prevent abuse
- Data-based responses: The bot only recommends properties that exist in your inventory and never fabricates information
Flow diagram
WhatsApp → Webhook → HMAC Validation → Store message
↓
Add to batch (debounce)
↓
Cron (every minute) processes ready batches
↓
Check bot enabled + AI limits
↓
Classify intent (8 types)
↓
┌──────────────────────────────────┐
│ Based on intent: │
│ - Search properties/projects │
│ - Schedule visit │
│ - Answer general question │
│ - Escalate to human agent │
└──────────────────────────────────┘
↓
Generate response with AI
↓
Send via WhatsApp + save to DBNext steps
- Bot intents -- The 8 types of messages the bot recognizes
- Knowledge base -- Hybrid search and embeddings
- Configuration -- Adjust bot behavior