Skip to main content

WhatsApp Business

Msghub integrates with Meta's WhatsApp Business API to send messages at scale. WhatsApp offers 98% open rates compared to 20% for email, making it the most effective channel for customer communication.

WhatsApp Setup

Prerequisites

  • WhatsApp Business Account (free from Meta)
  • Business phone number (dedicated or shared)
  • Approved message templates

Connect WhatsApp to Msghub

  1. Go to Settings → Channels → WhatsApp
  2. Click Connect Meta Cloud API
  3. You'll be redirected to Meta's login page
  4. Log in with your Facebook/Meta account
  5. Authorize Msghub to access your WhatsApp Business Account
  6. Select your business account and phone number
  7. Click Confirm
  8. Msghub will verify the connection

Once connected, you can start sending WhatsApp messages immediately.

Sending WhatsApp Messages

Template Messages

Template messages are pre-approved by Meta and can be sent anytime (even outside the 24-hour window).

curl -X POST \
  https://your-msghub.com/api/v1/messages/send \
  -H "X-API-Key: mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "to": "+919876543210",
    "templateId": "order_confirmation",
    "parameters": {
      "name": "Rahul",
      "orderId": "ORD-4821",
      "trackingUrl": "https://track.example.com/ORD-4821"
    }
  }'

Free-Form Messages

Free-form messages can only be sent within the 24-hour conversation window (after a customer messages you).

curl -X POST \
  https://your-msghub.com/api/v1/messages/send \
  -H "X-API-Key: mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "to": "+919876543210",
    "body": "Hi Rahul! Thanks for your order. We'll ship it tomorrow.",
    "type": "text"
  }'

Media Messages

Send images, videos, documents, and audio files.

curl -X POST \
  https://your-msghub.com/api/v1/messages/send \
  -H "X-API-Key: mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "to": "+919876543210",
    "type": "image",
    "media": {
      "url": "https://example.com/product.jpg",
      "caption": "Your order has arrived!"
    }
  }'

Supported media types:

  • image — JPG, PNG (max 5MB)
  • video — MP4, 3GPP (max 16MB)
  • document — PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX (max 100MB)
  • audio — MP3, OGG (max 16MB)

Template Management

Create a Template

  1. Go to Settings → Channels → WhatsApp → Templates
  2. Click Create Template
  3. Enter template details:
    • Name — Unique template name (e.g., "order_confirmation")
    • Category — Marketing, Transactional, or OTP
    • Language — Template language
    • Content — Template text with variables
  4. Click Create

Msghub will submit the template to Meta for approval. Approval usually takes 1-24 hours.

Template Variables

Use variables (placeholders) in templates:

Template:

Hi {{1}}, your order {{2}} has shipped. Track it here: {{3}}

Send request:

{
  "channel": "whatsapp",
  "to": "+919876543210",
  "templateId": "order_confirmation",
  "parameters": {
    "1": "Rahul",
    "2": "ORD-4821",
    "3": "https://track.example.com/ORD-4821"
  }
}

Or use named parameters:

{
  "channel": "whatsapp",
  "to": "+919876543210",
  "templateId": "order_confirmation",
  "parameters": {
    "name": "Rahul",
    "orderId": "ORD-4821",
    "trackingUrl": "https://track.example.com/ORD-4821"
  }
}

Template Categories

  • Marketing — Promotional messages (can be sent anytime with opt-in)
  • Transactional — Order confirmations, receipts, alerts (can be sent anytime)
  • OTP — One-time passwords (can be sent anytime)

Choose the right category for faster approval.

Interactive Messages

Send messages with buttons, lists, and quick replies.

Button Messages

curl -X POST \
  https://your-msghub.com/api/v1/messages/send \
  -H "X-API-Key: mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "to": "+919876543210",
    "type": "interactive",
    "interactive": {
      "type": "button",
      "body": {
        "text": "Do you want to confirm your order?"
      },
      "action": {
        "buttons": [
          {
            "type": "reply",
            "reply": {
              "id": "btn_yes",
              "title": "Yes, confirm"
            }
          },
          {
            "type": "reply",
            "reply": {
              "id": "btn_no",
              "title": "No, cancel"
            }
          }
        ]
      }
    }
  }'

List Messages

curl -X POST \
  https://your-msghub.com/api/v1/messages/send \
  -H "X-API-Key: mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "to": "+919876543210",
    "type": "interactive",
    "interactive": {
      "type": "list",
      "body": {
        "text": "Choose a product:"
      },
      "action": {
        "button": "View Products",
        "sections": [
          {
            "title": "Electronics",
            "rows": [
              {
                "id": "prod_1",
                "title": "Laptop",
                "description": "$999"
              },
              {
                "id": "prod_2",
                "title": "Phone",
                "description": "$599"
              }
            ]
          }
        ]
      }
    }
  }'

