Building a WhatsApp Chatbot for Ugandan Businesses with Node.js

Walk into any market in Kampala and ask a vendor how they take orders. Most will show you their WhatsApp. Small businesses in Uganda run on WhatsApp: orders come in as messages, confirmations go out as voice notes, and payment screenshots fill group chats. This is not a tech trend. It is how commerce works on the ground.

The numbers support what you see on the ground. WhatsApp is the most-used messaging app in Uganda. Most smartphone users open it multiple times per day. Compare this to email (rarely checked by many Ugandans), custom mobile apps (require downloads that eat data bundles), or websites (require browsing that feels slow on 3G).

A chatbot on WhatsApp does not ask customers to change their behavior. They already message businesses on WhatsApp. The bot just makes the business side faster and available at any hour.

Businesses that benefit most:

• Clinics and health centers: Patients book appointments, get reminders, and receive test result notifications.
• Restaurants and food vendors: Customers place orders, get estimated delivery times, and pay via MoMo.
• Salons and barbershops: Clients book time slots without calling.
• Schools: Parents receive fee reminders, exam schedules, and school announcements.
• E-commerce sellers: Product inquiries, order tracking, and payment confirmation.
• Event organizers: Ticket sales, event info, and attendee check-in.

As a developer in Uganda, building WhatsApp chatbots is a practical and sellable skill. Local businesses understand WhatsApp. They do not need to be convinced that their customers use it. The conversation starts at "How much does a bot cost?" rather than "Why do I need this?"

The WhatsApp Business app (the one you download from Google Play) is meant for manual use. You type replies yourself. The WhatsApp Business API is the programmatic version: your code sends and receives messages through an API.

Three ways to access the API:

• WhatsApp Cloud API (Meta): Free to start, you pay per conversation. Direct access through Meta's developer portal. Requires a Facebook Business account and a verified phone number. The most cost-effective option for small businesses.
• Twilio: A third-party provider that wraps the WhatsApp API in a simpler interface. Slightly higher per-message cost but better documentation and easier setup. Good if you already use Twilio for SMS.
• 360dialog: Another third-party provider popular in Africa. Competitive pricing and good support for African businesses.

How it works architecturally:

1. A customer sends a WhatsApp message to your business number.
2. The API provider sends a webhook (HTTP POST request) to your server with the message content.
3. Your server parses the message, determines the appropriate response, and sends a reply through the API.
4. The customer receives the reply in their WhatsApp chat.

This is the same webhook pattern used in MoMo payment callbacks. If you have built a MoMo integration, the architecture will feel familiar: receive a POST request, process it, take action, respond.

Message types you can send:

• Text messages (plain replies)
• Interactive buttons (up to 3 buttons the user can tap)
• List messages (a menu of options the user selects from)
• Template messages (pre-approved messages for notifications, reminders, and outbound communication)
• Media messages (images, documents, PDFs)

Interactive buttons and list messages are where the chatbot becomes powerful. Instead of asking the customer to type "1 for appointments, 2 for orders," you present tappable buttons. This reduces errors and makes the experience feel polished.

Here is the structure of a basic WhatsApp chatbot using Node.js and Express, connected to the WhatsApp Cloud API.

Project setup:

mkdir whatsapp-bot && cd whatsapp-bot
npm init -y
npm install express axios dotenv

Core server structure:

// server.js
const express = require('express');
require('dotenv').config();

const app = express();
app.use(express.json());

// Webhook verification (required by WhatsApp Cloud API)
app.get('/webhook', (req, res) => {
  const mode = req.query['hub.mode'];
  const token = req.query['hub.verify_token'];
  const challenge = req.query['hub.challenge'];

  if (mode === 'subscribe' && token === process.env.VERIFY_TOKEN) {
    res.status(200).send(challenge);
  } else {
    res.sendStatus(403);
  }
});

// Receive incoming messages
app.post('/webhook', (req, res) => {
  const body = req.body;

  if (body.object === 'whatsapp_business_account') {
    const entry = body.entry[0];
    const changes = entry.changes[0];
    const message = changes.value.messages?.[0];

    if (message) {
      const from = message.from; // sender phone number
      const text = message.text?.body?.toLowerCase() || '';

      handleMessage(from, text);
    }
  }

  res.sendStatus(200); // always acknowledge quickly
});

app.listen(3000, () => console.log('Bot running on port 3000'));

Message handling logic:

const axios = require('axios');

async function handleMessage(to, text) {
  let reply = '';

  if (text.includes('menu') || text.includes('hi') || text.includes('hello')) {
    reply = 'Welcome! Choose an option:
1. Book appointment
2. Check order status
3. View prices
4. Pay via MoMo';
  } else if (text === '1' || text.includes('appointment')) {
    reply = 'What day works for you? Reply with a date like "Monday" or "2026-06-10".';
  } else if (text === '4' || text.includes('pay')) {
    reply = 'To pay, I will send a MoMo prompt to your number. Reply with the amount in UGX.';
  } else {
    reply = 'I did not understand that. Type "menu" to see options.';
  }

  await sendMessage(to, reply);
}

