BlogResources

How to build a WhatsApp agent (step-by-step)

A step-by-step guide to building a WhatsApp agent with CodeWords — from describing your agent to writing a system prompt, testing, and iterating to improve it.

Rebecca PearsonJuly 15, 20267 min read

How to build a WhatsApp agent (step-by-step)

Building a WhatsApp agent in 2026 is significantly faster than it used to be. You don't need to write code, manage webhooks, or deal with the WhatsApp API directly. With CodeWords, you describe what you want to Cody (the AI automation assistant) and it builds the agent for you. You're in the conversation within the hour.

This guide is the practical version — exactly what to do at each step, what a good system prompt looks like, how to test properly, and how to improve your agent based on what you see in real conversations.

TL;DR

You can go from blank page to live WhatsApp agent in under an hour — describe your agent to Cody, connect WhatsApp, write your system prompt, and deploy.
The system prompt is the most important thing you'll write — it defines your agent's personality, scope, and behaviour, and a good one is the difference between a great agent and a frustrating one.
Real testing means edge cases, not just happy paths — test what happens when users ask off-topic questions, make mistakes, or try to break the bot.

Step 1: Go to CodeWords and open a new agent

You'll see a prompt where you can describe what you want your agent to do. This is where you talk to Cody — CodeWords' AI automation assistant — who builds the automation based on your description.

Step 2: Describe your agent

This is the most important step in the build, and it's worth spending a few minutes getting the description right.

A good agent description includes:

What the agent is for and who it serves
The specific actions it needs to take (answer questions, book appointments, take orders, qualify leads, escalate to humans)
Any integrations needed (Google Calendar, HubSpot, Google Sheets, Calendly, etc.)
How it should handle situations it can't resolve (what to say, who to escalate to)

Here are examples of descriptions that produce good first builds:

For a support bot:

"Build a WhatsApp support bot for a dental practice. It should answer common patient questions (hours, appointment booking, what treatments we offer, post-procedure care), help patients book appointments by checking Google Calendar and confirming slots, and escalate to the front desk team if a patient asks something it can't handle or asks for a human. Tone should be warm and professional."

For a sales bot:

"Build a WhatsApp lead qualification bot for a software company. When someone messages in, greet them, ask what they're trying to solve, ask about their team size and timeline, and if they look like a fit, push their details to HubSpot and send an alert to Slack. If they're not ready to buy yet, send them a link to our case study."

For an order bot:

"Build a WhatsApp order bot for a bakery. Show customers today's menu (from a Google Sheet), take their order in natural language, confirm the total and collection day, and log the order to a separate Google Sheet."

Don't worry about getting the description perfect — Cody can build a first version and you can iterate. But more detail in the initial description means fewer rounds of revision.

Step 3: Choose your WhatsApp connection method

Once Cody has built your agent, you'll connect it to WhatsApp. You have two options:

Personal Device: connect your own WhatsApp number by scanning a pairing code. Setup takes about 30 seconds. There are no daily message caps and no template requirements. This is the fastest path and works well for most inbound-first setups.

Business API: use CodeWords' WhatsApp Business API number. Templates are required for any outbound messages outside the 24-hour service window. Daily caps apply by plan (5/20/50 DMs/day). Better if you want to run scheduled outbound campaigns to an opted-in list.

For most businesses building their first agent, Personal Device is the right starting point. You can switch to Business API later if your needs evolve.

Step 4: Write your system prompt

The system prompt is the set of instructions the AI model reads on every single message. It defines who your agent is, what it can and can't do, how it communicates, and how it handles difficult situations.

A weak system prompt produces an agent that wanders off-topic, gives inconsistent answers, and handles edge cases badly. A strong system prompt produces an agent that feels like a reliable, professional representative of your business.

What a good system prompt includes

Identity: who the agent is and what it's there to do. "You are the customer support assistant for Riverside Dental. Your job is to help patients with appointment enquiries, answer common questions about our treatments, and escalate to the front desk when needed."

Tone and style: how the agent should communicate. "Be warm, professional, and concise. Use short paragraphs and avoid jargon. Write as if you're texting a patient, not writing a formal letter."

