> ## Documentation Index > Fetch the complete documentation index at: https://docs.textyess.com/llms.txt > Use this file to discover all available pages before exploring further. # WhatsApp Agent: set up the AI that answers on WhatsApp > Set up the WhatsApp AI agent: name, tone, rules, reply length, languages, hours, human handoff, checkout links, discount codes, order tracking, and tests. The WhatsApp agent is the AI that answers your customers on your WhatsApp number. To set it up, open [Agents → WhatsApp Agent](https://ai.textyess.com/agents/whatsapp). The page has three tabs: **Instructions**, **Tools** and **Appearance**. Your changes go live only when you click **Publish**. Click **Discard** to remove changes that you did not publish. This page appears when your plan includes WhatsApp. ## Turn the WhatsApp AI agent on or off You turn the WhatsApp agent on or off for your whole number in the **WhatsApp AI schedule** card. 1. Open [Settings → Organization](https://ai.textyess.com/organization-settings). 2. In **WhatsApp AI schedule**, select **Always on**, **Always off** or **Follows a schedule**. 3. Click **Save changes**. When the AI is off, it does not answer. Each conversation that gets a new message moves to **Needs attention** in the [Inbox](https://ai.textyess.com/inbox), so your team can reply. To stop the AI in one conversation only, open the conversation in the Inbox. Then turn off the switch next to **AI is handling this conversation**, above the reply box. ## Let the WhatsApp AI agent answer only at some hours or days You can let the WhatsApp agent answer only at the hours that you choose, for example only at weekends. Your team answers at the other times. 1. Open [Settings → Organization](https://ai.textyess.com/organization-settings). 2. In **WhatsApp AI schedule**, select **Follows a schedule**. 3. Select your timezone. 4. For each day, click the **+** button to add a time window. Then set the start and end time. The AI answers only inside the windows. 5. Click **Save changes**. A day without a window shows **AI agent disabled**. The card shows if the AI is **ON** or **OFF** now, and when the next change is. A conversation that gets a message while the AI is off moves to **Needs attention** and stays with your team. The AI does not answer in that conversation again until your team hands it back to the AI in the Inbox. ## Send an out-of-office message when the WhatsApp AI agent is off When the WhatsApp agent is off, TextYess can send an automatic out-of-office message to the customer. 1. Open [Settings → Organization](https://ai.textyess.com/organization-settings). 2. In **WhatsApp AI schedule**, select **Always off** or **Follows a schedule**. 3. Turn on **Out-of-office message**. 4. Write the message. The limit is 500 characters. 5. To add a message in another language, click **Add language**. 6. Click **Save changes**. TextYess selects the language from the country of the customer's phone number. If there is no message in that language, the customer gets the first message, marked **(Default)**. If an AI reply or an out-of-office message went to this customer in the last 24 hours, TextYess does not send it. Each out-of-office message counts as a billable AI reply. ## Set the WhatsApp agent's name and tone On the **Instructions** tab of [Agents → WhatsApp Agent](https://ai.textyess.com/agents/whatsapp): 1. In **Agent Name**, type the name that the agent uses with customers. The limit is 100 characters. 2. In **Tone Preset**, select **Friendly**, **Formal**, **Irreverent**, **Funny** or **Custom (AI-Generated)**. 3. Read the text in **Personality Description**. A preset fills this text for you. If necessary, edit it. The limit is 5,000 characters. 4. Click **Publish**. To write your own tone, select **Custom (AI-Generated)** and write the text in **Personality Description**. ## Add operational rules to the WhatsApp agent **Operational Rules** are instructions that the WhatsApp agent follows in every reply. Use them for behavior: what to always do, what to never say, and how to answer a type of question. 1. On the **Instructions** tab, write your rules in **Operational Rules**. The usual limit is 7,000 characters. The counter under the field shows your limit. 2. To let the AI write a rule for you, click **Add rule**. Describe the rule and click **Generate**. TextYess adds the rule at the end of your rules. 3. Click **Publish**. The agent treats your rules as high-priority instructions. They take priority over its default style and tone. If two rules conflict, the agent follows the more specific rule. Rules cannot override the agent's safety limits. For example, the agent never confirms a refund. ## Change the length of the WhatsApp agent's replies There is no setting for reply length. By default, the WhatsApp agent writes short, mobile-friendly replies. It aims for less than 300 characters. A longer reply can arrive as up to 3 separate WhatsApp messages. To change the length, add a rule in **Operational Rules** on the **Instructions** tab of [Agents → WhatsApp Agent](https://ai.textyess.com/agents/whatsapp). For example: "Answer in two sentences or less." or "When a customer asks about materials, give the full details." Your rules take priority over the default style. Click **Publish**, then try the change in the test chat on the same tab. ## Which languages the WhatsApp agent answers in The WhatsApp agent answers in the language of the customer's message. It translates your knowledge base, product data and rules into that language. If the customer changes language, the agent changes language too. There is no setting to choose or limit the reply language. For a short message, the agent also uses the customer's last messages to find the language. It ignores words that carry no language, such as order numbers, emails and links. For example, a message with only an order number gets a reply in the language of the customer's earlier messages. ## Why the WhatsApp agent does not reply instantly The WhatsApp agent waits 10 seconds after the customer's last message. If the customer sends another message during the 10 seconds, the wait starts again. This way, the agent answers several quick messages with one reply. When the wait ends, the customer sees the message as read and sees "typing…". The agent then searches your knowledge base and, when necessary, your products or the customer's order. Then it writes the reply. This takes some more seconds. A voice note takes a little longer, because TextYess first converts it to text. ## Hand a WhatsApp conversation to your team The **Escalation to Human** tool lets the WhatsApp agent pass a conversation to your team. It is on by default. You find it on the **Tools** tab, in **Agent Tools**. By default, the agent hands over when: * the customer asks for a person, * the customer is frustrated or unhappy, * the agent cannot solve the request. To set your own triggers, click **Edit** next to **Escalation rules**. Then click **I understand, let me edit**. Your rules replace the default triggers completely. To go back, click **Clear & revert to smart defaults**. Click **Publish** to save. When the agent hands over, it tells the customer that a person will help them soon. Then the AI stops answering in that conversation. The conversation moves to **Needs attention** in the [Inbox](https://ai.textyess.com/inbox). ## Get notified when the WhatsApp agent hands over a conversation When the WhatsApp agent hands a conversation to your team, TextYess tells you in two ways: * If the Inbox is open, an alert shows on the screen. * An email goes out with the customer's last message, the reason for the handover, and a link to the conversation. Each team member turns on this email in [Settings → Account → Notifications](https://ai.textyess.com/profile/notifications), with the **Human support request** switch. If nobody in your workspace set up email notifications, the email goes to the account owner. If your team set up email notifications but nobody turned on **Human support request**, no email goes out. See [Notifications](/notifications). ## When the Escalation to Human tool is off If you turn off **Escalation to Human**, the WhatsApp agent cannot pass conversations to your team. When a customer asks for a person, the agent says that human support is not available in this chat. It suggests that the customer contact your store directly, for example by email or phone. To hand over conversations, turn on **Escalation to Human** on the **Tools** tab of [Agents → WhatsApp Agent](https://ai.textyess.com/agents/whatsapp) and click **Publish**. ## What the WhatsApp agent can do for your customers The WhatsApp agent can: * answer questions about your products and suggest products, with a photo and a link, * answer questions about your store, shipping and returns from your [knowledge base](/agents/knowledge-base), * look up the status of an order with **Order Tracking** (Shopify stores), * send a ready-to-pay checkout link with **Checkout links** (Shopify stores), * share the discount codes that you allow with **Discount codes**, * pass the conversation to your team with **Escalation to Human**, * see photos that customers send, and answer voice notes. You turn the tools on or off on the **Tools** tab of [Agents → WhatsApp Agent](https://ai.textyess.com/agents/whatsapp). ## What the WhatsApp agent cannot do The WhatsApp agent cannot: * change, cancel or refund an order, or change a delivery address, * confirm or promise a refund, * send emails, or place an order for the customer (it can only prepare a checkout link), * watch videos or open files, such as a PDF, that customers send (it reads only the caption), * reply to emoji reactions, * invent discount codes (it shares only the codes that you allow). If **Escalation to Human** is on, the agent can pass a request that it cannot handle to your team. ## Can the WhatsApp agent see photos and listen to voice notes? Yes. When a customer sends a photo, the WhatsApp agent sees it. If the photo shows a product, the agent can talk about it or help find similar products. If the photo has no text, the agent says that it got the photo and asks how it can help. When a customer sends a voice note, TextYess converts it to text. The agent answers that text. The agent does not watch videos or open documents that customers send. It reads only the caption of the video or document. ## Let the WhatsApp agent send checkout links **Checkout links** lets the WhatsApp agent create a ready-to-pay checkout in your Shopify store and send the link. The customer only has to pay. The tool is on by default and shows only for Shopify stores. Before it creates the link, the agent confirms the product variant, the quantity and the full shipping address with the customer. The checkout is a draft order in your Shopify admin, with the tags `TextYess` and `agent-checkout`. If the product is out of stock or not for sale online, the agent does not create the link. Options on the **Tools** tab: * **When the agent proposes the checkout**: **Only when asked** or **Proactively when relevant**. * **Ask for an email before creating the link**: the agent gets the customer's email first. * **Add a phone number to the order**: the agent adds the customer's WhatsApp number, or a delivery number that the customer gives. ## Let the WhatsApp agent share discount codes The WhatsApp agent shares only the discount codes that you allow. Turn on **Discount codes** on the **Tools** tab of [Agents → WhatsApp Agent](https://ai.textyess.com/agents/whatsapp). 1. In **Allowed discounts**, select the Shopify discounts that the agent can share. This list shows only for Shopify stores. 2. In **When the agent can mention discounts**, select **Only when asked** or **Proactively when relevant**. 3. Optional: in **Behavior rules (optional)**, write how to use the codes. You can also write a code here, for example "Suggest WINTER40 for the new collection." The agent can then share that code. The limit is 2,000 characters. 4. Click **Publish**. When **Discount codes** is off, the agent tells customers that it has no information about current promotions. ## Let customers track their order on WhatsApp **Order Tracking** lets the WhatsApp agent look up the status of an order. It shows on the **Tools** tab for Shopify stores. When a customer asks where their order is, the agent asks for the order number and the email used for the purchase in one message. Then it looks up the order in your store. When **Order Tracking** is off, the agent does not look up orders. It follows your **Operational Rules** for order questions. If there is no rule, it tells the customer to contact the store or to look at their confirmation email. ## Greet first-time customers on WhatsApp On the **Tools** tab of [Agents → WhatsApp Agent](https://ai.textyess.com/agents/whatsapp), the **First contact** card sets what a new customer sees first. * **Welcome greeting**: TextYess sends an automatic greeting the first time that a customer writes to you. In **Guidance (optional)**, write what the greeting must mention. The limit is 300 characters. * **Suggested topics**: up to 4 tappable topics that WhatsApp shows to first-time customers. Each topic has a limit of 80 characters. Click **Draft with AI** to let the AI suggest topics. The preview on the right shows an example greeting. Then click **Publish**. If your WhatsApp bubble has a default message, a warning shows under **Welcome greeting**. Read it before you publish. ## Change the WhatsApp chat bubble on your website The **Appearance** tab of [Agents → WhatsApp Agent](https://ai.textyess.com/agents/whatsapp) sets the WhatsApp chat bubble for your website. You can change: * the colors of the bubble, the box and the button, * the **Position**: **Left** or **Right**, * the **Widget message** and the **Call to action text**, * the **Default message**: the text that is ready in WhatsApp when a visitor taps the bubble. Click **Publish** to save. The colors, the position and the texts are written in the bubble's snippet, so your store shows the old bubble until you replace it. Click **Install**, click **Copy**, and paste the new snippet in place of the old one in your theme. To put the bubble on your website for the first time, see [Shopify](/widget-installation-shopify) or [WooCommerce](/widget-installation-woocommerce). To translate the bubble texts, see [Localize your WhatsApp bubble](/localize-whatsapp-bubble). ## Test the WhatsApp agent before you publish The **Instructions** tab of [Agents → WhatsApp Agent](https://ai.textyess.com/agents/whatsapp) has a test chat on the right side. 1. Type a question in the field **Write here the questions to test your AI**. 2. Press Enter and read the reply. 3. To start a new test, click **Clean**. The test chat uses your current **Agent Name** and **Operational Rules**, also before you click **Publish**. Test messages do not go to WhatsApp and do not show in the Inbox. To test the real experience, send a WhatsApp message to your business number from your own phone. ## Why the WhatsApp agent did not reply to a message The WhatsApp agent does not reply when: * the **WhatsApp AI schedule** has the AI off at that time, * your team handles the conversation, or the agent handed it over before, * an automation waits for this customer's reply, or starts with this message (the automation answers), * you blocked the contact, * your plan has no AI replies left, * your account is suspended for a payment, * the message is an emoji reaction. When the AI is off, or your plan has no AI replies left, the conversation moves to **Needs attention** in the [Inbox](https://ai.textyess.com/inbox). If the agent has a technical error, the customer gets a short apology and the conversation moves to **Needs attention**. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.