Automate conversations, qualify opportunities and book meetings on WhatsApp
AI Agents let you automate specific states of your sales process, so your team can focus on the conversations where they add the most value.
Available 24/7, agents answer questions, collect information, qualify opportunities and stay with each contact until a person needs to step in.
1. What is an AI Agent?
An AI Agent is a virtual assistant that works inside WhatsApp and follows the rules of your sales process.
Its job is to help contacts move forward in their buying journey while it collects information and keeps your CRM up to date.
Main capabilities
- Answer frequent questions using your business information.
- Qualify contacts with structured questions.
- Collect relevant information from contacts.
- Understand voice notes (they are transcribed automatically).
- Reply in the contact's language.
- Update fields and records in Vixiees.
- Move contacts to another state, in the same or another Sales Brain (Playbook), when the conditions you write in its instructions are met.
- Book meetings with members of your team.
- Send automatic follow-up messages when the contact stops replying.
- Hand conversations over to a person when needed.
2. How it works
The contact starts a conversation
When a contact writes on WhatsApp, the agent replies within seconds. If the contact sends several messages in a row, the agent waits a moment to read them all and replies once.
Replies are short, natural messages in the contact's language.
The agent collects information
Depending on the state of the process, it asks the questions needed to reach the defined objective.
The agent takes actions
Depending on the configuration, it can:
- Qualify a contact.
- Collect information.
- Book meetings or a call.
- Update contact data.
- Answer frequent questions.
The agent hands the conversation over
When the objective is met or a person needs to step in, the conversation goes to a member of your team.
If the state's instructions say that, in a specific case, the contact must go to another state, the agent moves it as soon as that condition is met. If the AI also acts in the destination state, the conversation continues there with that state's instructions.
3. Common use cases
Contact qualification
Automate the initial information gathering before a salesperson steps in. For example: available budget, service of interest, urgency, location, company size.
Meeting booking
Identify qualified opportunities and coordinate meetings with your sales team by sending your meeting tool once the opportunity is qualified.
After-hours service
Answer questions when your team isn't available.
Opportunity recovery
Pick up conversations with contacts who get in touch again after a period of inactivity. When a contact stops replying mid-conversation, you can also send automatic follow-ups through workflows to reactivate it before it closes.
Recurring sales
Pick up conversations with contacts who buy your products or services on a recurring basis.
4. What an AI Agent needs to work
Knowledge Base
The Knowledge Base holds all the information the agent uses to answer questions: products and services, prices, frequent questions, policies, internal processes and sales information.
Supported formats: PDF (up to 35 MB) and text or Markdown files (up to 512 KB). After you upload or update a document, the agent has the new information as soon as syncing finishes (usually a few seconds).
| Recommendation | Importance |
|---|---|
| Keep information up to date | High |
| Avoid content in tables | High |
| Organize content by sections | High |
| Avoid contradictory information | High |
| Consolidate information in a few documents | Medium |
Fields
Fields let the agent read or update information about contacts. The agent uses them both ways:
- Reading: it checks fields before asking, so it doesn't ask for data the contact already gave.
- Writing: when the contact shares a piece of data during the conversation, the agent saves it automatically in the matching field.
For this to work, the field must exist in the account and the state's instructions must say which data to collect. If you set up the agent with the Agent Builder, this check is done automatically.
| Field | Example |
|---|---|
| juan@email.com | |
| Phone | +34 600 123 456 |
| Budget | €5,000 |
| Interest | Training |
| Urgency | High |
Objective
Every agent needs a clearly defined objective, for example: qualify a contact, book a meeting, get specific information, answer frequent questions, or recover inactive opportunities.
A well-defined objective is the most important factor for a successful setup. The Best practices section shows how to write a good state objective, with examples.
5. Agent configuration
Agent Builder: the recommended way to set up your agent
The simplest and most reliable way to configure an AI Agent is the Agent Builder, the setup assistant built into the platform. Instead of writing instructions from scratch, the Agent Builder guides you through a conversation:
- Interview: it asks about your company (who you sell to, what problem you solve, what sets you apart), the agent's personality (name, tone, formality), topics it must avoid and the objective of each state of the Sales Brain (Playbook).
- Automatic validation: it checks that the contact fields you mention exist in your account and creates the missing ones.
- Draft: it writes the general instructions and each state's objectives following quality criteria (specific, measurable objectives with a defined success and failure path). When you describe a rule like "move them to [state]", it writes it into the state's instructions as a mention of that state; it no longer asks you for a success state.
- Review and approval: it shows you the draft, applies your changes and only saves the configuration once you explicitly approve it.
Using the Agent Builder avoids the most common manual configuration mistakes: vague objectives, states without a failure path and contact fields that don't exist — the most frequent causes of the issues described in the Troubleshooting section.
The following sections describe what the configuration contains, whether the Agent Builder generates it or you edit it by hand.
General instructions
They define the agent's overall behavior, whatever state the contact is in:
- Tone: formal or informal.
- Personality: the agent's name and conversation style.
- Restrictions: topics it must never discuss (for example legal terms, unauthorized discounts or opinions about competitors).
- Scope of answers: what to do with questions outside its scope (answer briefly and steer back, or hand over to a person).
General instructions always apply; each state's instructions define the specific objective for that moment of the process.
Instructions per state
They define how the agent acts in each state of the Sales Brain (Playbook). For each state you configure:
| Setting | Description |
|---|---|
| State instructions | The state's objective, how the AI should act and, with a mention, which state to move the contact to in each case |
| Allow the AI to discard the contact | When on, the AI can discard the contact (no interest, wrong number or irrelevant) and move it to the Sales Brain (Playbook)'s lost state. When off, it can't discard it |
| Transfer to human after inactivity | Inactivity time after which the conversation closes and goes to your team (from 15 minutes to 16 hours, or never; 1 hour by default) |
There are no longer selectors to move the contact "on success" or "if the objective was not met": where the contact goes is written in the state's own instructions, as explained below.
6. Moving the contact from the instructions: state mentions
In each state's instructions you can say which state the contact should go to depending on what happens in the conversation. This way the AI follows your real process, with as many cases as you need, instead of only two fixed destinations (success and failure).
How to insert a state mention
- In the state's instructions, type @ or click the "@mention" button.
- Pick the "Playbook States" tab.
- Pick the Sales Brain (Playbook) and, inside it, the state. The mention shows as @[Sales Brain (Playbook) name › state name].
Next to each mention, write the condition that must be met. For example: "If they ask about financing, move them to @[Financing › New]".
What happens to the contact
Above each state's instructions, the "What happens to the contact based on your instructions" box sums up this behavior:
- When the condition written next to a mention is met, the AI moves the contact to that state right then, without waiting for the end of the conversation.
- If the AI acts in the destination state, it continues the conversation straight away with that state's instructions, without waiting for a new message from the contact. If the destination state belongs to another Sales Brain (Playbook) handled by a different agent, the conversation continues with that agent.
- If the AI doesn't act in the destination state, the conversation ends and the contact stays in that state for your team.
- If the AI meets the objective and your instructions don't say where to move the contact, the contact stays in the current state and the conversation ends.
- Discarding still depends on the "Allow the AI to discard the contact" switch, in each state's "Conversation closure" section.
Call agents work the same way: when the condition is met during the call, the agent moves the contact and, if it has instructions for the new state, carries on with the call following them.
The outcome of each conversation (objective met, objective not met or contact discarded) is still recorded, so agent metrics and conversation review work as before.
If you already had success and failure destinations set up
The destinations you had in the old selectors have been added at the end of each state's instructions as sentences with a mention, for example: "If, after talking with the contact, this stage's objective is met, move the contact to @[Sales Brain (Playbook) name › state name]" (written in Spanish). The contact moves just as before, and you can edit or extend those sentences like any other instruction.
States mentioned in instructions
A state or a Sales Brain (Playbook) that is mentioned in an agent's instructions can't be deleted: the warning names the agents that mention it. Remove the mention from those instructions first.
7. When a person steps in
AI Agents are designed to work alongside your team. The conversation is handed over automatically when:
Objective met
The agent has completed its task (for example: contact qualified, meeting booked, information collected). The contact goes to the state your instructions indicate; if they don't indicate one, it stays in the current state.
Contact discarded
The contact isn't valid for the process: wrong number, explicit lack of interest, or it meets the discard criteria defined in the instructions. If the state has "Allow the AI to discard the contact" on, it moves to the Sales Brain (Playbook)'s lost state; if it's off, the AI can't discard it.
Objective not met (valid contact)
The contact is still valid but needs a person: it asks to talk to someone, doesn't want to share its data, or the agent doesn't have the information it needs to help. The conversation goes to your team without discarding the contact.
Inactivity
The contact stops replying for the waiting time set in the state. The conversation closes and goes to your team.
Manual takeover
A member of your team can take over the conversation at any time; from then on the AI is turned off for that contact.
8. WhatsApp's 24-hour window
WhatsApp only lets businesses send free-text messages during the 24 hours after the contact's last message. After that, only approved templates can be sent.
For the agent, this means every new message from the contact reopens the window for another 24 hours.
This is a restriction of the WhatsApp platform itself, not of Vixiees, and it applies equally to every provider.
9. Best practices
- Set up the agent with the Agent Builder instead of writing instructions from scratch.
- Define specific, measurable objectives for each state, with a success and a failure path.
- Write in the instructions, with a state mention, where the contact should go in each case, with clear conditions that don't overlap.
- Define explicit, concrete discard criteria: they decide whether a contact is marked as lost.
- Keep the Knowledge Base up to date and delete old versions of documents instead of keeping both.
- Avoid redundant questions: if a piece of data is already saved in a contact field, the agent shouldn't ask for it again.
- Review conversations regularly, especially those handed over without the objective met: they show which information or instructions are missing.
- Make gradual changes to the configuration: one change at a time, measuring its effect.
- Keep a copy of the agent's instructions outside the platform.
How to write a good state objective
A well-written objective is the difference between a reliable agent and an unpredictable one. Compare:
| Vague objective ❌ | Well-defined objective ✅ |
|---|---|
| Qualify the contact | Get the budget, city and estimated project date. Success: all three collected and budget of €1,000 or more. Failure: budget under €1,000, or the contact refuses to share it |
A good objective meets four criteria:
- Specific: it uses exact numbers and conditions, not generalities.
- Measurable: it can be answered with a yes or a no.
- Complete: it defines what happens when it's met and when it isn't.
- Actionable: it makes the next step clear in each case.
10. Recommended metrics
| Metric | What it measures |
|---|---|
| Conversations started | Activity volume |
| Objectives met | Agent effectiveness |
| Handovers to your team | Need for optimization |
| Credits used | Platform usage |
| Average response time | Contact experience |
11. Credits and usage
AI Agents usage is measured in credits:
- Each contact message the agent processes uses one credit.
- Ways to buy credits:
- What happens when you reach the monthly limit you bought depends on your credit model:
If a monthly payment fails, the agent stops replying and is turned off until the payment is settled. If the agent stops replying, check that the last payment went through.
You can track usage in your account's billing section > AI Agents, and see more details on the Vixiees AI Agents page: LINK.
12. Troubleshooting
This section covers the most common issues, their most likely cause and how to fix them.
The agent doesn't reply to messages
For the agent to reply, all of these conditions must be true. Check them in order:
| Condition | What to check |
|---|---|
| The agent is active | Check that the agent is turned on in the Sales Brain (Playbook) configuration. |
| The state has the agent enabled | The agent only acts in the states of the Sales Brain (Playbook) where it's enabled. Check which state the contact is in. |
| The state has instructions | If the state has no objective or instructions, the agent doesn't reply in it. |
| The contact wasn't handed over before | After handing over a conversation (objective met, contact discarded or handover to your team), the agent stays silent for that contact until it changes state. |
| The AI is active for that contact | If someone on your team took over the conversation, or it closed due to inactivity, the AI is turned off for that contact. |
| Billing is up to date | On pay as you go (PAYG), if credits run out the agent stops processing messages. On subscription plans, the agent only stops replying if the monthly payment fails (it's turned off until settled); extra usage above the limit is billed under the plan. |
The agent also has anti-loop protection: it never replies to its own messages and, if it has already sent several messages in a row with no reply from the contact, it deliberately stops insisting. This isn't an error.
The agent takes a while to reply
This is expected: when a contact sends several messages in a row, the agent waits a few seconds to group them and answer them together instead of replying to each one. This makes the conversation more natural.
The agent said it didn't have the information
The agent never makes up answers: it checks the Knowledge Base and, if it can't find the information with enough confidence, it says so or hands the conversation over. The cause is almost always the Knowledge Base content:
- The information isn't in any document.
- The document hasn't finished syncing or has a sync error (check its status in the Knowledge Base).
- The information exists but is out of date or contradicts another document.
- The information exists but in a format the agent can't read, such as tables (redo the document with all the information as text).
Supported formats: PDF (up to 35 MB) and text or Markdown files (up to 512 KB). After you upload or update a document, the agent has the new information as soon as syncing finishes (usually a few seconds).
The agent gave a wrong answer
- Check for contradictory information across Knowledge Base documents and consolidate it.
- Check that the state's instructions don't contradict the Knowledge Base.
- Delete old versions of documents (prices, terms) instead of keeping both.
The contact sent an audio, an image or a file
- Audios and voice notes: transcribed automatically; the agent understands them as text.
- Images and documents: saved on the contact's record, but the agent doesn't interpret their content. If the contact sends key information in a photo (for example, a receipt), someone on your team needs to review it.
The contact changed state or was marked as lost unexpectedly
The agent moves the contact according to the state mentions written in the state's instructions, as soon as the condition written next to each one is met. When a conversation ends, it distinguishes three outcomes:
- Objective met → the contact goes to the state your instructions indicate; if they don't indicate one, it stays in the current state.
- Contact discarded (wrong number, explicit lack of interest, or it meets the discard criteria defined in the instructions) → only if the state has "Allow the AI to discard the contact" on, the contact moves to the Sales Brain (Playbook)'s lost state.
- Objective not met but valid contact (asks to talk to a person, doesn't want to share data, or the agent doesn't have information to help) → the conversation goes to your team without discarding the contact.
If a valid contact ended up discarded, review the discard criteria written in the state's instructions: they are probably too broad or ambiguous.
If the contact went to an unexpected state, review the conditions written next to each state mention in the instructions: they are probably too broad or overlap with each other.
I can't delete a state or a Sales Brain (Playbook)
If the state or Sales Brain (Playbook) is mentioned in any agent's instructions, it can't be deleted. The warning names the agents that mention it: remove the mention from their instructions and try again.
The conversation closed on its own
Each state has an inactivity waiting time (from 15 minutes to 16 hours, or never; 1 hour by default). If the contact doesn't reply within that time, the conversation closes, the AI is turned off for that contact and the conversation goes to your team. If this happens too early or too late, adjust the state's waiting time.
The agent didn't update a contact field
- Check that the field exists in the account with that exact name.
- Check that the state's instructions say that data must be collected.
- If the value was already saved and is the same, the agent doesn't write it again.
Conversation closure reasons
| Reason | What it means |
|---|---|
| Objective met | The agent completed the state's task; the contact goes to the state the instructions indicate, or stays in the current one if they don't indicate any. |
| Contact discarded | The contact isn't valid or meets the discard criteria; if the state allows it, it moves to the Sales Brain (Playbook)'s lost state. |
| Objective not met | The contact is still valid but needs a person; it goes to your team. |
| Inactivity | The contact stopped replying for the configured waiting time; it goes to your team. |
| Taken over by your team | A team member stepped into the conversation; the AI is turned off for that contact. |
| No credits / failed payment | Pay as you go: credits ran out and the agent stops processing new messages. Subscription: the monthly payment failed and the agent is turned off until it's settled. |
What to include when reporting an issue to support
So we can find the conversation and diagnose the case, always include:
- Your customer account or company name.
- The affected contact's phone number, or the contact's URL.
- The approximate date and time of the conversation.
- What you expected the agent to do and what it did instead (a screenshot helps a lot).
13. Frequently asked questions
Does the agent replace salespeople?
No. The goal is to automate repetitive tasks so your team can focus on higher-value conversations.
Does it work outside business hours?
Yes. Agents stay active 24 hours a day.
Can it integrate with my CRM?
Yes. It can update information in Vixiees, HubSpot and Pipedrive.
Can I have several agents?
Yes. You can set up different agents for different Sales Brains (Playbooks). Each Sales Brain (Playbook) can have only one agent. If you need more than one, the recommendation is to write different instructions for each state.
What happens if all credits are used?
It depends on your billing model. On pay as you go (PAYG), the agent stops processing new messages until credits are added. On subscription plans, the agent keeps replying and extra usage is billed under the plan's terms. If a monthly payment fails, the agent stops replying and is turned off until the payment is settled.
Can I turn the agent off temporarily?
Yes. You can turn it on or off at any time without losing the existing configuration.
Does it understand audios contacts send?
Yes. Voice notes are transcribed automatically and the agent processes them as text.
Can it interpret images or attached documents?
No. They're saved on the contact's record, but the agent doesn't analyze their content.
What language does it reply in?
In the language the contact writes in.
Why does it reply with short messages?
On purpose: the agent is designed to chat like a person on WhatsApp, with short, natural messages, instead of sending long paragraphs.
Conclusion
AI Agents take care of the first part of each conversation on WhatsApp and move every contact to the right state of your Sales Brain (Playbook) following the rules you write in each state's instructions, so your team steps in when it adds the most value.
Was this article helpful?