AI Agent for WhatsApp Customer Support

This guide builds a complete support journey: prepare the agent, choose a WhatsApp integration, decide who receives each conversation, and validate the real channel. Continuous availability depends on the provider connection and your routing rules; it is not a guarantee of failure-free replies.

Expected result

When you finish, you will have:

an active agent with behavior and boundaries defined in its prompt;
an inbox connected through one of the five current WhatsApp integrations;
a default destination and, when needed, service hours alternating between AI and human support;
an explicit human-transfer path;
a real inbound and outbound conversation validated on WhatsApp.

Before you start

You need permission to edit agents and inboxes. If New Agent, Connect inbox, or the editing controls do not appear, ask your organization administrator for the corresponding access.

Also prepare the account and credentials for the chosen integration. The Official API uses Meta’s flow and a WhatsApp Business number; Z-API, UAZAPI, and Evolution use the account or instance you maintain with those providers.

Choose the integration

Under Inboxes, Pick the channel shows five options. These names match the current interface:

Option	When to use it	What to prepare
WhatsApp	QR Code validation. The interface identifies this option as testing only.	A phone available to scan the QR Code.
WhatsApp Official	Meta’s official API with a verified number.	Meta account and WhatsApp Business number; the flow may request the two-step verification PIN.
WhatsApp (Z-API)	Your own Z-API account.	Instance ID, instance token, and client security token.
WhatsApp (UAZAPI)	Your own UAZAPI account.	Base URL and instance token.
WhatsApp (Evolution)	Your own Evolution instance.	Base URL, instance name, and API key.

Configure support

Create and save the agent

Open Agents, select New Agent, enter the name, and confirm with Create Agent. On desktop, the new agent opens the editor with AgentMaker; you can also close the copilot and edit directly.

In Prompt, describe the role, tone, boundaries, information that must never be invented, and situations that require a person. Choose an available model, keep the agent active, and use Save changes. See Creating Agents and System Prompts.
Add knowledge when needed

Under Knowledge, select the relevant bases and write a shared instruction. The runtime decides when to call search_knowledge_base; it does not query every document on every message. Confirm that the items are processed and test questions whose answers exist in the content. See Connecting Knowledge Bases to Agents.
Define human transfer

Add the Transfer Conversation native tool when the agent must route specific cases. Configure valid conditions and destinations, state in the prompt when to transfer, and test one case that transfers and another that remains with AI. See Transfer Conversation.
Connect the WhatsApp inbox

Open Inboxes, select Connect inbox, and choose one of the five options under Pick the channel.
- For QR Code, scan the code before its displayed deadline and wait for the connection.
- For the Official API, complete Meta’s flow and, when requested, the two-step verification PIN.
- For Z-API, UAZAPI, or Evolution, enter the credentials, follow the provider setup, and complete verification in SquadOS.
Read the integration-specific guide: QR Code, Official API, Z-API, UAZAPI, or Evolution.
Choose the inbox destination and name

Connection happens before inbox creation. Once confirmed, Who handles this inbox? asks for the Destination and Inbox name. Select the agent from step 1 as the default destination, review the name, and use Done.
Configure service hours

SquadOS opens Service hours, step 2 of 2. You may choose Set up later. With no active schedule, every new conversation follows the default destination at any time. With a schedule, define weekly windows, the outside-hours destination, and exceptions; the screen also offers SLA and AI takeover. Inboxes explains the separation between connection and routing.
Test the saved version and the real channel

Open Test Agent. The panel uses the real runtime, may create a persistent conversation, consume credits, and run tools with external effects. Test knowledge, a refusal, transfer, and a normal reply. Save any change before testing again. See Testing an Agent.

Next, send a message from another phone to the connected number. Under Conversations, confirm the inbox, destination, schedule, and delivery of the reply on WhatsApp. Also perform a human reply and a handoff to validate the contingency path.
Monitor and adjust from evidence

Under Conversations, track the assignee, state, SLA, and reply turn. Taking over a conversation interrupts automation for that support interaction; it does not disable the agent for other conversations. Read Human Intervention.

In Analytics, observe volume, credits, performance by agent, and SLA. Adjust the prompt, knowledge, and routing from real conversations, not only an isolated test.

The Official API’s 24-hour rule

Meta’s window applies only to WhatsApp Official. During the 24 hours after the customer’s latest message, the team can reply with free-form text. Outside the window, a new message requires an approved template. When available to your organization, the catalog is under Settings → WhatsApp templates; the conversation also offers template sending when it is required.

QR Code, Z-API, UAZAPI, and Evolution do not use the Cloud API window or templates inside SquadOS. You must still follow the provider’s policies and contract.

Checklist before releasing the number

The agent is active and its changes are saved.
Questions with and without an answer in the knowledge base were tested.
Human transfer has a valid destination and was exercised.
The default destination, schedule, and outside-hours destination were reviewed.
A real message entered through the correct inbox and received a reply on WhatsApp.
The team knows how to take over, transfer, complete, and reopen a conversation.
For the Official API, approved templates exist for use outside the 24-hour window.

Quick troubleshooting

Symptom	Check
New Agent or Connect inbox does not appear	Write access for Agents and Inboxes.
The agent does not reply	Active state, saved version, credits, destination, and current schedule.
Knowledge is missing	Base link, processed item, instruction, and retrieval test.
The conversation reached an unexpected destination	Default destination, weekly window, exception, and outside-hours destination.
The Official API does not allow free-form text	Time of the customer’s latest message and an approved template.
The channel connects but does not deliver	Status, credentials, provider webhook or session, and conversation logs.