Skip to main content

Overview

WhatsApp automation with Tools transforms your WhatsApp Business account into an intelligent AI-powered assistant. Handle customer support, send notifications, manage groups, and automate conversationsβ€”all through natural language with AI agents.

What You Can Build

Customer Support Bot

24/7 automated support that understands context and provides intelligent responses

Order Notifications

Real-time updates about orders, deliveries, and shipments directly to customers

Group Management

Automate group administration, member management, and announcements

Media Handling

Send and receive images, videos, documents, and voice messages automatically

Architecture

Components:
  • WhatsApp Business: Your WhatsApp account
  • Evolution API: Open-source WhatsApp API bridge
  • Automagik Tools: MCP tool generator with Evolution API integration
  • AI Agents: Claude Code, Cursor, or custom agents that use the tools

Quick Start (5 Minutes)

1

Install Evolution API

# Option 1: Docker (Recommended)
docker run -d \
  --name evolution-api \
  -p 8080:8080 \
  atendai/evolution-api:latest

# Option 2: Manual installation
git clone https://github.com/EvolutionAPI/evolution-api
cd evolution-api
npm install
npm run start:prod
2

Configure Environment

# Create .env file
cat > .env <<EOF
EVOLUTION_API_URL=http://localhost:8080
EVOLUTION_API_KEY=your_evolution_api_key
EOF
Get your API key from Evolution API dashboard at http://localhost:8080/manager
3

Start Tools with Evolution API

# Run Tools with Evolution API integration
uvx automagik-tools serve \
  --tools evolution-api \
  --transport sse \
  --port 3000

# Tools is now ready to manage WhatsApp!
4

Connect WhatsApp

Use your AI agent to connect:
You: "Create a new WhatsApp instance called 'customer-support'"

AI: [Uses evolution_create_instance]
βœ“ Instance created: customer-support

You: "Get QR code to connect WhatsApp"

AI: [Uses evolution_get_qr_code]
[QR Code Image Displayed]

Scan this QR code with WhatsApp to connect.
Scan the QR code with WhatsApp β†’ WhatsApp Web β†’ Linked Devices
5

Start Automating

You: "Send 'Hello!' to +1234567890"

AI: [Uses evolution_send_text_message]
βœ“ Message sent to +1234567890

Your WhatsApp bot is live! πŸŽ‰

Use Case 1: Customer Support Automation

Build a 24/7 customer support bot that handles common queries intelligently.

Setup

1

Create Support Instance

You: "Create WhatsApp instance for customer support"

AI: I'll create a dedicated instance.
[Uses evolution_create_instance with name="customer-support"]
βœ“ Instance created
[Displays QR code for connection]
2

Connect Claude Code

Add to Claude Desktop config:
{
  "mcpServers": {
    "whatsapp-support": {
      "command": "uvx",
      "args": [
        "automagik-tools",
        "serve",
        "--tools",
        "evolution-api"
      ],
      "env": {
        "EVOLUTION_API_URL": "http://localhost:8080",
        "EVOLUTION_API_KEY": "your_api_key",
        "EVOLUTION_INSTANCE": "customer-support"
      }
    }
  }
}
3

Configure Auto-Response

You: "When someone messages us, check their message.
     If it's about order status, get order number and look it up.
     If it's about returns, provide return policy.
     If it's technical support, create a support ticket."

AI: I'll set up intelligent message handling.
[Creates webhook listener that:
  1. Receives incoming messages
  2. Analyzes message intent
  3. Routes to appropriate handler
  4. Sends contextual response
]

Auto-responder active. Monitoring messages...

Real Conversations

  • Order Status Query
  • Return Request
  • Technical Support
Customer: "Hi, what's the status of my order #12345?"

Bot: [Analyzes message β†’ Detects order status query]
     [Extracts order number: 12345]
     [Uses company_api to check order]

