MxChat WhatsApp Integration

Seamlessly transfer conversations from your website chat to WhatsApp for continued support. This integration uses Twilio to bridge your MxChat conversations with WhatsApp, allowing customers to continue their conversation on their preferred messaging platform while your support team receives notifications.

How It Works

The WhatsApp integration creates a bridge between your website chat and WhatsApp:

1. Customer Request: User clicks “Transfer to WhatsApp” button in chat
2. Conversation Transfer: MxChat sends conversation history to Twilio
3. WhatsApp Notification: You receive a WhatsApp message with conversation context and session ID
4. Agent Response: You reply on WhatsApp, starting message with session ID
5. Message Delivery: Your response appears in customer’s website chat
6. Continued Conversation: Back-and-forth continues seamlessly across platforms

Complete Setup Guide

Step 1: Get Your Twilio Credentials

1. Go to Twilio Console Dashboard
2. Sign up for a free account if you don’t have one (includes trial credits)
3. From the dashboard, locate your Account SID (found at Account Dashboard scroll down)
   • Starts with AC...
   • Found in the “Account Info” section
4. Copy your Auth Token
   • Click “Show” to reveal the token
   • Keep this secure – it’s like a password
5. Keep these credentials handy – you’ll need them in Step 3

Step 2: Create a WhatsApp Sender in Twilio

1. Navigate to WhatsApp Senders in your Twilio console
2. Click “Create new sender”
3. Choose your setup option:

Option A: Display Name Only (Recommended for Most Users)

Best for: Testing, small businesses, quick setup without Meta approval

• What you get: A Twilio-managed shared WhatsApp number
• Setup process:
  1. Select “Display Name Only”
  2. Enter your business display name (e.g., “MxChat Support”)
  3. Twilio assigns you a shared number (e.g., +15551110000)
  4. This number is immediately ready to use
• How it works:
  • Messages sent FROM Twilio’s shared number
  • Notifications received ON your personal WhatsApp
  • Two different numbers in configuration
• Limitations:
  • Shared number (not unique to your business)
  • Can’t use your own business number
  • Messages show Twilio’s number as sender

Option B: WhatsApp Business API (Advanced)

Best for: Established businesses with Meta approval, dedicated business number needed

• What you get: Your own dedicated WhatsApp Business number
• Requirements:
  • WhatsApp Business API approved through Meta
  • Facebook Business Manager account
  • Business verification completed
  • Phone number ownership verified
• Setup process:
  1. Select “Use Your Own Business Number”
  2. Enter your verified business phone number
  3. Complete Meta’s verification process
  4. Wait for approval (can take several days)
• How it works:
  • Messages sent FROM your business number
  • Notifications received ON the same business number
  • Same number used in both configuration fields
• Benefits:
  • Professional appearance (your own number)
  • Brand consistency
  • Higher sending limits
  • Advanced WhatsApp Business features

Configure the Webhook

4. After creating your sender, click “Edit Sender” on your newly created sender
5. Find the “Webhook URL for incoming messages” field
6. Leave this blank for now – you’ll get the URL in Step 3
7. Note the WhatsApp number assigned or configured (you’ll need this in Step 3)

Step 3: Configure MxChat WhatsApp Settings

1. In WordPress admin, go to MxChat → WhatsApp
2. You’ll see the Webhook URL displayed at the top
   • Format: https://yourdomain.com/wp-json/mxchat-whatsapp/v1/webhook
   • Copy this URL
3. Return to Twilio WhatsApp Senders (from Step 2)
4. Edit your sender and paste the webhook URL in “Webhook URL for incoming messages”
5. Ensure method is set to HTTP POST
6. Save the Twilio configuration
7. Now configure MxChat settings based on your setup option:

For Display Name Only Setup

