WhatsApp Integration

The WhatsApp integration allows your AI assistants to communicate with customers through WhatsApp Business API. Your assistant can send and receive messages, manage conversations, and provide automated support via WhatsApp.

What is WhatsApp Integration?

WhatsApp Business API is a powerful messaging platform that enables businesses to communicate with customers at scale. By integrating WhatsApp with your AI assistant, you can provide automated customer support and engage with customers on their preferred messaging platform.

Key Features

• Two-Way Messaging: Your assistant can send and receive WhatsApp messages in real-time
• Conversation Management: Automatically track and manage customer conversations
• Phone Number Registration: Register WhatsApp phone numbers for business use
• Assistant Attachment: Connect WhatsApp numbers to specific AI assistants
• 24/7 Availability: Provide automated support around the clock
• Conversation Expiry: Conversations automatically expire after 24 hours of inactivity for privacy

How It Works

1. Customer Sends Message: A customer sends a WhatsApp message to your business number
2. Message Received: The platform receives the message through Meta's webhook
3. Assistant Processes: Your AI assistant analyzes the message and generates a response
4. Response Sent: The assistant's response is sent back to the customer via WhatsApp
5. Conversation Tracked: All messages are tracked in a conversation for context
6. Auto-Expiry: Conversations expire after 24 hours of inactivity to maintain privacy

Setting Up WhatsApp Integration

Prerequisites

• Meta Business Account
• WhatsApp Business Account (WABA)
• Phone number verified with Meta
• AI assistant configured in your KI Agency platform
• Meta App ID, App Secret, and access tokens (system-level configuration)

Step-by-Step Setup

1. Connect WhatsApp Business Account

The WhatsApp Business Account (WABA) connection is typically set up at the system level by administrators. This involves:

• Connecting to Meta's platform using OAuth
• Exchanging authorization codes for access tokens
• Storing secure credentials for API access

If you need to connect a new WABA, contact your system administrator.

2. Register and Verify a Phone Number

Once your WABA is connected, you need to register and verify phone numbers for WhatsApp messaging. The verification process depends on whether the phone number is already attached to an assistant:

1. Navigate to WhatsApp Management

   • Go to the integrations section
   • Select WhatsApp integration

2. View Eligible Phone Numbers

   • The system will display phone numbers that can be registered
   • These may include numbers from your existing phone provider or numbers already linked to your WABA

3. Click Verify Button

   • Select the phone number you want to verify
   • Click the "Verify" button next to the phone number

4. Choose Verification Path

   The system will automatically determine which verification path to use:

   Path A: Phone Already Assigned to Assistant

   • If the phone number is already attached to an assistant, Meta will call that assistant's phone number directly
   • Simply wait for the verification call, note the 6-digit PIN, and enter it when prompted
   • This is the simpler path if you've already configured your assistant's phone number

   Path B: Phone Not Assigned (Call Forwarding)

   • If the phone number is not yet attached to an assistant, you'll need to provide a forwarding phone number
   • Enter your personal phone number (in international format, e.g., +1234567890) where you want to receive the verification call
   • The system will temporarily configure call forwarding for the verification process
   • Meta will call the WhatsApp business number, which will be forwarded to your phone
   • After receiving the call and the 6-digit PIN, enter it to complete verification
   • Call forwarding will be automatically removed after verification

5. Enter Verification PIN

   • Listen to the automated verification call
   • Note the 6-digit PIN code you hear
   • Enter the PIN in the verification dialog
   • Click "Verify" to complete the process

6. Verification Complete

   • If successful, the phone number status will update to "verified"
   • The phone number is now ready to be attached to an assistant
   • If you used Path B, the temporary call forwarding has been automatically removed

3. Attach Phone Number to Assistant

After registering a phone number, connect it to an AI assistant:

1. Select Available Number

   • View the list of registered WhatsApp numbers
   • Choose the number you want to use

2. Choose Assistant

   • Select which AI assistant should handle messages from this number
   • Each phone number can be attached to only one assistant at a time

3. Attach Number

   • Click "Attach" to connect the number to the assistant
   • The system will configure webhook routing automatically

4. Verify Connection

   • Send a test message to the WhatsApp number
   • Verify that your assistant responds correctly

Configuration Options

Phone Number Management

Verification: Verify phone numbers with Meta for WhatsApp Business API usage