24-Hour Conversation Window

WhatsApp enforces a 24-hour conversation window: you can only send free-form messages within 24 hours of the customer's last message.

How Msghub Handles It

Msghub automatically:

  1. Checks if the conversation is within the 24-hour window
  2. If yes, sends the message immediately
  3. If no, queues the message and retries with a template when the window closes

This means you can send messages anytime—Msghub handles the window logic.

Example

Scenario: Customer messages you at 10 AM. You have until 10 AM the next day to send free-form messages.

Customer message: 10:00 AM (Day 1)
Your window: 10:00 AM (Day 1) - 10:00 AM (Day 2)

Send free-form message: 3:00 PM (Day 1) ✓ Sent immediately
Send free-form message: 11:00 AM (Day 2) ✗ Outside window
  → Msghub queues and retries with template

Delivery Status

WhatsApp provides detailed delivery status:

{
  "event": "message.delivered",
  "messageId": "msg_abc123",
  "channel": "whatsapp",
  "status": "delivered",
  "deliveredAt": "2024-04-08T10:30:05Z"
}

Possible statuses:

  • sent — Message sent to WhatsApp servers
  • delivered — Message delivered to recipient's phone
  • read — Message read by recipient
  • failed — Message delivery failed

Incoming Messages

When a customer messages you on WhatsApp, Msghub receives the message and can:

  1. Route to your AI chatbot for automatic response
  2. Route to a human agent in the unified inbox
  3. Trigger a flow or webhook

Receiving Messages

Configure a webhook to receive incoming messages:

curl -X POST \
  https://your-msghub.com/api/v1/webhooks \
  -H "X-API-Key: mk_live_..." \
  -d '{
    "event": "message.received",
    "channel": "whatsapp",
    "url": "https://your-app.com/webhooks/whatsapp"
  }'

Msghub will POST incoming messages to your webhook:

{
  "event": "message.received",
  "messageId": "msg_xyz789",
  "channel": "whatsapp",
  "from": "+919876543210",
  "contact": {
    "id": "contact_123",
    "name": "Rahul",
    "phone": "+919876543210"
  },
  "message": {
    "type": "text",
    "text": "Hi, where's my order?"
  },
  "receivedAt": "2024-04-08T10:30:00Z"
}

Bulk WhatsApp Campaigns

Send WhatsApp messages to multiple contacts using campaigns.

Create a Campaign

curl -X POST \
  https://your-msghub.com/api/v1/campaigns \
  -H "X-API-Key: mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Confirmation Campaign",
    "channel": "whatsapp",
    "templateId": "order_confirmation",
    "recipients": {
      "segment": "recent_orders"
    },
    "sendAt": "2024-04-08T18:00:00Z"
  }'

Monitor Campaign

curl -X GET \
  https://your-msghub.com/api/v1/campaigns/camp_xyz789 \
  -H "X-API-Key: mk_live_..."

Best Practices

Template Approval

  • Be specific — Use clear, concise language
  • Include variables — Show how parameters will be used
  • Avoid spam — Don't use ALL CAPS or excessive punctuation
  • Test first — Send to yourself before submitting for approval

Message Content

  • Personalize — Use customer name and order details
  • Be concise — WhatsApp is for quick, direct communication
  • Include CTA — "Click here", "Reply YES", "Call us"
  • Use emojis — Sparingly, for visual appeal

Timing

  • Respect time zones — Schedule for recipient's local time
  • Avoid late night — Don't send after 9 PM
  • Send during business hours — 9 AM - 6 PM for best engagement

Compliance

  • Get consent — Always ask before adding to broadcast lists
  • Respect opt-outs — Honor "STOP" requests immediately
  • Keep records — Log all consent and opt-outs

Troubleshooting

Template not approved

  1. Check content — Is it clear and professional?
  2. Check variables — Are they properly formatted?
  3. Check category — Is it the right category for your message?
  4. Resubmit — Meta may reject and ask for changes

Messages not sending

  1. Check phone number — Must be E.164 format (+919876543210)
  2. Check template — Is it approved?
  3. Check window — Is it within 24 hours of customer's message?
  4. Check connection — Is WhatsApp connected in Settings?

Low delivery rate

  1. Check phone numbers — Are they valid and active?
  2. Check message content — Does it match the template?
  3. Check timing — Are you respecting the 24-hour window?

See Also