• Twilio Account SID: Paste from Step 1 (e.g., AC1234567890abcdef...)
• Twilio Auth Token: Paste from Step 1
• Twilio WhatsApp Number: The Twilio-assigned shared number
  • Format: +15551110000 (example)
  • Found in Twilio WhatsApp Senders list
  • This is the number messages are sent FROM
• Business WhatsApp Number: YOUR personal WhatsApp number
  • Format: +19101110000 (example – use your number)
  • Include country code
  • This is where YOU receive notifications
  • This is a DIFFERENT number from Twilio’s number

For WhatsApp Business API Setup

• Twilio Account SID: Paste from Step 1 (e.g., AC1234567890abcdef...)
• Twilio Auth Token: Paste from Step 1
• Twilio WhatsApp Number: Your verified business number
  • Format: +19101110000 (example – use your business number)
  • This is your WhatsApp Business API number
  • Messages are sent FROM this number
• Business WhatsApp Number: Your verified business number
  • Format: +19101110000 (example – same as above)
  • Use the SAME number as Twilio WhatsApp Number
  • This is where YOU receive notifications
  • Yes, it’s the same number – this is correct for Business API!

8. Click “Save Changes”

Step 4: Enable WhatsApp Transfer in Actions

1. Go to MxChat → Actions
2. Create a new intent or edit an existing one
3. Select “Transfer to WhatsApp” as the callback
4. Add trigger phrases like:
   • “transfer to whatsapp”
   • “continue on whatsapp”
   • “whatsapp support”
   • “message me on whatsapp”
   • “switch to whatsapp”
5. Save the intent

Step 5: Test the Integration

1. Open your website and start a chat
2. Have a brief conversation (2-3 messages)
3. Trigger the WhatsApp transfer (e.g., type “transfer to whatsapp”)
4. You should see a confirmation message in the chat
5. Check your WhatsApp (the Business WhatsApp Number you configured)
6. You should receive a message with:
   • Conversation history
   • Session ID (format: [SESSION:abc123...])
   • Instructions for replying
7. Reply on WhatsApp, starting with the session ID:

   [SESSION:abc123...] Hello! How can I help you today?

8. Your message should appear in the customer’s chat on the website
9. Continue the conversation – messages flow both ways

Understanding Number Configuration

Scenario 1: Display Name Only Setup

Scenario 2: WhatsApp Business API Setup

Key Features

Conversation Transfer

• Full Context Transfer: Entire conversation history sent to WhatsApp
• Session Tracking: Unique session ID links website chat to WhatsApp
• Automatic Formatting: Conversation formatted clearly with timestamps
• User Information: Customer details included in transfer
• Seamless Handoff: Customer continues chat without interruption

Agent Notifications

• Real-time Alerts: Instant WhatsApp notification when transfer occurs
• Conversation Summary: See full chat history at a glance
• Session ID: Unique identifier for replying to correct customer
• Customer Context: Know who you’re helping and their issue
• Reply Instructions: Clear guidance on how to respond

Two-Way Messaging

• Agent to Customer: Your WhatsApp replies appear in website chat
• Customer to Agent: Customer’s website messages forwarded to your WhatsApp
• Session Management: Multiple conversations tracked separately
• Message Threading: Responses linked to correct conversations
• No App Required: Customers continue on your website, agents use WhatsApp

Session Management

• Unique IDs: Each conversation gets unique session identifier
• Session Format: [SESSION:abc123def456...]
• Required for Replies: Must include session ID at start of each message
• Multi-Customer Support: Handle multiple conversations simultaneously
• Session Timeout: Configurable session expiration

Using WhatsApp Integration

For Support Agents

When Customer Requests Transfer

1. Customer triggers transfer intent in website chat
2. You receive WhatsApp notification with:

   New conversation from John Doe
   Session ID: [SESSION:abc123...]
   
   Conversation History:
   [2024-01-15 10:30] Customer: Hi, I need help with my order
   [2024-01-15 10:31] Bot: I'd be happy to help! What's your order number?
   [2024-01-15 10:32] Customer: It's #12345
   
   Please reply to this message with the session ID to continue the conversation.

