BotSailor AI Agents are specialized AI assistants that can understand customer conversations, use your business knowledge, and take real actions automatically.
You can create different agents for different responsibilities, such as:
| AI Agent | Example Responsibilities |
|---|---|
| Sales Agent | Product questions, pricing, recommendations, lead conversion |
| Support Agent | Order status, shipping, refunds, customer issues |
| Lead Qualification Agent | Collect and qualify customer information |
| Order Agent | Order lookup, cancellation, delivery information |
| Appointment Agent | Booking and appointment-related conversations |
Instead of forcing one AI assistant to handle everything, BotSailor lets you build specialized agents and route each conversation to the right one.
BotSailor AI Agents can work across WhatsApp, Facebook Messenger, Instagram, Telegram, and Webchat.
What Makes Up a BotSailor AI Agent?
| Component | Purpose |
|---|---|
| System Prompt | Defines the agent's role, behavior, instructions, and available actions |
| Knowledge Campaign | Gives the agent access to FAQs, URLs, documents, and business knowledge |
| Actions | Allows the agent to perform real operations inside BotSailor and connected systems |
| Agent Configuration | Controls which agents are active and how conversations are routed |
The AI Agent decides what should be said and what action should happen.
BotSailor executes the actual action.
For example:
Customer asks for order status → AI Agent understands the request → BotSailor retrieves the Shopify order → AI Agent explains the result to the customer
Create an AI Agent
Go to:
Bot Manager → AI Agents → Create Agent
Configure the following options:
| Field | Description |
|---|---|
| Name | Required. Example: Sales Agent, Support Agent |
| Slug | Optional. Generated automatically from the name if left empty |
| Description | Short internal description of the agent |
| System Prompt | Main instructions and available actions |
| Knowledge Campaign | Optional business knowledge for the agent |
| Status | Active or Inactive |
For example:
| Field | Example |
|---|---|
| Name | Sales Agent |
| Slug | sales-agent |
| Description | Handles product, pricing, and purchase-related conversations |
| Knowledge Campaign | Product & Sales Knowledge |
| Status | Active |
After saving the agent, you must still enable it from Agent Configuration before it can respond to customers.
Write the System Prompt
The System Prompt is the most important part of your AI Agent.
Think of it as instructions you would give to a new team member.
A good prompt should explain:
| Instruction | Example |
|---|---|
| Who the agent is | You are the Sales AI Agent for our store |
| Its responsibility | Help customers choose and purchase products |
| How it should communicate | Be friendly, concise, and professional |
| What it must not do | Never invent pricing, stock, or discounts |
| When to use actions | Search Shopify when customers ask for products |
| When to transfer | Transfer order issues to the Support Agent |
| When to assign a human | Assign support staff when the customer asks for a person |
Example Sales Agent Prompt
You are the Sales AI Agent for our store.
Help customers choose products, understand pricing,
and make purchase decisions.
Be friendly, concise, and accurate.
Never invent prices, stock availability, or discounts.
When customers ask about products, search our Shopify store.
If the customer asks about an existing order,
shipping, refund, or cancellation, transfer the conversation
to the Support Agent.
Add Actions to Your AI Agent
Inside the System Prompt editor, type:
##
BotSailor will show available actions through autocomplete.
For actions connected to a BotSailor resource, BotSailor stores the resource ID.
Example:
##add_label## : 12
##call_http_api## : 5
##transfer_agent## : 18
Some actions do not require an ID:
##shopify_get_order_details##
##mark_as_solved##
Always use the ## autocomplete whenever possible instead of manually entering IDs.
Subscriber & Automation Actions
These actions allow AI Agents to work directly with BotSailor subscriber data and automation features.
| Action | What It Does |
|---|---|
##add_label## : 12 | Adds a selected label to the subscriber |
##remove_label## : 12 | Removes a selected label |
##assign_sequence## : 8 | Starts a BotSailor sequence |
##remove_sequence## : 8 | Removes the subscriber from a sequence |
##save_custom_field## : 42 | Saves information collected from the conversation |
##trigger_bot_flow## : 15 | Triggers a Visual Flow Builder flow |
##call_http_api## : 5 | Calls a configured HTTP API |
For example, a Lead Qualification Agent can collect the customer's name, email, company, or requirement and save the information directly into BotSailor Custom Fields.
An AI Agent can also trigger an existing BotSailor flow or start a follow-up sequence when appropriate.
HTTP API Actions
The HTTP API action allows an AI Agent to retrieve or send information through an API configured in BotSailor.
| Action | Purpose |
|---|---|
##call_http_api## : 5 | Executes the selected mapped HTTP API |
The process works like this:
| Step | What Happens |
|---|---|
| 1 | Customer asks a question requiring external information |
| 2 | AI Agent determines that the HTTP API is needed |
| 3 | BotSailor executes the API |
| 4 | API result is returned to the AI Agent |
| 5 | AI Agent explains the result naturally to the customer |
For example:
Customer: What is the status of ticket #4825?
BotSailor can call your support API, retrieve the ticket information, and let the AI Agent explain the current status.
The agent should summarize API results naturally instead of showing raw JSON to customers.
Human Handoff and AI Agent Transfer
BotSailor supports both AI-to-AI transfer and AI-to-human handoff.
| Action | Purpose |
|---|---|
##assign_human_member## : 335 | Assigns the conversation to a specific team member |
##assign_human_role## : 3 | Assigns it to an available member of a team role |
##transfer_agent## : 18 | Transfers the conversation to another AI Agent |
AI Agent Transfer vs Human Assignment
| Customer Need | Correct Action |
|---|---|
| Needs another AI specialist | ##transfer_agent## |
| Wants a specific human | ##assign_human_member## |
| Wants someone from the support/sales team | ##assign_human_role## |
| Says "I want to talk to a human" | Human assignment |
| Changes from sales question to order support | AI Agent transfer |
Human assignment respects configured business hours.
AI Agents can remain available 24/7.
Avoid Unnecessary Transfers
Simple messages should not cause agents to transfer conversations unnecessarily.
Examples include:
Hi, Hello, Thanks, Okay, Yes, No, emojis, or simple typos.
Transfer only when another specialist is actually required.
Shopify Actions
BotSailor AI Agents can work with a connected Shopify store.
First add the connected store:
##shopify_store## : 12
Then you can give the agent the Shopify actions it needs.
| Shopify Action | What It Does |
|---|---|
##shopify_store## : 12 | Connects the selected Shopify store |
##shopify_get_order_details## | Retrieves live order information |
##shopify_recommend_products## | Searches and recommends products |
##shopify_update_order_tag## : whatsapp-connected | Adds the specified Shopify order tag |
##shopify_cancel_order## | Cancels an order when clearly requested |
Important Shopify Rules
| Rule | Explanation |
|---|---|
| Connect store first | Shopify actions require the Shopify Store action |
| Customer provides order number | Do not use the store ID as the order ID |
| Order lookup is live | Current Shopify information is retrieved when required |
| Product context can be reused | Size/color follow-ups can reuse previous search results |
| Do not invent order tags | Use the exact configured tag |
| Cancel only when requested | Do not cancel an order based on an unclear request |
WooCommerce Actions
WooCommerce works in a similar way.
| WooCommerce Action | What It Does |
|---|---|
##woocommerce_store## : 12 | Connects the selected WooCommerce store |
##woocommerce_get_order_details## | Retrieves live order information |
##woocommerce_recommend_products## | Searches and recommends products |
##woocommerce_update_order_note## : whatsapp-connected | Adds the specified order note |
##woocommerce_cancel_order## | Cancels an order when clearly requested |
The main difference is that WooCommerce uses order notes instead of Shopify order tags.
Conversation Control Actions
These are optional actions. The AI Agent can only use them if you add them to its System Prompt.
| Action | What It Does |
|---|---|
##mark_as_solved## | Marks a completed live chat as resolved |
##block_subscriber## | Blocks genuine spam |
##skip_reply## | Sends no customer reply when a reply is unnecessary |
Important:##block_subscriber## should only be used for genuine spam such as: Scam links, Repeated junk, Bot flooding, Clearly malicious messages.
A legitimate customer should not be blocked simply because they are angry or rude.
Enable and Configure Your AI Agents
Creating an AI Agent does not automatically enable it.
Open:
Agent Configuration
Then configure your agents.
| Configuration | What to Do |
|---|---|
| Active Agents | Enable the agents that should work on this bot |
| Routing Rules | Define which agent handles different customer topics |
| Intent Mapping | Optionally map Training Campaign intents to agents |
| Business Hours | Configure availability rules for human assignment |
Until an AI Agent is enabled here, it will not respond to customers.
Configure Multi-Agent Routing
One of the biggest advantages of BotSailor AI Agents is the ability to create specialized agents that work together.
For example:
| Customer Topic | Assigned Agent |
|---|---|
| Product questions | Sales Agent |
| Pricing | Sales Agent |
| Product recommendations | Sales Agent |
| Order tracking | Support Agent |
| Shipping issues | Support Agent |
| Refund questions | Support Agent |
| Lead qualification | Lead Qualification Agent |
A conversation can also move from one specialist to another.
Example
| Conversation | Agent |
|---|---|
| "I need a black shirt." | Sales Agent |
| Agent searches Shopify | Sales Agent |
| "Do you have XL?" | Sales Agent |
| "Actually, where is my previous order?" | Transfer |
| Order lookup | Support Agent |
| Customer requests a person | Human Support |
This lets businesses build a team of specialized AI Agents rather than relying on one AI assistant for every type of conversation.
Knowledge Campaign
You can attach a Training Campaign to an AI Agent so it can use your business information while answering customers.
A Knowledge Campaign can contain:
| Knowledge Type | Example |
|---|---|
| FAQs | Shipping policy, refund policy, common questions |
| URLs | Website pages and documentation |
| Files | Product guides, manuals, business documents |
| Business Information | Services, pricing rules, company information |
The difference between the System Prompt and Knowledge Campaign is important:
| System Prompt | Knowledge Campaign |
|---|---|
| Defines what the agent should do | Provides information the agent can use |
| Controls behavior | Supplies business knowledge |
| Defines available actions | Supports the answers |
| Higher priority | Secondary to System Prompt instructions |
If information in the Knowledge Campaign conflicts with the System Prompt, the System Prompt takes priority.
Example: Sales and Support AI Agent Setup
Here is a simple example of a Shopify business using two specialized agents.
Sales Agent
You are the Sales AI Agent for our store.
Help customers choose products, sizes, and prices.
Be short, friendly, and accurate.
Never invent stock, prices, or discounts.
Search our Shopify catalog when customers ask for products.
If the customer asks about an existing order,
shipping, refund, or cancellation, transfer to Support.##shopify_store## : 12
##shopify_recommend_products##
##add_label## : 12
##save_custom_field## : 42
##transfer_agent## : 18
Sales Agent Capabilities
| Capability | Action |
|---|---|
| Search products | ##shopify_recommend_products## |
| Add lead label | ##add_label## |
| Save customer information | ##save_custom_field## |
| Transfer order issues | ##transfer_agent## |
Support Agent
You are the Support AI Agent.
Help customers with orders, shipping, tracking, and refunds.
Always check live order information before answering
questions about an order.
If the customer asks to cancel an order,
cancel only after the request is clear.
If the customer requests human assistance,
assign the support team.
Mark the conversation solved when the issue is complete.
Block only genuine spam.##shopify_store## : 12
##shopify_get_order_details##
##shopify_update_order_tag## : whatsapp-connected
##shopify_cancel_order##
##assign_human_role## : 3
##mark_as_solved##
##skip_reply##
##block_subscriber##
Support Agent Capabilities
| Capability | Action |
|---|---|
| Check live orders | ##shopify_get_order_details## |
| Update order tag | ##shopify_update_order_tag## |
| Cancel orders | ##shopify_cancel_order## |
| Assign human support | ##assign_human_role## |
| Resolve completed chats | ##mark_as_solved## |
| Block genuine spam | ##block_subscriber## |
Then configure routing:
| Routing Rule | Agent |
|---|---|
| Product, price, buy, recommendation | Sales Agent |
| Order, shipping, tracking, refund | Support Agent |
Now if a sales conversation changes into an order-support conversation, the Sales Agent can transfer the customer directly to Support.
How AI Agent Actions Work
Shared Inbox
The AI model does not directly execute BotSailor operations.
The process is:
| Step | Process |
|---|---|
| 1 | Customer sends a message |
| 2 | AI Agent understands the request |
| 3 | AI Agent decides whether an action is required |
| 4 | BotSailor executes the action |
| 5 | Results are returned to the AI Agent when required |
| 6 | AI Agent replies naturally to the customer |
For example:
Customer Where is order #12542?
↓
AI Agent Determines that Shopify order lookup is required.
↓
BotSailor Retrieves live Shopify order information.
↓
AI Agent "Your order has been shipped and is currently in transit."
This is what allows BotSailor AI Agents to do more than simply generate text responses.
Best Practices for Writing AI Agent Prompts
| Best Practice | Recommendation |
|---|---|
| Give each agent a clear role | Create specialized agents for different responsibilities |
| Explain when actions should run | Don't rely only on action tags |
| Limit available actions | Give each agent only the tools it needs |
| Use ## autocomplete | Avoid entering incorrect IDs manually |
| Connect ecommerce store first | Add Shopify/WooCommerce store before related operations |
| Use live information | Never invent order status, stock, or API information |
| Avoid raw JSON responses | Let the AI explain API results naturally |
| Control agent transfers | Transfer only when another specialist is required |
| Separate AI and human handoff | Transfer for AI; assignment for humans |
| Never self-transfer | An agent should never transfer to itself |
| Limit transfers | Maximum one AI Agent transfer per customer message |
Test Your AI Agents Before Going Live
Always test your AI Agent with different types of customer messages.
| Test Message | What You Should Verify |
|---|---|
| "Hello" | Agent replies normally without unnecessary transfer |
| "Do you have black shirts?" | Product search works |
| "Does the second one come in XL?" | Conversation context works |
| "Where is my order?" | Agent asks for required order information |
| "My order is #10542" | Live order lookup works |
| "I want to talk to a human" | Human assignment is used |
| Customer changes topic | Correct specialist receives the conversation |
| Spam message | Spam rules work correctly |
| Angry real customer | Customer is not incorrectly blocked |
| Irrelevant message | Skip Reply behaves correctly if enabled |
Complete AI Agent Action Reference
| Category | Action | Purpose |
|---|---|---|
| Subscriber | ##add_label## : 12 | Add label |
| Subscriber | ##remove_label## : 12 | Remove label |
| Automation | ##assign_sequence## : 8 | Start sequence |
| Automation | ##remove_sequence## : 8 | Stop sequence |
| Data | ##save_custom_field## : 42 | Save customer information |
| Automation | ##trigger_bot_flow## : 15 | Trigger visual bot flow |
| Integration | ##call_http_api## : 5 | Execute HTTP API |
| Human | ##assign_human_member## : 335 | Assign specific human |
| Human | ##assign_human_role## : 3 | Assign team role |
| AI Agent | ##transfer_agent## : 18 | Transfer to another AI Agent |
| Conversation | ##mark_as_solved## | Resolve conversation |
| Conversation | ##skip_reply## | Send no reply |
| Conversation | ##block_subscriber## | Block genuine spam |
| Shopify | ##shopify_store## : 12 | Connect Shopify store |
| Shopify | ##shopify_get_order_details## | Retrieve order details |
| Shopify | ##shopify_recommend_products## | Recommend products |
| Shopify | ##shopify_update_order_tag## : whatsapp-connected | Update order tag |
| Shopify | ##shopify_cancel_order## | Cancel order |
| WooCommerce | ##woocommerce_store## : 12 | Connect WooCommerce store |
| WooCommerce | ##woocommerce_get_order_details## | Retrieve order details |
| WooCommerce | ##woocommerce_recommend_products## | Recommend products |
| WooCommerce | ##woocommerce_update_order_note## : whatsapp-connected | Update order note |
| WooCommerce | ##woocommerce_cancel_order## | Cancel order |
Final Thoughts
BotSailor AI Agents combine AI-powered conversations with real business actions.
The complete setup is straightforward:
You can create specialized agents for sales, support, ecommerce, lead qualification, order management, and other customer-facing roles.
These agents can use your business knowledge, save customer information, trigger automations, call external APIs, search products, check orders, transfer conversations to another AI specialist, and assign human team members when necessary.
For the best results, keep every agent focused on a clear responsibility and give it only the actions it actually needs.
With BotSailor's multi-agent system, you are not limited to building a chatbot that simply answers questions.
You can build an AI workforce that understands conversations, takes real actions, and routes every customer to the right specialist.