• Requires receiving a voice call with a 6-digit PIN
• Two verification paths available:
  • Path A: Phone already assigned to assistant (call goes directly to assistant's number)
  • Path B: Phone not assigned (you provide a forwarding number to receive the call)
• Verification must be completed before the phone number is fully operational
• The system automatically handles call forwarding setup and cleanup for Path B

Attachment: Connect registered numbers to specific AI assistants

• Each number can be attached to one assistant at a time
• Detaching a number allows reassignment to a different assistant
• Attached numbers are displayed in the assistant list

Unregistration: Remove phone numbers from WhatsApp Business API

• Detach the number from any assistant first
• Unregister the number through the management interface
• Number can be re-registered later if needed

Conversation Management

Automatic Tracking: All WhatsApp conversations are automatically tracked with:

• Unique conversation ID
• Associated assistant
• Customer WhatsApp ID
• Message history
• Activity timestamps

Conversation Expiry: To protect customer privacy, conversations automatically expire:

• After 24 hours of no activity from the customer
• Expired conversations are marked as "expired" in the system
• New messages from the customer create a fresh conversation

Context Continuity: Within the 24-hour window:

• The assistant maintains conversation context
• Previous messages are available for reference
• Responses are more contextual and relevant

How Customers Experience WhatsApp Messaging

When a customer messages your WhatsApp business number:

1. Initial Message: Customer sends their first message (e.g., "Hello, I need help")
2. Assistant Response: Your AI assistant analyzes the message and responds appropriately
3. Natural Conversation: Customer and assistant exchange messages naturally
4. Context Awareness: Within 24 hours, the assistant remembers previous messages
5. Automatic Handling: No manual intervention needed - the assistant manages the entire conversation
6. Conversation End: After 24 hours of inactivity, the conversation expires for privacy

Example conversation:

Customer: Hello, I'd like to know your business hours
Assistant: Hello! We're open Monday to Friday, 9 AM to 5 PM. How can I help you today?
Customer: Do you offer weekend appointments?
Assistant: Currently, we don't offer weekend appointments, but we can schedule you for any weekday that works best for you. Would you like to book an appointment?

Best Practices

Customer Experience

• Train your assistant with friendly, conversational language
• Keep responses concise and clear for mobile reading
• Use quick reply options when available
• Respond promptly to maintain engagement

Phone Number Management

• Use dedicated business numbers for WhatsApp
• Keep phone number registrations up-to-date
• Monitor registration status regularly
• Document which assistant is attached to each number

Privacy and Compliance

• Respect conversation expiry times
• Don't store sensitive customer information in messages
• Follow WhatsApp Business Policy guidelines
• Comply with local data protection regulations

Message Quality

• Test your assistant responses thoroughly before going live
• Monitor conversation logs for quality assurance
• Update assistant training based on customer feedback
• Handle edge cases and unexpected messages gracefully

Troubleshooting

Common Issues

Phone Number Verification Fails

• Verify the 6-digit PIN is correct (listen carefully to the verification call)
• For Path B (call forwarding), ensure your forwarding phone number is in correct international format (e.g., +1234567890)
• Make sure you can receive phone calls on your forwarding number
• Ensure the phone number is properly configured in Meta Business Manager
• Check that the number isn't already verified with another WABA
• Try the verification process again - the system will clean up any previous attempts
• Contact Meta support if verification repeatedly fails

Messages Not Being Received

• Verify the phone number is properly verified (status shows "verified")
• Check that the number is attached to an active assistant
• Ensure Meta webhooks are configured correctly (system-level)
• Review webhook logs for incoming message data
• Confirm that phone number verification was successful (not just in progress)

Assistant Not Responding

• Verify the assistant is active and properly configured
• Check that the WhatsApp number is correctly attached
• Test the assistant's configuration outside of WhatsApp
• Review conversation logs for error messages

Conversation Context Lost

• Remember that conversations expire after 24 hours
• New messages after expiry create a fresh conversation
• This is expected behavior for privacy protection
• Context is maintained within the 24-hour window

Getting Help

If you encounter issues with WhatsApp integration:

1. Check phone number verification status (should show "verified", not just "registered")
2. Verify assistant attachment is active
3. Review conversation logs for errors
4. Test with a simple message like "Hello"
5. For verification issues, try again - the system will clean up previous attempts
6. Contact your system administrator if problems persist

Related Documentation

• Assistant Configuration - Learn about assistant settings
• Integrations Overview - Explore other available integrations
• Assistant Management - General assistant management guide

---

The WhatsApp integration brings your AI assistants to the world's most popular messaging platform, enabling seamless customer conversations and automated support at scale.