3. Read the conversation context
4. Copy the session ID

Replying to Customers

1. Start your WhatsApp message with the session ID
2. Add your response after the ID

   [SESSION:abc123...] Hi John! I can see you're having trouble with order #12345. Let me look that up for you.

3. Send the message
4. Your response appears in customer’s website chat (without the session ID)
5. Continue conversation naturally

Important Rules

• Always include session ID at the start of EVERY message
• Don’t modify the session ID format
• Session ID is automatically stripped from customer view
• Handle one conversation at a time or carefully track session IDs
• If you forget the session ID, ask customer to reinitiate transfer

Handling Multiple Conversations

1. Each transfer has a unique session ID
2. Save session IDs as WhatsApp contacts for quick access:
   • Contact Name: “Customer – John Doe”
   • Note: [SESSION:abc123...]
3. Or copy-paste session IDs from notification messages
4. Use WhatsApp’s search to find specific session
5. Respond to each using their respective session ID

For Customers

The customer experience is seamless:

1. Customer asks to transfer to WhatsApp
2. They see confirmation: “Transferring to WhatsApp support. An agent will respond shortly.”
3. Customer stays on website chat (no app needed)
4. Agent’s WhatsApp replies appear in website chat
5. Customer continues conversation normally
6. No session IDs visible to customer
7. Appears as seamless live chat experience

Complete Workflow Example

Scenario: Customer Needs Order Help

New conversation from Jane Smith
Session ID: [SESSION:xyz789abc]

Conversation History:
[2024-01-15 14:30] Customer: Hi, I haven't received my order yet
[2024-01-15 14:31] Bot: I'm sorry to hear that. I can help you track your order. Do you have your order number?
[2024-01-15 14:32] Customer: Yes, it's #12345
[2024-01-15 14:32] Bot: Let me look that up. Would you like to continue this conversation on WhatsApp with a live agent?
[2024-01-15 14:33] Customer: Yes please

Please reply to this message with the session ID to continue the conversation.

[SESSION:xyz789abc] Hi Jane! I can see you're waiting for order #12345. Let me check the tracking information for you.

Phone Number Formatting

Required Format

• Must include country code: Start with + followed by country code
• No spaces or special characters: Use continuous digits
• Examples:
  • US: +19101110000
  • UK: +447911123456
  • India: +919876543210
  • Brazil: +5511987654321

Common Country Codes

• United States: +1
• United Kingdom: +44
• Canada: +1
• Australia: +61
• India: +91
• Germany: +49
• France: +33
• Brazil: +55
• Mexico: +52
• Spain: +34

Invalid Formats

• ❌ 9101110000 – Missing country code and +
• ❌ +1 910 111 0000 – Contains spaces
• ❌ +1-910-111-0000 – Contains dashes
• ❌ +1 (910) 111-0000 – Contains formatting
• ✅ +19101110000 – Correct format!

Twilio Setup Options Comparison

Which Option to Choose?

Troubleshooting

Best Practices

For Support Teams

• Save Session IDs: Create WhatsApp contacts for active sessions with session ID in notes
• Respond Promptly: Customers expect quick response after requesting WhatsApp transfer
• Read Full History: Review entire conversation context before replying
• Be Consistent: Maintain professional tone matching your brand
• Close Sessions: Let customer know when issue is resolved
• Track Sessions: Keep a log of active sessions if handling multiple customers
• Use Templates: Prepare common responses for efficiency
• Test Regularly: Do weekly test transfers to ensure system working

For Implementation

• Start with Display Name: Test integration with Twilio’s shared number first
• Monitor Twilio Usage: Track message costs in Twilio console
• Set Business Hours: Consider disabling transfers outside support hours
• Train Your Team: Ensure all agents understand session ID requirement
• Document Workflow: Create internal guide for handling WhatsApp conversations
• Test Edge Cases: Try various scenarios (multiple transfers, long conversations, etc.)
• Monitor Logs: Regularly check Twilio and WordPress logs for errors
• Have Backup: Maintain alternative contact method if WhatsApp fails

