{"id":11011,"date":"2026-09-23T17:12:12","date_gmt":"2026-09-23T20:12:12","guid":{"rendered":"https:\/\/z-api.io\/blog\/?p=11011"},"modified":"2026-09-23T17:15:11","modified_gmt":"2026-09-23T20:15:11","slug":"how-to-build-an-ai-powered-whatsapp-chatbot-with-n8n-z-api-chatgpt","status":"publish","type":"post","link":"https:\/\/z-api.io\/blog\/en\/how-to-build-an-ai-powered-whatsapp-chatbot-with-n8n-z-api-chatgpt\/","title":{"rendered":"How to build an AI-powered WhatsApp chatbot with n8n + Z-API + ChatGPT"},"content":{"rendered":"\n

Building an AI-powered WhatsApp chatbot is no longer a project reserved for large development teams. With a messaging API, an automation platform, and a language model, you can create workflows capable of receiving questions, understanding context, and replying automatically.<\/p>\n\n\n\n

In this guide, you\u2019ll learn how to build an AI chatbot with n8n, Z-API, and ChatGPT<\/strong>. The workflow is based on the video tutorial referenced for this content and has been expanded with information from the technical documentation of each tool.<\/p>\n\n\n\n

The architecture is straightforward: Z-API connects the WhatsApp number to the system; n8n receives events and orchestrates the workflow; and the AI interprets messages and generates responses<\/strong>.<\/p>\n\n\n\n

Conversation memory allows the chatbot to take previous interactions into account, while webhooks and message-sending configurations deliver the response back to the customer.<\/p>\n\n\n\n

The result goes beyond a simple keyword-based autoresponder. It becomes a conversational operation that can integrate with CRMs, e-commerce platforms, scheduling systems, ERPs, knowledge bases, and internal systems.<\/p>\n\n\n\n

What is an AI-powered WhatsApp chatbot with n8n, and how does it work?<\/h2>\n\n\n\n

An AI-powered WhatsApp chatbot is a system capable of receiving a message, understanding its content, generating a response, and sending it back to the user without requiring an agent to manually perform every step.<\/p>\n\n\n\n

Traditional bots usually depend on menus, keywords, and predefined paths. A chatbot connected to a language model, on the other hand, can understand natural-language questions and generate more flexible responses<\/strong>.<\/p>

\"\"<\/a><\/div><\/div>\n\n\n\n

That does not mean letting AI respond without any controls. A professional chatbot needs a clear objective, context, boundaries, reliable data sources, and rules for handing conversations over to human agents.<\/p>\n\n\n\n

In the workflow covered in this tutorial:<\/p>\n\n\n\n

    \n
  1. The customer sends a message through WhatsApp.<\/li>\n\n\n\n
  2. Z-API forwards the event to n8n through a webhook.<\/li>\n\n\n\n
  3. n8n identifies the contact and extracts the message.<\/li>\n\n\n\n
  4. The OpenAI model receives the text and instructions.<\/li>\n\n\n\n
  5. Memory, when configured, retrieves the session context.<\/li>\n\n\n\n
  6. n8n receives the generated response.<\/li>\n\n\n\n
  7. Z-API sends the text back through WhatsApp.<\/li>\n<\/ol>\n\n\n\n

    <\/p>\n\n\n\n

    Z-API<\/a> provides a REST API and webhooks for interacting with WhatsApp and receiving events from the connected number.<\/p>\n\n\n\n

    What tools do you need?<\/h2>\n\n\n\n

    To recreate this architecture, you need a Z-API instance, an n8n account, and OpenAI credentials.<\/p>\n\n\n\n

    Component<\/strong><\/th>Role<\/strong><\/th>Required information<\/strong><\/th><\/tr><\/thead>
    Z-API<\/strong><\/td>Receive and send messages<\/td>Instance ID, Token, and Client Token if enabled<\/td><\/tr>
    n8n<\/strong><\/td>Orchestrate events and integrations<\/td>Workflow and HTTPS webhook URL<\/td><\/tr>
    OpenAI<\/strong><\/td>Interpret messages and generate responses<\/td>API Key and model<\/td><\/tr>
    Memory<\/strong><\/td>Maintain context across interactions<\/td>Session identifier and memory configuration<\/td><\/tr>
    CRM\/internal system<\/strong><\/td>Retrieve or store data<\/td>API or corresponding credentials<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

    Z-API also provides a community node for n8n<\/strong>, which can simplify message-sending operations. Alternatively, you can use an HTTP Request node with the API\u2019s send-text<\/code> endpoint.<\/p>\n\n\n\n

    On n8n Cloud<\/strong><\/a>, the availability of community nodes depends on the platform\u2019s verification rules. In self-hosted environments, they can be installed directly.<\/p>\n\n\n\n

    How do you configure incoming messages with Z-API?<\/h2>\n\n\n\n

    The first step is to create a workflow in n8n that can receive external requests. Add a Webhook<\/strong> node, set the method to POST, and copy the generated URL.<\/p>\n\n\n\n

    n8n provides both a test URL and a production URL. During development, use the test URL so you can inspect incoming data. Once the workflow has been published, switch to the production URL.<\/p>\n\n\n\n

    In Z-API, the incoming-message webhook is configured with a PUT request to update-webhook-received<\/code>. The URL you provide must use HTTPS<\/strong>.<\/p>\n\n\n\n

    For example:<\/p>\n\n\n\n

    curl --request PUT \\\n  --url https:\/\/api.z-api.io\/instances\/{instanceId}\/token\/{token}\/update-webhook-received \\\n  --header 'Client-Token: YOUR_CLIENT_TOKEN' \\\n  --header 'Content-Type: application\/json' \\\n  --data '{\n    \"value\": \"https:\/\/your-n8n.com\/webhook\/whatsapp-receive\"\n  }'\n<\/code><\/pre>\n\n\n\n
    Replace these values with the credentials and URL from your own instance. Never publish tokens in articles, repositories, or screenshots<\/strong>.<\/p>\n\n\n\n
    Adjust your filters before testing<\/h3>\n\n\n\n
    If your chatbot does not need to process messages sent by the connected number itself, disable those notifications. Z-API provides the update-notify-sent-by-me<\/code> endpoint to control this behavior.<\/p>\n\n\n\n
    This prevents the bot from processing its own reply and entering a message loop.<\/p>\n\n\n\n
    To ignore groups, the webhook includes the isGroup<\/code> attribute. In n8n, you can add a filter so the workflow continues only when isGroup<\/code> is false<\/code><\/strong>.<\/p>\n\n\n\n
    Your filters should match your use case: a one-to-one customer service chatbot may ignore groups, while other automations may need to process them<\/strong>.<\/p>\n\n\n\n
    Still exploring what Z-API can do? Read our guide about Z-API vs. Official WhatsApp API.<\/a><\/strong><\/p>\n\n\n\n
    How do you process the incoming payload in n8n?<\/h2>\n\n\n\n
    After the Webhook, you can add a Code node in JavaScript to transform the incoming event into a predictable structure<\/strong>.<\/p>\n\n\n\n
    The Z-API webhook includes fields such as phone number, message ID, timestamp, source, and content type. For text messages, the content appears in text.message<\/code>.<\/p>\n\n\n\n
    Here is an example normalization:<\/p>\n\n\n\n
    const body = $json.body ?? $json;\n\nreturn [{\n  json: {\n    phone: body.phone,\n    text: body.text?.message?.trim() ?? \"\",\n    messageId: body.messageId,\n    timestamp: body.momment,\n    fromMe: body.fromMe,\n    isGroup: body.isGroup,\n    raw: body\n  }\n}];\n<\/code><\/pre>\n\n\n\n
    The phone<\/code>, messageId<\/code>, momment<\/code>, fromMe<\/code>, and isGroup<\/code> fields are part of the callback documented by Z-API.<\/p>\n\n\n\n
    This example handles text messages.<\/strong> Images, audio, video, documents, and other content types have their own structures and should be handled according to the payload received.<\/p>\n\n\n\n
    After normalization, use filter nodes to stop the workflow when there is no phone number or text, when fromMe<\/code> is true<\/code>, or when the event does not match your use case.<\/p>\n\n\n\n
    Validating the payload before calling OpenAI helps prevent unnecessary processing, errors, and response loops.<\/strong><\/p>\n\n\n\n
    How do you configure the AI Agent in n8n?<\/h2>\n\n\n\n
    Once the data has been organized, add an AI Agent<\/strong> node. It receives the input, uses a chat model, and can call tools to perform tasks.<\/p>\n\n\n\n
    In current versions of n8n, the AI Agent works as a Tools Agent and needs at least one connected tool<\/strong>.<\/p>\n\n\n\n
    For a chatbot that only generates responses, a Basic LLM Chain may be enough. If you need to retrieve order data, check schedules, or access internal systems, use the AI Agent with the appropriate tools and permissions.<\/p>\n\n\n\n
    Connect the OpenAI chat model<\/h3>\n\n\n\n
    Add the OpenAI Chat Model<\/strong>, configure your API Key, and select an available model.<\/p>\n\n\n\n
    The video may use a specific model, but your choice should take cost, speed, and task complexity into account<\/strong>, since available models change over time. OpenAI publishes current model options and API pricing in its documentation.<\/p>\n\n\n\n
    Lower-cost models may work well for FAQs and initial triage, while more complex tasks may require more capable models.<\/p>\n\n\n\n
    How do you write the system prompt?<\/h2>\n\n\n\n
    The prompt defines the chatbot\u2019s purpose, behavior, boundaries, and escalation criteria<\/strong>.<\/p>\n\n\n\n
    For example:<\/p>\n\n\n\n
    \n
    You are the virtual assistant for Flower & Gifts, a flower shop specializing in bouquets and gifts.
    Help customers choose products and provide delivery times and opening hours only when that information is available.
    Reply in American English, clearly and concisely.
    Do not invent prices, inventory, or delivery times.
    For payments, order changes, complaints, or requests for human support, hand the conversation over to the team.
    Do not claim that an action has been completed unless the system confirms it.<\/p>\n<\/blockquote>\n\n\n\n
    The same structure can be adapted to different businesses.<\/p>\n\n\n\n
    The prompt guides the model, but critical controls should live in the workflow and tool permissions<\/strong>, not only in the instructions.<\/p>\n\n\n\n
    How do you add conversation memory?<\/h2>\n\n\n\n
    Without memory, each message may be processed without any context from previous interactions. With memory, the agent can take recent exchanges into account.<\/p>\n\n\n\n
    In the tutorial, Simple Memory<\/strong> can use the phone number as the session key:<\/p>\n\n\n\n
    Session Key: {{$json.phone}}\n\nContext Window Length: 10\n<\/code><\/pre>\n\n\n\n
    The Context Window Length represents the number of previous interactions included in the context<\/strong>.<\/p>\n\n\n\n
    A phone number is a convenient session key, but it should be normalized. In larger operations, an internal CRM ID may be more appropriate.<\/p>\n\n\n\n
    Memory is not a knowledge base<\/strong>. For pricing, products, policies, or up-to-date information, the agent should query specific sources such as APIs, databases, or RAG systems.<\/p>\n\n\n\n
    There is also an important limitation: n8n advises against using Simple Memory in production workflows running in queue mode<\/strong>. In that scenario, use persistent memory such as Redis or Postgres instead.<\/p>\n\n\n\n
    How do you send the response back to WhatsApp?<\/h2>\n\n\n\n
    After the AI Agent generates a response, you can use a Code<\/strong> node to validate or normalize the text before sending it. This step is optional.<\/p>\n\n\n\n
    The agent\u2019s response often appears in a field such as output<\/code>, but you should confirm the actual node output structure before mapping the expression.<\/p>\n\n\n\n
    In the tutorial, the response can be sent through the Z-API WhatsApp community node using the Send Text Message operation<\/strong>. The phone number comes from the webhook, while the message comes from the agent output.<\/p>\n\n\n\n
    You can also send the message directly through the Z-API API:<\/p>\n\n\n\n
    curl --request POST \\\n  --url https:\/\/api.z-api.io\/instances\/{instanceId}\/token\/{token}\/send-text \\\n  --header 'Client-Token: YOUR_CLIENT_TOKEN' \\\n  --header 'Content-Type: application\/json' \\\n  --data '{\n    \"phone\": \"5511999999999\",\n    \"message\": \"Hello! How can I help?\"\n  }'\n<\/code><\/pre>\n\n\n\n
    The send-text<\/code> endpoint uses phone<\/code> and message<\/code> in the request body. In n8n, these values should come from previous nodes:<\/p>\n\n\n\n
    Phone: {{$node[\"Code \u2013 Normalize Input\"].json.phone}}\n\nMessage: {{$node[\"AI Agent\"].json.output}}\n<\/code><\/pre>\n\n\n\n
    Avoid hardcoding the phone number or message in the workflow<\/strong>. When the send request is accepted, Z-API returns identifiers such as zaapId<\/code>, messageId<\/code>, and id<\/code>, which can be stored for correlation, status tracking, and troubleshooting<\/strong>.<\/p>\n\n\n\n
    How do you test the chatbot without repeatedly sending messages?<\/h2>\n\n\n\n
    During development, you can capture the JSON from a real execution and reuse it in your tests.<\/p>\n\n\n\n
    n8n allows you to pin data from a node and reuse it in manual executions<\/strong>, avoiding additional calls to the external system. (github.com<\/strong><\/a>)<\/p>\n\n\n\n
    Capture a real message, save the payload, and use it to test normalization, prompts, and memory.<\/p>\n\n\n\n
    If the sending node is still active, the workflow may send a real message<\/strong>, so stop the flow before that step when you only want to test the logic.<\/p>\n\n\n\n
    You should also test greetings, incomplete questions, out-of-scope requests, requests for human support, and different media types.<\/p>\n\n\n\n
    Text, image, audio, video, and document messages have different payload structures. Files received through Z-API remain available for 30 days and require type-specific handling<\/strong>. (developer.z-api.io<\/strong><\/a>)<\/p>\n\n\n\n
    How do you prevent loops and duplicate responses?<\/h2>\n\n\n\n
    A loop can occur when the bot processes a message sent by its own number as though it were a new incoming message.<\/p>\n\n\n\n
    When those events are not needed, disable notifySentByMe<\/code>. Z-API provides a dedicated setting for this. (developer.z-api.io<\/strong><\/a>)<\/p>\n\n\n\n
    If you need to keep the setting enabled, filter out events where fromMe: true<\/code>.<\/p>\n\n\n\n
    It is also a good idea to store the messageId<\/code> of processed events and ignore IDs that have already been handled<\/strong>. This idempotency reduces the risk of duplicate processing.<\/p>\n\n\n\n
    If a customer sends several messages in quick succession, parallel executions may occur. For more complex workflows, use queues or session-level controls to preserve processing order<\/strong>.<\/p>\n\n\n\n
    How do you create a human fallback?<\/h2>\n\n\n\n
    Your chatbot needs an exit path for situations where it does not have enough information, encounters an exception, or receives a request for human support.<\/p>\n\n\n\n
    The handoff can be triggered by business rules, explicit requests, missing data, or repeated failures<\/strong>.<\/p>\n\n\n\n
    When this happens, pause the automation for that conversation and send the context to the support team.<\/p>\n\n\n\n
    \n
    \u201cGot it. I\u2019ll hand your conversation over to a member of our team, along with the context you\u2019ve already provided.\u201d<\/p>\n<\/blockquote>\n\n\n\n
    The fallback should also account for technical failures. If the AI model is unavailable while WhatsApp remains operational, the workflow can send an alternative response.<\/p>\n\n\n\n
    If the Z-API send operation itself fails, log the error, alert the team, and apply the recovery strategy defined for your operation<\/strong>.<\/p>\n\n\n\n
    Are you already aware of the new pricing for WhatsApp Business? Read our article and find out how to prepare for October 2026.<\/a><\/p>\n\n\n\n
    Security: how do you protect tokens and data?<\/h2>\n\n\n\n
    Z-API and OpenAI credentials are sensitive information. Never publish tokens in code, screenshots, videos, or repositories<\/strong>. In n8n, use the platform\u2019s credential system and appropriate access controls.<\/p>\n\n\n\n
    In Z-API, the Client Token can add an additional layer of protection to your instances. When enabled, it must be included with authorized requests.<\/p>\n\n\n\n
    The webhook also requires attention: use HTTPS, minimize logged data, and avoid storing unnecessary personal information in logs.<\/p>\n\n\n\n
    If the chatbot accesses CRM records, order information, or financial data, apply the principle of least privilege to all credentials and tools available to it<\/strong>.<\/p>\n\n\n\n
    The prompt can instruct the agent not to reveal internal data or claim that unconfirmed actions were completed, but security controls should exist in the workflow and permission layer, not only in the prompt.<\/p>\n\n\n\n
    How do you turn the chatbot into a sales and support agent?<\/h2>\n\n\n\n
    The basic workflow answers questions. With additional integrations, it can also execute controlled processes<\/strong>.<\/p>\n\n\n\n
    Tools connected to the AI Agent can retrieve orders, check schedules, register leads, or update opportunities. n<\/a><\/strong>8n<\/strong><\/a> orchestrates those integrations, while Z-API maintains communication with WhatsApp.<\/p>\n\n\n\n
    Stage<\/strong><\/th>Action<\/strong><\/th>Possible integration<\/strong><\/th><\/tr><\/thead>
    Capture<\/td>Identifies the contact and their interest<\/td>CRM<\/td><\/tr>
    Qualification<\/td>Collects needs, timeframe, and budget<\/td>CRM or database<\/td><\/tr>
    Recommendation<\/td>Retrieves suitable options<\/td>Catalog or internal system<\/td><\/tr>
    Conversion<\/td>Sends a proposal, checkout, or scheduling option<\/td>ERP, e-commerce, or calendar<\/td><\/tr>
    Follow-up<\/td>Re-engages opportunities according to defined rules<\/td>CRM and n8n<\/td><\/tr>
    Handoff<\/td>Escalates complex cases<\/td>Customer service platform<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    AI should not invent operational information: prices, inventory, delivery times, and status updates must come from the system responsible for that data<\/strong>.<\/p>\n\n\n\n
    Metrics to track chatbot performance<\/h2>\n\n\n\n
    A chatbot should not be evaluated only by message volume.<\/p>\n\n\n\n
    Track metrics such as automated resolution rate, handoff rate, messages per interaction, cost per resolution, qualified leads, and conversions.<\/p>\n\n\n\n
    You should also analyze failures: which questions went unanswered, where customers dropped out of the flow, and which requests required more human intervention<\/strong>.<\/p>\n\n\n\n
    This data helps improve prompts, memory, integrations, and the overall experience.<\/p>\n\n\n\n
    Metric<\/strong><\/th>What it reveals<\/strong><\/th><\/tr><\/thead>
    Automated resolution rate<\/td>How much the chatbot resolves without human help<\/td><\/tr>
    Handoff<\/td>Which requests require human support<\/td><\/tr>
    Messages per interaction<\/td>Workflow efficiency<\/td><\/tr>
    Response time<\/td>Operational speed<\/td><\/tr>
    Technical errors<\/td>Workflow reliability<\/td><\/tr>
    Qualified leads<\/td>Contribution to sales<\/td><\/tr>
    Conversion by journey<\/td>Business results<\/td><\/tr>
    Cost per resolution<\/td>Automation viability<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    Mistakes to avoid<\/h2>\n\n\n\n