WhatsApp Chatbot API — Build Intelligent Conversations

Create AI-powered chatbots, rule-based responders, and conversational flows on WhatsApp. Connect your logic to our API and handle customer conversations automatically.

How a WhatsApp Chatbot Works

A WhatsApp chatbot has three components: the connection layer, the processing layer, and the response layer. Our API handles the connection layer entirely. You build the processing and response layers.

The flow is simple:

1. A customer sends a message to your WhatsApp number
2. Our API receives the message and forwards it to your webhook URL
3. Your webhook handler processes the message — this is where your chatbot logic lives
4. Your handler calls our API to send a reply back to the customer
5. The customer receives the reply in their WhatsApp chat

This entire loop typically completes in under 200 milliseconds. The customer sees the response almost instantly, which creates a natural conversational experience.

Chatbot Architecture Patterns

Pattern 1: Simple Rule-Based Bot

The simplest chatbot uses keyword matching. When a customer sends "track order", the bot responds with the order tracking link. When they send "hours", the bot responds with business hours. This pattern works well for FAQ-style bots and can be implemented in under 50 lines of code.

# Python example - simple rule-based bot
def handle_message(message):
    msg = message.lower()
    if 'track' in msg or 'order' in msg:
        return 'Track your order here: https://example.com/track'
    elif 'hours' in msg:
        return 'We are open Mon-Fri, 9AM-6PM.'
    elif 'help' in msg:
        return 'Type: track, hours, or contact for support.'
    else:
        return 'I am not sure how to help. Type "help" for options.'

Pattern 2: Stateful Conversation Bot

A more sophisticated bot tracks conversation state. The customer goes through a flow — selecting a menu option, providing information, confirming an action. Each step depends on the previous one. You need to store conversation state (in a database, Redis, or in-memory) and reference it when processing each new message.

This pattern is ideal for appointment booking, order placement, lead qualification, and any multi-step process. The bot asks a question, waits for the answer, asks the next question, and so on until the flow is complete.

Pattern 3: AI-Powered Bot

Connect our webhook to an AI model (OpenAI, Claude, or any LLM) and let the bot handle free-form conversations. The AI generates responses based on your system prompt, knowledge base, and conversation history. This works remarkably well for customer support, product questions, and general inquiries.

// Node.js example - AI-powered bot
app.post('/webhook', async (req, res) => {
    const { message, from } = req.body.data;

    // Call your AI model
    const aiResponse = await openai.chat.completions.create({
        model: 'gpt-4',
        messages: [
            { role: 'system', content: 'You are a helpful support agent for...' },
            { role: 'user', content: message }
        ]
    });

    // Send the AI response back via WhatsApp
    await fetch('https://api2whats.com/send-text', {
        method: 'POST',
        headers: { 'Authorization': 'Bearer ' + API_KEY },
        body: JSON.stringify({
            to: from,
            message: aiResponse.choices[0].message.content
        })
    });

    res.json({ success: true });
});

Pattern 4: Hybrid Bot

The most practical approach combines rules, state, and AI. Simple queries get fast rule-based responses. Complex queries trigger the AI. If the AI cannot resolve the issue, the conversation escalates to a human agent. This gives you the speed of rules, the flexibility of AI, and the safety net of human support.

Building a Chatbot: Step by Step

Step 1: Set Up the API Connection

Create an account, connect a WhatsApp number, and get your API key. Configure your webhook URL in the dashboard or via the API. Test that incoming messages reach your server by checking the webhook logs.

Step 2: Design Your Conversation Flows

Map out the conversations your bot needs to handle. Start with the top 5-10 most common customer inquiries. For each one, define:

• What triggers the flow (keywords, intents, or direct commands)
• What questions the bot asks
• What information the bot needs from the customer
• What response or action the bot provides
• What happens if the bot cannot help (escalation path)

Step 3: Implement the Webhook Handler

Write a server endpoint that receives POST requests from our API. Parse the incoming message, run it through your chatbot logic, and send a response using our API. Handle edge cases: empty messages, media messages, messages from numbers you do not recognize.

Step 4: Test and Iterate

Connect your personal number as a test instance. Send messages to it from another phone. Test every conversation flow. Check that the bot handles unexpected inputs gracefully. Monitor the webhook logs for errors.

Step 5: Deploy and Monitor

Deploy your webhook handler to a production server. Set up monitoring for response times, error rates, and conversation completion rates. Use the message status webhooks to track delivery and read rates.

Use Cases for WhatsApp Chatbots

Customer Support

Handle the most common support queries automatically: order status, return policies, store hours, account questions. Reduce ticket volume by 40-60% while providing instant responses 24/7. Escalate complex issues to human agents with full conversation context.

E-Commerce

Send order confirmations, shipping updates, and delivery notifications automatically. Let customers track orders by sending their order number. Recommend products based on purchase history. Handle returns and exchanges through conversational flows.

Appointment Booking

Let customers book appointments directly in WhatsApp. Show available time slots, collect necessary information, send confirmation messages, and handle rescheduling. Integrate with your calendar system to prevent double-booking.

Lead Generation

Qualify leads through conversational flows. Ask about budget, timeline, requirements, and company size. Score leads automatically and route qualified prospects to your sales team. Send follow-up messages at scheduled intervals.

Internal Tools

Build internal chatbots for your team. IT helpdesk bots that handle password resets and system status checks. HR bots that answer policy questions. Operations bots that report on system health and trigger alerts.

Best Practices

• Keep responses short — WhatsApp is a mobile-first platform. Long paragraphs get skipped. Aim for 1-3 sentences per response.
• Use quick replies — When possible, offer numbered options ("Reply 1 for order status, 2 for returns") instead of open-ended questions.
• Always provide an exit — Every conversation flow should have a way to reach a human agent. "Type 'agent' to talk to a person."
• Personalize — Use the customer's name and reference their order or account. Personalized messages get 3-5x higher engagement.
• Test with real users — Your bot will be used by real people with real questions you did not anticipate. Test early and often.
• Monitor and improve — Track which messages cause confusion or abandonment. Refine your flows based on actual usage data.

Advanced: Multi-Language Support

If your customers speak multiple languages, your chatbot should handle that. There are two approaches:

Language Detection

Analyze the incoming message to detect the language, then respond in the same language. For rule-based bots, maintain separate keyword sets for each language. For AI-powered bots, instruct the model to respond in the detected language.

Language Selection

Start the conversation by asking the customer to select their language: "Reply 1 for English, 2 for Arabic, 3 for Spanish." This is simpler to implement and more reliable than automatic detection.

Our API supports Unicode, so messages in Arabic, Hebrew, Hindi, Chinese, and any other script work perfectly. Right-to-left text is handled by the WhatsApp client itself.

Integrating With AI Models

The most powerful chatbots use large language models to generate responses. Here is how to integrate popular AI models:

OpenAI (GPT-4)

Send the incoming WhatsApp message to the OpenAI API with a system prompt describing your business and how the bot should respond. Pass the conversation history for context. Return the AI's response to the customer via our API.

Claude (Anthropic)

Similar to OpenAI integration. Claude excels at nuanced conversations and following complex instructions. Use the Messages API with a system prompt tailored to your use case.

Local Models

For businesses that need data privacy, run a local LLM (like Llama or Mistral) on your own servers. The integration pattern is the same — receive the message, send it to your local model, return the response.

Cost considerations: AI-powered bots cost more per conversation than rule-based bots, but they handle a much wider range of queries. Start with rule-based for the top 20 queries and add AI for the long tail.