Bot: "Hi! Your order #12345 is currently in transit.
     Expected delivery: December 15, 2024
     Tracking: https://track.example.com/12345

     Would you like me to send updates when it arrives?"

Customer: "Yes please"

Bot: "Perfect! I'll notify you as soon as it's delivered. πŸ“¦"
     [Saves notification preference]

Metrics & Improvement

You: "Show me support metrics for this week"

AI: [Analyzes message logs and traces]

πŸ“Š Support Metrics (Dec 8-14, 2024)

Total Conversations: 247
β€’ Resolved Automatically: 189 (76.5%)
β€’ Escalated to Human: 58 (23.5%)

Response Times:
β€’ Average: 3.2 seconds
β€’ Fastest: 0.8 seconds
β€’ Slowest: 12.1 seconds

Top Topics:
1. Order Status: 89 queries (36%)
2. Returns: 45 queries (18%)
3. Product Info: 38 queries (15%)
4. Technical Support: 32 queries (13%)
5. Other: 43 queries (18%)

Customer Satisfaction: 4.7/5.0 ⭐

Use Case 2: Order & Delivery Notifications

Proactively notify customers about their orders in real-time.

Workflow Setup

You: "When an order status changes, automatically send WhatsApp update
     to the customer with tracking info and estimated delivery"

AI: I'll create an order notification workflow.

[Sets up webhook listener for order events]
[Connects to company order API]
[Configures WhatsApp message templates]

βœ“ Order notification workflow active

Notification Examples

  • Order Confirmed
  • Order Shipped
  • Out for Delivery
  • Delivered
[Order API triggers event: order_confirmed]

Bot automatically sends:
"πŸŽ‰ Order Confirmed!

Hi Sarah! Your order has been confirmed.

Order #12456
β€’ Blue Widget x 2 - $49.99
β€’ Red Gadget x 1 - $29.99
β€’ Shipping - $8.99
Total: $88.97

Estimated delivery: Dec 15-17, 2024

Track your order: https://track.example.com/12456"

Interactive Follow-ups

Customer: [Clicks 😊 Great]

Bot: "Thanks for the feedback! We're glad your delivery went smoothly.

     Would you like to:
     β€’ Rate the product (5 stars = 20% off next order!)
     β€’ Track another order
     β€’ Contact support"

Customer: "Rate the product"

Bot: "How would you rate the Blue Widget?"
     [Star rating interface: ⭐⭐⭐⭐⭐]

Customer: [Selects 5 stars]

Bot: "Thank you! πŸŽ‰

     Your 20% discount code: LOYAL20
     Valid until: Dec 31, 2024

     Use it on your next purchase!"

Use Case 3: Group Management & Announcements

Automate group administration and send targeted announcements.

Group Administration

1

Create Managed Group

You: "Create a WhatsApp group called 'Product Updates'
     and add these members: +1234567890, +9876543210"

AI: [Uses evolution_create_group]
βœ“ Group created: Product Updates
[Uses evolution_add_group_members]
βœ“ Members added: 2

Group link: https://chat.whatsapp.com/xyz123abc
2

Set Group Rules

You: "Set group description and only allow admins to send messages"

AI: [Uses evolution_update_group_settings]
βœ“ Group settings updated:
  - Description: "Official product updates and announcements"
  - Send messages: Admins only
  - Edit group info: Admins only
3

Automate Member Management

You: "When someone from sales team joins company Slack,
     automatically add them to this WhatsApp group"

AI: [Creates integration between Slack and WhatsApp]
βœ“ Auto-add workflow active

[Later, when new sales member joins Slack...]
βœ“ Added +15551234567 to "Product Updates" group
βœ“ Sent welcome message

Targeted Announcements

You: "Send announcement to all Premium customers about new feature launch"

AI: I'll segment and send the announcement.

[Queries customer database for Premium tier]
Found 347 Premium customers with WhatsApp numbers

[Personalizes message template]
[Sends via evolution_send_text_message in batches]

