Get your AI agent on WhatsApp, two-way, without the Business API grind

If you’ve built an AI agent, you’ll soon discover that building it is only part of the work. You still need to bring the agent to the messaging platforms your users already use and make sure it works as expected on each one.

Novu Connect handles that communication layer. It lets you connect one agent to multiple messaging platforms without rebuilding the agent for every channel. In this tutorial, we’ll show you how to bring your agent to WhatsApp for two-way customer conversations.

Key takeaways

What it takes to bring an AI agent to WhatsApp

1. 1

   Handle WhatsApp-specific complexity

   WhatsApp messages arrive as platform-specific payloads. To make them useful to your agent, you need to identify the right user and conversation, translate the payload, manage credentials, and support channel-specific behaviors such as typing indicators and emoji reactions.

2. 2

   Let Novu Connect handle the communication layer

   Novu Connect handles this integration layer, allowing the same agent to work across the messaging platforms your users already use. In this tutorial, you’ll connect an existing agent to WhatsApp without rebuilding its model, tools, or business logic.

What it takes to put an AI agent on WhatsApp

A WhatsApp AI agent needs a communication layer between the WhatsApp Business Platform and the code that runs its model, prompts, tools, and business logic.

The message path looks like this:

1. A user sends a message to your WhatsApp Business number.
2. WhatsApp sends an event to a registered webhook.
3. The communication layer validates and normalizes the event.
4. The correct conversation and its history are loaded.
5. Your agent receives the current message and conversation context.
6. Your agent returns a reply or requests approval to call a tool.
7. The reply is translated and delivered to the same WhatsApp conversation.

Novu Connect provides the ACI, Agent Communication Infrastructure, bridge in this path. It receives channel events, normalizes them, preserves conversation context, and delivers responses.

What Novu handles and what you configure

The WhatsApp Business Platform remains the underlying channel. Novu removes the integration work around connecting that channel to your agent.

Prerequisites

You need the following accounts and tools to complete the tutorial.

• A Novu account.
• Node.js 22 or later.
• An OpenAI API key or another model-provider key supported by the Vercel AI SDK
• A Meta account with access to a WhatsApp Business account
• A phone number you can use with the WhatsApp Business Platform

Build an order-support agent that works in the terminal

Start with a useful agent that works without Novu or WhatsApp. For this example, the demo answers return-policy questions and looks up the status of a sample order.

1. 1

   Create the project

   Create a new project and install the required packages:

   mkdir whatsapp-order-agent
   cd whatsapp-order-agent
   npm init -y
   npm install ai @ai-sdk/openai zod
   npm install --save-dev tsx typescript @types/node

2. 2

   Configure the project

   Update the package.json file to use ES modules, add a command for starting the terminal chat, and provide the model API key.

   {
     "type": "module",
     "scripts": {
       "chat": "tsx --env-file=.env cli.ts"
     }
   }

   Create a .env file and add your model-provider key:

3. 3

   Add the order-support agent

   Keep the agent logic independent of WhatsApp and Novu so you can run it from any interface. Create support-agent.ts with the agent's instructions, order lookup tool, and model call:

   import { openai } from "@ai-sdk/openai";
   import { generateText, stepCountIs, tool, type ModelMessage,} from "ai";
   import { z } from "zod";
   
   const orders = {
     "NV-1042": {
       status: "Shipped",
       expectedDelivery: "Friday",
     },
     "NV-1043": {
       status: "Processing",
       expectedDelivery: "Next Tuesday",
     },
     "NV-1044": {
       status: "Delivered",
       expectedDelivery: "Delivered on Monday",
     },
     "NV-1045": {
       status: "Out for delivery",
       expectedDelivery: "Today",
     },
     "NV-1046": {
       status: "Cancelled",
       expectedDelivery: "N/A",
     },
     "NV-1047": {
       status: "Delayed",
       expectedDelivery: "Next Monday",
     },
     "NV-1048": {
       status: "Shipped",
       expectedDelivery: "Wednesday",
     },
   } as const;
   
   export function generateOrderSupportResponse(messages: ModelMessage[]) {
     return generateText({
       model: openai("gpt-4o"),
       system: `
         You are an order-support agent.
         Keep replies concise.
         Use getOrderStatus when a user provides an order ID.
         If an order does not exist, ask the user to check the ID.
         The return window is 30 days after delivery.
       `,
       messages,
       stopWhen: stepCountIs(5),
       tools: {
         getOrderStatus: tool({
           description: "Look up the current status of an order",
           inputSchema: z.object({
             orderId: z.string().describe("The order ID, such as NV-1042"),
           }),
           execute: async ({ orderId }) => {
             const order = orders[orderId as keyof typeof orders];
             if (!order) {
               return { found: false, orderId };
             }
             return { found: true, orderId, ...order };
           },
         }),
       },
     });
   }

4. 4

   Add the terminal interface

   Next, create cli.ts. This gives the agent a small terminal interface and keeps the conversation history between turns:

   import { stdin as input, stdout as output } from "node:process";
   import { createInterface } from "node:readline/promises";
   import type { ModelMessage } from "ai";
   import { generateOrderSupportResponse } from "./support-agent.js";
   
   const terminal = createInterface({ input, output });
   const messages: ModelMessage[] = [];
   
   console.log("Order support agent");
   console.log("Try: Where is order NV-1042?");
   console.log("Type exit to stop.\n");
   
   while (true) {
     const prompt = await terminal.question("You: ");
   
     if (prompt.trim().toLowerCase() === "exit") {
       break;
     }
   
     messages.push({ role: "user", content: prompt });
   
     const result = await generateOrderSupportResponse(messages);
   
     console.log(`Agent: ${result.text}\n`);
     messages.push(...result.response.messages);
   }
   
   terminal.close();

