WhatsApp Integration

WhatsApp Integration

WhatsApp is the world's most widely used messaging platform, with over two billion active users. Deploying your Chatsby AI agent on WhatsApp allows your customers to get instant, intelligent support through the app they already use every day. This guide covers the complete integration architecture, step-by-step setup via both Meta Cloud API and Twilio, message formatting considerations, WhatsApp's session and pricing rules, and a production readiness checklist.

Overview

The WhatsApp integration enables your Chatsby AI agent to:

• Receive incoming messages from customers on WhatsApp
• Process those messages through your trained AI agent
• Send intelligent, context-aware responses back to the customer
• Capture leads and contact information during WhatsApp conversations
• Escalate to human agents when the AI cannot resolve an issue

Prerequisites

Architecture

Understanding the message flow is essential for setting up and debugging the integration.

Customer (WhatsApp) --> WhatsApp Cloud API --> Your Webhook Server --> Chatsby API --> Your Server --> WhatsApp Cloud API --> Customer (WhatsApp)

The flow works as follows:

1. A customer sends a message on WhatsApp.
2. WhatsApp's Cloud API (or Twilio) delivers the message to your webhook endpoint via an HTTP POST request.
3. Your server extracts the message text and sends it to the Chatsby Conversations API.
4. Chatsby processes the message through your trained agent and returns a response.
5. Your server sends the response back to the customer via the WhatsApp Cloud API (or Twilio API).

Setup via Meta Cloud API

This is the direct, officially supported method from Meta. It is free to use (you only pay WhatsApp's per-conversation charges) and gives you full control over the integration.

// Express.js example - Webhook verification
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 === 'YOUR_VERIFY_TOKEN') {
    res.status(200).send(challenge);
  } else {
    res.sendStatus(403);
  }
});

// Express.js example - Handle incoming WhatsApp message
app.post('/webhook', async (req, res) => {
  const message = req.body?.entry?.[0]?.changes?.[0]?.value?.messages?.[0];
 
  if (message && message.type === 'text') {
    const customerPhone = message.from;
    const messageText = message.text.body;
 
    // Send to Chatsby API
    const chatsbyResponse = await fetch(
      `https://api.chatsby.co/v1/agents/YOUR_AGENT_ID/conversations`,
      {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_CHATSBY_API_KEY',
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          message: messageText,
          session_id: customerPhone, // Use phone as session ID
        }),
      }
    );
 
    const data = await chatsbyResponse.json();
    const agentReply = data.response;
 
    // Send reply back to WhatsApp
    await sendWhatsAppMessage(customerPhone, agentReply);
  }
 
  res.sendStatus(200);
});

async function sendWhatsAppMessage(to, text) {
  await fetch(
    'https://graph.facebook.com/v18.0/YOUR_PHONE_NUMBER_ID/messages',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_WHATSAPP_ACCESS_TOKEN',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        messaging_product: 'whatsapp',
        to: to,
        type: 'text',
        text: { body: text },
      }),
    }
  );
}

Setup via Twilio

Twilio provides a managed WhatsApp Business API that simplifies the setup process, especially if you are already using Twilio for other communication needs.

app.post('/twilio-webhook', async (req, res) => {
  const messageText = req.body.Body;
  const customerPhone = req.body.From; // e.g., "whatsapp:+1234567890"
 
  // Forward to Chatsby API
  const chatsbyResponse = await fetch(
    `https://api.chatsby.co/v1/agents/YOUR_AGENT_ID/conversations`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_CHATSBY_API_KEY',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        message: messageText,
        session_id: customerPhone,
      }),
    }
  );
 
  const data = await chatsbyResponse.json();
 
  // Respond via TwiML
  const twiml = `<Response><Message>${data.response}</Message></Response>`;
  res.type('text/xml').send(twiml);
});

Message Format Considerations

WhatsApp messages are text-only when sent via the standard messaging API. Keep the following in mind:

• No rich widgets --- The Chatsby chat widget UI (buttons, carousels, quick replies) does not render on WhatsApp. Responses are delivered as plain text.
• Message length --- WhatsApp supports messages up to 4,096 characters. If your agent generates longer responses, consider truncating or splitting them.
• Formatting --- WhatsApp supports basic formatting: *bold*, _italic_, ~strikethrough~, and ```monospace```. Configure your agent's response style accordingly.
• No images or files --- Standard text responses do not include images. If you need to send media, use the WhatsApp Cloud API's media message type separately.

Session Management: The 24-Hour Window

WhatsApp enforces a 24-hour messaging window policy:

• Customer-initiated conversations: When a customer messages you first, you have a 24-hour window to respond with any number of messages. This window resets with each new customer message.
• Business-initiated conversations: To message a customer outside the 24-hour window, you must use a pre-approved Message Template (see below).
• Session expiration: If 24 hours pass without a customer message, you can no longer send free-form messages until the customer reaches out again.

Template Messages for Re-Engagement

To proactively reach out to customers after the 24-hour window closes, create Message Templates in your WhatsApp Business Manager:

1. Go to WhatsApp Manager > Message Templates.
2. Create a template with a category (e.g., Marketing, Utility) and submit it for Meta approval.
3. Once approved, use the template via the WhatsApp Cloud API to re-engage customers.

Common template use cases include follow-up messages after a support conversation, appointment reminders, and order status updates.

Rate Limits and Pricing

WhatsApp charges per conversation (a 24-hour session), not per message. Pricing varies by country and conversation category:

Rate limits depend on your WhatsApp Business Account tier. New accounts start at Tier 1 (1,000 business-initiated conversations per day) and can scale up to unlimited by building a quality messaging reputation.

Testing with WhatsApp Sandbox

Both Meta and Twilio provide sandbox environments for testing before going to production:

• Meta Test Number: Use the test phone number provided in the Meta developer dashboard to send and receive messages without a verified business.
• Twilio Sandbox: Join the Twilio WhatsApp Sandbox by sending a specific message from your personal WhatsApp to the sandbox number. This allows you to test the full flow without a production number.

We strongly recommend completing full end-to-end testing in a sandbox environment before deploying to production.

Troubleshooting

Production Checklist

Before going live with your WhatsApp integration, verify the following:

• Business verified with Meta
• Production phone number registered and approved
• Webhook server deployed to a reliable, scalable hosting environment
• HTTPS enabled on webhook endpoint
• Error handling and retry logic implemented
• Message deduplication in place
• Session ID management tested with multiple simultaneous conversations
• Chatsby API key stored securely (environment variables, not hardcoded)
• Rate limits understood and within your WhatsApp tier
• Template messages created and approved for re-engagement scenarios
• Monitoring and alerting set up for webhook failures