Progress: 347/347 sent (100%)
Delivered: 342
Read: 187
Replied: 23

Message sent:
"πŸŽ‰ Exclusive Premium Feature!

Hi {name}! As a valued Premium customer, you now have early access
to our new AI Assistant feature.

What's new:
β€’ Smart search with natural language
β€’ Automated workflows
β€’ Priority support

Try it now: https://app.example.com/ai-assistant

Questions? Reply to this message!"

Use Case 4: Media & Document Handling

Send and process images, documents, audio, and video automatically.

Sending Media

  • Images
  • Documents
  • Audio Messages
  • Videos
You: "Send product catalog image to +1234567890"

AI: [Uses evolution_send_media_message]
βœ“ Image sent: product-catalog-2024.jpg
Caption: "Check out our latest products! πŸ“Έ"

Processing Received Media

Customer: [Sends photo of damaged product]

Bot: [Receives image via webhook]
     [Uses AI vision to analyze damage]

Bot: "I see the package arrived damaged. I'm so sorry about this! πŸ˜”

     I've automatically:
     βœ“ Created replacement order (#12457)
     βœ“ No charge - ships today
     βœ“ Return label sent to your email

     Your replacement will arrive by December 16th.
     No need to return the damaged item.

     Is there anything else I can help with?"

[Meanwhile, bot creates internal ticket with image:]
🚨 Damaged product report
Customer: +1234567890
Order: #12456
Image: [damaged-package.jpg]
Action: Replacement sent

Advanced Features

Feature 1: Multi-Language Support

You: "Detect customer's language and respond accordingly"

AI: I'll enable automatic language detection.

[Customer messages in Spanish:]
Customer: "Hola, ΒΏdΓ³nde estΓ‘ mi pedido?"

Bot: [Detects Spanish language]
     [Queries order in database]
     [Responds in Spanish]

Bot: "Β‘Hola! Tu pedido #12345 estΓ‘ en camino.
     Entrega estimada: 15 de diciembre, 2024
     Seguimiento: https://track.example.com/12345"

Feature 2: Smart Context Tracking

Customer: "Hi, I have a question about my order"
Bot: "I'll help! What's your order number?"

Customer: "12345"
Bot: "Found order #12345! What would you like to know?"

Customer: "When will it arrive?"
Bot: [Uses context: order #12345]
     "Your order will arrive on December 15th.
     It's currently in transit from our warehouse."

Customer: "Can you change the address?"
Bot: [Still remembers: order #12345]
     "Sure! What's the new delivery address?"

[Context maintained throughout conversation]

Feature 3: Rich Interactive Messages

You: "Send interactive product catalog with buttons"

AI: [Uses evolution_send_interactive_message]

Bot sends:
"πŸ›οΈ Product Catalog

Choose a category:"

[Button 1: Electronics]
[Button 2: Clothing]
[Button 3: Home & Garden]
[Button 4: Sports]

Customer: [Clicks Electronics]

Bot: "Electronics
Select a product:"

[Button 1: Smartphones πŸ“±]
[Button 2: Laptops πŸ’»]
[Button 3: Headphones 🎧]
[Button 4: Back to Categories ⬅️]

Feature 4: Scheduled Messages

You: "Every Monday at 9 AM, send weekly deals to all subscribed customers"

AI: I'll set up scheduled messaging.

[Creates cron job]
βœ“ Schedule created: Weekly deals
  Frequency: Mondays, 9:00 AM
  Recipients: Subscribed customers (1,234)
  Template: Weekly deals announcement

[Every Monday at 9 AM:]
Bot sends to 1,234 customers:
"πŸŽ‰ This Week's Deals!

Hi {name}! Check out this week's hot deals:

πŸ“± Smartphone X - 30% off ($699 β†’ $489)
πŸ’» Laptop Pro - 25% off ($1,299 β†’ $974)
🎧 Wireless Buds - 40% off ($149 β†’ $89)

Shop now: https://deals.example.com/weekly
Expires: Sunday 11:59 PM

Reply STOP to unsubscribe"

Integration Patterns

Pattern 1: WhatsApp + E-commerce

You: "Integrate WhatsApp with Shopify for complete order lifecycle"

AI: I'll set up end-to-end e-commerce integration.

Workflow created:
1. Order placed β†’ Confirmation message
2. Order shipped β†’ Tracking link
3. Out for delivery β†’ Live updates
4. Delivered β†’ Request review
5. Review submitted β†’ Loyalty points
6. Abandoned cart β†’ Reminder (24h later)

βœ“ Integration active for 1,247 customers

Pattern 2: WhatsApp + CRM

You: "When customer messages us, automatically:
     1. Check if they exist in CRM
     2. If new, create CRM contact
     3. Log conversation in CRM
     4. Tag based on message intent"

AI: I'll integrate WhatsApp with your CRM.

[Customer messages for first time]
βœ“ New contact created in CRM
  Name: Sarah Johnson
  Phone: +1234567890
  Source: WhatsApp
  Tags: First-time, Product inquiry

[Conversation automatically logged]
βœ“ CRM activity created
  Type: WhatsApp conversation
  Subject: Product availability question
  Duration: 5 minutes
  Status: Resolved

Pattern 3: WhatsApp + Support Ticketing

You: "Create support ticket in Linear when customer issue can't be
     resolved automatically, include full conversation history"

AI: I'll connect WhatsApp to Linear ticketing.

[Complex customer issue detected]
Bot: "I'll escalate this to our support team for detailed assistance.
     Ticket #SUP-8901 created. Expected response: within 2 hours."

[In Linear:]
βœ“ Issue created: #SUP-8901
  Title: "Payment processing error"
  Priority: High
  Labels: WhatsApp, Payment, Urgent
  Description: [Full conversation history]
  Assigned to: Support team
  Customer contact: +1234567890

Configuration Best Practices

# Separate instances for different purposes
# customer-support: Customer interactions
# notifications: Automated alerts
# marketing: Promotional messages
# internal: Team communication

You: "Create instance for customer support"
AI: [Creates customer-support instance]

You: "Create instance for notifications"
AI: [Creates notifications instance]
Benefits:
  • Better organization
  • Separate rate limits
  • Isolated metrics
  • Easier troubleshooting
# Create reusable message templates
You: "Create message template for order confirmation"

AI: Template created: order_confirmation

"πŸŽ‰ Order Confirmed!

Hi {customer_name}! Your order has been confirmed.

Order #{order_id}
{order_items}
Total: {order_total}

Estimated delivery: {delivery_date}
Track: {tracking_url}"

# Use template
You: "Send order confirmation to customer using template"
AI: [Fills template with order data]
    [Sends via WhatsApp]
# Respect WhatsApp rate limits
# - Max 1,000 messages per day (business account)
# - Max 20 messages per second

You: "Send announcement to 5,000 customers"

AI: Note: This exceeds daily limit (1,000/day)

Options:
1. Spread over 5 days (1,000/day)
2. Upgrade to WhatsApp Business API
3. Send to priority customers only

Which would you prefer?
# Set up webhooks for real-time events
You: "Configure webhook for incoming messages"

AI: [Uses evolution_set_webhook]
βœ“ Webhook configured
  URL: https://your-server.com/webhook
  Events: message.received, message.read, status.update

# Test webhook
You: "Test webhook connection"
AI: [Sends test event]
βœ“ Webhook responding correctly (200 OK)
# Graceful error handling
You: "If message fails to send, retry 3 times with exponential backoff,
     then log error and notify me"

AI: Error handling configured:
βœ“ Retry attempts: 3
βœ“ Backoff: Exponential (1s, 2s, 4s)
βœ“ Failure notification: Enabled
βœ“ Error logging: Enabled

[Message send failure]
πŸ”„ Retry 1/3... Failed (network error)
πŸ”„ Retry 2/3... Failed (network error)
πŸ”„ Retry 3/3... Success βœ“

Metrics & Analytics

Real-Time Dashboard

You: "Show WhatsApp metrics dashboard"

AI: πŸ“Š WhatsApp Metrics (Last 24 hours)

Messages:
β€’ Sent: 1,247
β€’ Delivered: 1,198 (96.1%)
β€’ Read: 891 (71.4%)
β€’ Replied: 234 (18.8%)

Performance:
β€’ Average response time: 3.2s
β€’ Automation rate: 76.5%
β€’ Customer satisfaction: 4.7/5.0

Top Topics:
1. Order status (342 queries)
2. Product info (198 queries)
3. Returns (145 queries)
4. Technical support (89 queries)
5. Other (473 queries)

Active Conversations: 23
Queue: 2 waiting
Agents online: 5

Conversation Analytics

You: "Analyze customer conversations to find common pain points"

AI: [Analyzes 10,000 recent conversations]

πŸ“ˆ Conversation Insights:

Common Pain Points:
1. Shipping delays (234 mentions)
   β†’ Action: Improve communication about delays

2. Return process confusion (189 mentions)
   β†’ Action: Simplify return instructions

3. Product availability (156 mentions)
   β†’ Action: Add real-time stock checker

4. Payment issues (98 mentions)
   β†’ Action: Add payment troubleshooting guide

Positive Feedback:
1. Fast response time (412 mentions) ⭐
2. Helpful support (378 mentions) ⭐
3. Easy ordering (267 mentions) ⭐

Recommendations:
β€’ Create FAQ bot for top 3 pain points
β€’ Proactive delay notifications
β€’ Add stock availability to product pages

Troubleshooting

Problem: QR code won’t scan or connection failsSolutions:
# Regenerate QR code
You: "Generate new QR code"
AI: [Uses evolution_restart_instance]
    [Gets fresh QR code]

# Check instance status
You: "Check instance status"
AI: Instance: customer-support
    Status: disconnected
    Reason: QR code expired (15 minutes)

# Ensure WhatsApp is updated
- Update WhatsApp to latest version
- Try different phone/device
- Check internet connection
Problem: Messages fail to sendSolutions:
# Check instance connection
You: "Check if WhatsApp is connected"
AI: Instance: customer-support
    Status: connected βœ“
    Last seen: 2 seconds ago

# Verify phone number format
# βœ“ Correct: +1234567890
# βœ— Wrong: 1234567890, (123) 456-7890

# Check rate limits
You: "Check message quota"
AI: Messages today: 847/1,000
    Quota remaining: 153
    Resets in: 3 hours
Problem: Events not triggeringSolutions:
# Verify webhook URL is accessible
curl https://your-server.com/webhook

# Check webhook configuration
You: "Show webhook settings"
AI: Webhook URL: https://your-server.com/webhook
    Status: Active
    Last event: 5 minutes ago βœ“
    Failed deliveries: 0

# Test webhook manually
You: "Send test webhook event"
AI: [Sends test message]
    βœ“ Webhook received event (200 OK)

Cost Comparison

Traditional Development vs. Tools

ApproachSetup TimeDevelopment TimeMaintenanceTotal Cost
Custom Development1-2 days2-4 weeksHigh10,000βˆ’10,000-20,000
Third-party Service1-2 hours1-2 weeksMedium500βˆ’500-1,000/month
Tools + Evolution API5 minutes0 (AI-driven)Low0βˆ’0-50/month
Savings with Tools: 95%+ in time and cost

Next Steps


Remember: WhatsApp automation isn’t about replacing human connectionβ€”it’s about making human connection scale. Handle routine queries automatically so your team can focus on complex, high-value customer interactions. πŸ’¬