For Customer Experience

• Set Expectations: Tell customers agent will respond “shortly” not “immediately”
• Keep Chat Open: Inform customers to stay on website chat page
• Auto-Responses: Consider automated acknowledgment when transfer completes
• Clear Instructions: Display help text if customer needs to reinitiate
• Fallback Options: Provide email/phone if WhatsApp transfer fails
• Privacy Notice: Inform customers their conversation will be transferred

Security & Privacy

• Secure Credentials: Never share Twilio Auth Token publicly
• Use HTTPS: Required for webhook security
• Monitor Access: Limit who has access to Twilio console
• Regular Audits: Review conversation logs periodically
• Data Retention: Configure appropriate session timeout
• Comply with Regulations: Follow GDPR, CCPA, etc. for customer data

Twilio Pricing

WhatsApp Conversation Pricing

Twilio charges based on “conversations” (24-hour windows):

• Business-Initiated: You start the conversation (customer requests transfer)
  • Varies by country (typically $0.005-$0.025 per conversation)
  • Conversation window lasts 24 hours from first message
• User-Initiated: Customer messages you first
  • Free for first 1,000 conversations/month
  • Then same rate as business-initiated
• Additional Messages: Within 24-hour window are free

Cost Examples

• 10 transfers/day: ~$3-7.50/month (assuming US rates)
• 50 transfers/day: ~$15-37.50/month
• 100 transfers/day: ~$30-75/month

Twilio Trial Account

• Free trial credits available for testing
• Limited to verified numbers only
• Upgrade for production use
• No monthly fees – pay only for usage

Technical Details

Webhook Endpoint

• URL Format: https://yourdomain.com/wp-json/mxchat-whatsapp/v1/webhook
• Method: HTTP POST
• Authentication: Twilio signature validation
• Response: JSON with status

Session Management

• Session ID Format: [SESSION:64-character-hash]
• Generation: SHA-256 hash of conversation data
• Storage: WordPress transients (configurable timeout)
• Expiration: Default 24 hours, adjustable

Message Flow

1. Customer triggers transfer → MxChat creates session
2. Session stored with conversation history
3. Twilio API called to send WhatsApp notification
4. Agent replies with session ID on WhatsApp
5. Twilio sends reply to webhook endpoint
6. Webhook validates Twilio signature
7. Session ID extracted from message
8. Message routed to correct website chat session
9. Customer sees message in real-time

API Endpoints Used

• Send Message: https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json
• Webhook Callback: Your site’s REST API endpoint

Database Storage

• Sessions: Stored as WordPress transients
• Format: mxchat_whatsapp_session_{session_id}
• Data: JSON with conversation history and metadata

Security

• Twilio Signature Validation: Verifies webhook requests from Twilio
• HTTPS Required: Encrypted communication
• Session Hashing: Prevents session ID guessing
• Nonce Validation: WordPress REST API security

Frequently Asked Questions

Need Help?

If you’re experiencing issues not covered here:

• Visit MxChat.ai for documentation and updates
• Check our YouTube channel for video tutorials
• Review Twilio WhatsApp documentation
• Check Twilio error logs for delivery issues
• Test webhook URL directly in browser
• Contact MxChat support with your Twilio Account SID (NOT Auth Token) and detailed description of the issue

Common Support Information Needed

When requesting support, include:

• Setup option used (Display Name or Business API)
• Twilio Account SID (safe to share)
• Twilio WhatsApp Number (with formatting)
• Business WhatsApp Number (with formatting)
• Error messages from Twilio console
• Webhook URL
• WordPress version and MxChat version
• Steps to reproduce the issue
• Sample session ID (if issue is reply-related)