AI Agents & Generative Auto-Replies
The AI Agent module acts as an asynchronous, non-blocking fallback responder to inbound WhatsApp messages. It automatically replies to customer inquiries using large language models, but only when appropriate.
When It Triggers
The AI Auto-Reply attempts to trigger every time a new inbound WhatsApp message arrives via the Meta Webhook. However, to prevent double-texting customers or interfering with your human support team, it has a strict set of "stand-down" rules.
The AI will silently ignore an inbound message if ANY of the following are true:
- Billing/Config: The workspace hasn't enabled AI Agents, or the current billing tier doesn't support them.
- Flow Conflict: You have an active deterministic automation flow (like a Chatbot Builder flow listening for
new_message_receivedorkeyword_match). Deterministic flows always take priority over generative AI. - Human Intervention: A human agent has already claimed the conversation.
- AI Hand-off: The AI previously decided it couldn't answer and "handed off" the conversation to a human.
- Reply Cap Reached: The conversation has reached the maximum allowed AI replies per thread (configured in settings) to prevent runaway token loops.
How it Works (The Execution Flow)
If the message passes all the gates above, the module executes the following sequence in the background:
- Context Building: It pulls the recent chat history so the AI has context on what was previously discussed in the thread.
- Knowledge Retrieval: It looks at the latest message and attempts to fetch relevant information from the organization's Knowledge Base.
- Prompt Assembly: It builds a master system prompt combining your custom instructions, the retrieved knowledge, and the conversation history.
- LLM Generation: It calls the configured AI Provider (OpenAI, Gemini, OpenCode Zen, Anthropic) to generate the response.
- Handoff Detection: If the model determines it does not have enough information to answer, it will trigger a handoff. The system permanently disables auto-reply for that specific conversation thread and leaves the message unread for a human to pick up.
- Atomic Slot Claiming: Before sending the message, the system uses an atomic database lock to increment the reply counter, guaranteeing it never overshoots your reply cap even under heavy concurrent load.
- Message Dispatch: Finally, it dispatches the outbound message through the Meta WhatsApp Cloud API.
Note: This entire pipeline runs asynchronously inside a Background Worker. This is critical because AI generation can sometimes take several seconds, and processing it in the background ensures your webhook immediately returns a successful response to Meta, preventing timeout penalties!