Scope: what the agent handles and what it doesn't. "You handle appointment bookings, general questions about treatments, and post-procedure care queries. If a patient asks for clinical advice specific to their situation, politely explain that you can't advise on that and suggest they call the practice."

Edge case behaviour: what to do when things don't go to plan. "If a patient is upset or frustrated, acknowledge their concern genuinely before offering a solution. If the situation requires a human, say: 'I want to make sure you get the right help here — let me connect you with our front desk team.'"

Escalation triggers: when to hand over to a human. "Escalate to a human if the patient says 'I want to speak to someone', 'this isn't working', or asks anything involving symptoms, pain, or urgent dental emergencies."

Formatting instructions: how to structure responses. "Keep responses to two or three short paragraphs maximum. Use bullet points for lists of options. Don't use formal salutations or sign-offs — just get to the point."

Common system prompt mistakes

Too vague: "Be helpful and answer questions." This tells the model almost nothing about what to do in any specific situation.
Too long: system prompts over 1,000 words can cause the model to miss instructions. Be concise and prioritise.
No escalation path defined: if the agent doesn't know when to hand over to a human, it will either hand over too readily or not at all.
No scope defined: without clear scope, the agent will attempt to answer anything — including things it shouldn't.

Step 5: Deploy

Once you're happy with the agent and system prompt, deploy it. In CodeWords, this publishes the agent and activates the WhatsApp connection.

Share your WhatsApp number — or a click-to-chat link — with your customers. A click-to-chat link looks like https://wa.me/447911123456 and can be added to your website, email signature, Google Business profile, or social media bio.

When a customer clicks the link and sends a message, your agent responds automatically.

Step 6: Test properly

Testing a WhatsApp agent means more than sending a few sample questions and confirming the happy path works. Proper testing covers three categories:

Normal questions: the typical queries you expect most customers to send. If you've described your agent well and your system prompt covers these, they should work well.

Edge cases: unusual questions, malformed requests, or things your agent isn't designed to handle. "What's the capital of France?" "Can you hack my ex's phone?" "I want a refund for something I bought five years ago." Your agent should handle these gracefully — acknowledging it can't help and redirecting, rather than making something up or breaking.

Escalation triggers: explicitly test that the escalation path works. Say "I want to speak to a human." Say "This is an emergency." Check that the agent stops responding and the alert goes to the right place.

Also test on mobile — your WhatsApp is on your phone, so your agent's responses should read naturally on a small screen. Long paragraphs and dense text that look fine on desktop can feel overwhelming on mobile.

Step 7: Iterate based on what you see

Your first deployment won't be perfect. Every agent gets better through iteration, and the raw material for iteration is real conversations.

For the first two weeks, read through your agent's actual conversations regularly. Look for:

Questions the agent answered incorrectly or imprecisely
Topics that came up that you hadn't anticipated and aren't in the system prompt
Points where customers seemed confused by the agent's response
Successful resolutions — these tell you what's working well

For each issue you find, update your system prompt to address it. Be specific: if the agent gave a wrong answer about your cancellation policy, add the correct policy explicitly to the prompt. If it's handling a topic too broadly, narrow the scope instructions.

Agents that get regular system prompt updates based on real conversations improve quickly. Within a few weeks, most agents are handling the vast majority of queries well.

What to do when an agent isn't improving

Sometimes an agent's issues aren't fixed by system prompt updates. If the agent is:

Consistently misunderstanding a specific type of question
Giving responses that feel inconsistent in tone
Struggling with multi-step tasks

...it may be worth trying a different AI model. CodeWords supports GPT-5, GPT-5-mini, Claude Sonnet 4.6, Claude Haiku 4.5, and Gemini 3.5 Flash. Different models have different strengths — try switching and see if performance improves for your specific use case.

You're live

A well-built WhatsApp agent handles the repetitive, time-consuming part of customer communication automatically — so you and your team can focus on the work that actually needs a human.

Build your WhatsApp agent on CodeWords — describe what you need to Cody and be live within the hour.