5. 5

   Test the agent in the terminal

   The terminal test proves that the model, instructions, tool, and conversation history work before a messaging provider enters the path.

   Start the agent:

   npm run chat

   Ask for the sample order:

   You: Where is order NV-1042?
   Agent: Order NV-1042 has shipped and is expected to arrive Friday.

   Then test a follow-up question:

   You: Can I return it after it arrives?
   Agent: Yes. You can return it within 30 days after delivery.

   Try an unknown order ID as well:

   You: Where is order NV-9999?

   The agent should ask you to check the order ID instead of inventing an order status. If the terminal agent does not respond, confirm that OPENAI_API_KEY is available and that your model account can make API requests.

   

   At this point, the business agent works. It does not depend on Novu, and it is not tied to WhatsApp. The next step gives that existing agent a WhatsApp communication path.

Connect the working agent to Novu and WhatsApp

Run the Novu CLI inside the project that contains the working agent. The command specifies both the AI SDK runtime and WhatsApp channel, so the CLI can guide you through the complete connection flow.

npx novu connect --channel whatsapp --runtime ai-sdk

The CLI will ask you to connect your Novu account, create the agent in Novu, and connect its WhatsApp channel. For WhatsApp, you can log in with Facebook or provide the credentials manually. The next section covers both options.

Connect your WhatsApp Business account

The CLI takes you to the WhatsApp connection step during setup. You can connect your WhatsApp Business account through Facebook or enter its credentials manually.

1. 1

   Option 1: Log in with Facebook

   The Facebook login flow is the recommended path because Novu can save the credentials you authorize and register the webhook automatically.

   1. Open your agent in the Novu dashboard.
   2. Click WhatsApp to add it as a channel.
   3. Click Log in with Facebook.
   4. Select the business portfolio and WhatsApp Business account you want to share.
   5. Review the requested access and complete the authorization flow.

   After authorization, Novu stores the shared credentials and registers the webhook that receives inbound WhatsApp messages. You do not need to copy API fields or configure the webhook yourself.

   

2. 2

   Option 2: Enter your credentials manually

   You can configure the provider manually if you prefer to copy the credentials from Meta into Novu.

   Create a Meta app

   First, create the app that will provide access to your WhatsApp Business account.

   1. Open the Meta App Dashboard and click Create App.
   2. Select the Connect with customers through WhatsApp use case.
   3. Select an existing business portfolio or create one.

   Add the API credentials to Novu

   Next, collect the required values from the app and add them to the provider configuration.

   1. In the Meta app's left sidebar, open Use cases.
   2. Find Connect with customers through WhatsApp and click Customize.
   3. Open API Setup from the inner menu.
   4. Copy the contents of the API Setup page and then paste them into the Novu configuration sidebar. Novu uses the page contents to fill the supported fields automatically.
   5. Open App settings > Basic, copy the App secret, and paste it into Novu manually.

   Novu needs these values:

   Credential	Where to find it
   Access token	Click Generate access token on the API Setup page
   Phone Number ID	Under the selected phone number on the API Setup page
   WhatsApp Business Account ID	Directly above the Phone Number ID
   App secret	App settings > Basic

   Save the provider after Novu fills the fields and you add the app secret.

   

Complete the project setup and start the local bridge

After you connect WhatsApp, the CLI runs the project setup and tells you what is needed to connect your code to Novu Connect.

You can complete the suggested changes yourself. You can also copy the prompt provided by Novu, paste it into your coding agent, and let the coding agent complete the setup in your project.

Review the generated changes before continuing. Your original agent behavior should remain the same. Novu adds the communication path that passes WhatsApp messages and conversation context to the agent and returns its replies.

When setup is complete, start the local bridge using the command provided by the CLI. For this project, run:

npx novu dev --port 4000

Keep the process running, then open WhatsApp and message the connected business number. The terminal interface remains available when you want to test the underlying agent without going through WhatsApp.

Send a WhatsApp message to the agent

With the provider connected and the local bridge running, send a message to the WhatsApp Business number.

Start with the same order lookup you tested earlier:

Where is order NV-1042?

The complete round trip is now:

1. WhatsApp sends the inbound event to the webhook registered by Novu.
2. Novu normalizes the event and resolves the user and conversation.
3. Novu sends the current conversation history to orderSupportAgent.
4. The agent calls getOrderStatus and returns its response.
5. Novu delivers the answer to the same WhatsApp conversation.

The user should receive a response similar to:

Order NV-1042 has shipped and is expected to arrive Friday.

Open Agent Conversations in the Novu dashboard to inspect the conversation and confirm that the messages belong to the same session.

Use WhatsApp-native agent interactions

On WhatsApp, Novu Connect currently supports:

• Full conversation context
• Threaded replies within the session window
• A typing indicator while the agent works
• Quick-reply buttons, with up to three buttons per message
• Emoji reactions
• Message edits
• Tool approval through quick-reply buttons
• Short authorization links for MCP server connections
• Conversation resolution

For example, you can require approval before an agent calls a sensitive tool. Novu presents Approve and Deny as quick-reply buttons in WhatsApp, then resumes the agent turn after the user responds. See the WhatsApp channel reference for the current capability matrix.

Give your existing agent a WhatsApp presence

Keep your agent’s model, prompts, tools, and business logic. Novu Connect handles the WhatsApp communication layer.

Connect to WhatsApp

Frequently asked questions