async function sendMessage(to, text) {
  await axios.post(
    `https://graph.facebook.com/v18.0/${process.env.PHONE_NUMBER_ID}/messages`,
    {
      messaging_product: 'whatsapp',
      to,
      type: 'text',
      text: { body: text },
    },
    {
      headers: {
        Authorization: `Bearer ${process.env.WHATSAPP_TOKEN}`,
        'Content-Type': 'application/json',
      },
    }
  );
}

This is a minimal starting point. A production bot would use a state machine or conversation context to track where each user is in the flow, rather than relying purely on keyword matching. But this structure demonstrates the core pattern: receive message, parse intent, send reply.

Testing locally: Use ngrok to expose your local server to the internet so WhatsApp can send webhooks to it. Run npx ngrok http 3000 and use the generated URL as your webhook endpoint in the WhatsApp Cloud API configuration.

The most powerful feature for a Ugandan WhatsApp bot is the ability to collect payments inside the conversation. A customer orders food, and the bot sends a MoMo payment prompt to their phone. They confirm with their PIN. The bot receives a callback confirming payment. No screenshots. No manual verification.

The payment flow inside WhatsApp:

1. Customer tells the bot they want to pay (selects "Pay via MoMo" or types "pay").
2. Bot asks for the amount (or calculates it from the order).
3. Bot sends a payment request to the MoMo Collections API with the customer's phone number and amount.
4. MoMo sends a USSD prompt to the customer's phone.
5. Customer enters their MoMo PIN to confirm.
6. MoMo sends a callback to your server with the transaction result.
7. Your server updates the order status and the bot sends a confirmation message on WhatsApp: "Payment of UGX 25,000 received. Your order is confirmed."

Key implementation details:

• Phone number matching: The WhatsApp sender's number and the MoMo number are often the same (Ugandans typically use one phone for both). Confirm with the user before sending the payment request.
• Timeout handling: If the customer does not confirm the MoMo prompt within 60 to 90 seconds, your bot should send a follow-up: "Your MoMo payment is still pending. Please check your phone for the approval prompt."
• Dual provider support: Some customers use Airtel Money instead of MTN MoMo. A production bot should ask which provider the customer uses and route the payment request accordingly.
• Transaction records: Store every payment attempt in your database with the WhatsApp sender ID, MoMo transaction ID, amount, status, and timestamp. This is your reconciliation trail.

The architecture is two asynchronous flows running in parallel: the WhatsApp message flow and the MoMo payment flow. They converge when the MoMo callback arrives and your server sends the confirmation message through WhatsApp. Getting this right requires careful state management, but it is the same pattern you would use in any MoMo integration. The WhatsApp part just adds a notification layer.

To learn the MoMo request-callback architecture in depth, the M-Pesa Integration course (~UGX 280,000) teaches the pattern thoroughly. The architecture is identical for MoMo: request, wait, callback, update. For the full backend stack including databases, APIs, and deployment, the Full-Stack + AI course (~UGX 3,400,000) covers everything you need.

Here are four concrete bot implementations that Ugandan businesses will pay for.

1. Clinic appointment bot: A health center in Kampala receives 40+ calls per day for appointment bookings. A WhatsApp bot handles this automatically. The patient messages the clinic's WhatsApp number, selects a doctor or service from a list, picks an available time slot, and receives a confirmation with reminder messages 24 hours and 1 hour before the appointment. The clinic staff sees new bookings on a dashboard without answering a single phone call.

2. Restaurant ordering bot: A Kampala restaurant takes orders via WhatsApp already, but a human reads each message, types it into the POS system, and replies manually. The bot automates this: the customer sees the menu as a list message, selects items, confirms the order, pays via MoMo, and receives an estimated delivery time. Kitchen staff see orders in a queue. The restaurant handles three times the volume without hiring more order-takers.

3. School fee reminder bot: A school sends fee reminders to 800 parents at the start of each term. Previously, teachers made phone calls or sent individual messages. The bot sends templated messages with the student name, amount due, and a "Pay Now" button that triggers a MoMo payment request. Parents who have paid receive receipts. The bursar sees a real-time dashboard of collections.

4. Event ticket bot: An event organizer in Kampala sells tickets through a WhatsApp bot. Customers receive event details, select ticket categories, pay via MoMo or Airtel Money, and receive a QR code ticket on WhatsApp. At the door, an attendant scans the QR code from the customer's phone. No printing, no physical tickets, no cash handling at the gate.

Pricing your bot development: Small Ugandan businesses typically pay UGX 500,000 to UGX 3,000,000 for a custom WhatsApp chatbot, depending on complexity. Ongoing hosting and maintenance can be charged monthly. A bot with MoMo integration commands higher rates because it directly generates revenue for the business. This is a real income stream for developers, not just a portfolio project.