WhatsApp Business Cloud API¶

Overview¶

The WhatsApp Business task integrates BaseCloud CRM with Meta's official WhatsApp Business Cloud API, enabling enterprise-grade WhatsApp messaging with OAuth 2.0 authentication, multi-organization support, and advanced template management.

Key Features:

• 7 Actions: Send templates/text/media, create/manage templates, track message status, mark as read
• OAuth 2.0 Authentication: Secure Facebook integration with automatic token refresh
• Multi-WABA Support: Manage multiple WhatsApp Business Accounts (owned + client accounts)
• Template Management: Create, retrieve, and send WhatsApp-approved templates
• Message Status Tracking: Monitor delivery, read status, and failures
• Quality Ratings: Phone number quality monitoring (GREEN/YELLOW/RED)
• Official Meta API: Direct integration with Facebook Graph API v18.0

Use Cases:

• Multi-organization WhatsApp management
• Template-based marketing campaigns
• Order confirmations with media/QR codes
• Customer support with status tracking
• E-commerce order updates
• Appointment reminders

Prerequisites¶

1. Facebook Developer Account¶

Create App:

1. Go to https://developers.facebook.com
2. My Apps → Create App
3. Select Business type
4. Fill in app details and create

2. WhatsApp Business Account (WABA)¶

Setup WABA:

1. In Facebook App Dashboard, add WhatsApp product
2. Complete Business Verification (required for production)
3. Select or create WhatsApp Business Account
4. Add phone number to WABA
5. Complete phone number verification

Account Types:

• Owned WABA: Your organization's account
• Client WABA: Customer accounts (via System User access)

3. OAuth Configuration in BaseCloud¶

Create App Connection:

1. Navigate to BaseCloud CRM → Settings → App Connections
2. Click + New App Connection
3. Select WhatsApp Business from dropdown
4. Click Authorize with Facebook
5. Authorize permissions:
6. whatsapp_business_management - Manage WABA settings
7. whatsapp_business_messaging - Send messages
8. Select Business Account
9. Save connection

OAuth Scopes Required:

whatsapp_business_management
whatsapp_business_messaging

4. Phone Number Configuration¶

Get Phone Number ID:

1. In automation task, select app connection
2. Reload Business Accounts dropdown (🔄 button)
3. Select your WhatsApp Business Account
4. Reload Phone Numbers dropdown (🔄 button)
5. Select phone number (shows quality rating)
6. Phone Number ID automatically populated

Quality Ratings:

• 🟢 GREEN: High quality, highest message limits
• 🟡 YELLOW: Medium quality, reduced limits
• 🔴 RED: Low quality, severe restrictions

Maintain quality by:

• Avoiding spam reports
• Maintaining high engagement rates
• Following WhatsApp policies

5. Message Templates¶

Create Templates:

Use WhatsApp Manager or create_template action:

1. Define template name (lowercase, underscores)
2. Select category (MARKETING, UTILITY, AUTHENTICATION)
3. Design template components:
4. HEADER: Text or media (optional)
5. BODY: Main message with {{1}} placeholders (required)
6. FOOTER: Small text (optional)
7. BUTTONS: Quick replies, URLs, phone numbers (optional)
8. Submit for approval (24-48 hours)

Template Example:

Name: order_confirmation
Category: UTILITY

HEADER: Your order is confirmed! 🎉

BODY: Hi {{1}}, your order #{{2}} has been confirmed.
Total: {{3}}
Estimated delivery: {{4}}

FOOTER: Thank you for your business

BUTTONS:
- Track Order (URL: https://example.com/track/{{1}})

Outputs¶

Session fields describe the 24-hour customer-service window: outside it, only template messages can be sent.

Reference fields as {{task_<ID>_<field>}}.

Always emitted¶

Connections are made in Settings → WhatsApp Business, not on the task — the selector here only picks from what is already connected, and the template list stays empty until one is chosen.

Configuration¶

Builder fields¶

The Field column is the label as it appears in the task builder; Key is the name the value is stored under and referenced by.

Action 1: send_template¶

Send pre-approved WhatsApp template (works anytime, no 24-hour window).

Output Variables:

task_58001_run; // true/false
task_58001_run_text; // "Template sent successfully."
task_58001_action; // "send_template"
task_58001_message_id; // WhatsApp message ID (wamid.xxx)
task_58001_recipient; // Recipient number
task_58001_template_name; // Template used

How It Works:

1. Validates OAuth connection and permissions
2. Builds template payload with parameters
3. Sends via: POST https://graph.facebook.com/v18.0/{phone_number_id}/messages
4. Request body:

   {
     "messaging_product": "whatsapp",
     "to": "27821234567",
     "type": "template",
     "template": {
       "name": "order_confirmation",
       "language": { "code": "en_US" },
       "components": [
         {
           "type": "body",
           "parameters": [
             { "type": "text", "text": "John" },
             { "type": "text", "text": "12345" },
             { "type": "text", "text": "R500" },
             { "type": "text", "text": "Dec 25" }
           ]
         }
       ]
     }
   }
   

5. Returns wamid message ID for tracking

Template Parameters:

Parameters replace placeholders in order:

• {{1}} = first parameter value
• {{2}} = second parameter value
• etc.

Provide as JSON array: ["value1", "value2", "value3"]

Or build dynamically:

['{{client_first_name}}', '{{order_id}}', '{{order_total}}', '{{delivery_date}}'];

Action 2: create_template¶

Create new WhatsApp message template (requires Meta approval 24-48 hours).

Template Components JSON:

[
  {
    "type": "HEADER",
    "format": "TEXT",
    "text": "Welcome to Our Service!"
  },
  {
    "type": "BODY",
    "text": "Hi {{1}}, thank you for signing up! Your account ID is {{2}}. Start exploring today.",
    "example": {
      "body_text": [["John", "ACC12345"]]
    }
  },
  {
    "type": "FOOTER",
    "text": "Reply STOP to unsubscribe"
  },
  {
    "type": "BUTTONS",
    "buttons": [
      {
        "type": "QUICK_REPLY",
        "text": "Get Started"
      },
      {
        "type": "URL",
        "text": "Visit Website",
        "url": "https://example.com/{{1}}"
      }
    ]
  }
]

Output Variables:

task_58001_run; // true/false
task_58001_run_text; // "Template created successfully."
task_58001_action; // "create_template"
task_58001_template_id; // Meta template ID
task_58001_template_name; // Template name
task_58001_status; // "PENDING" (awaiting approval)

How It Works:

1. Validates template name format (lowercase, underscores only)
2. Builds template structure with components
3. Submits via: POST https://graph.facebook.com/v18.0/{waba_id}/message_templates
4. Request body:

   {
     "name": "new_customer_welcome",
     "category": "MARKETING",
     "language": "en_US",
     "components": [
       /* components array */
     ]
   }
   

5. Meta reviews template (24-48 hours)
6. Returns template ID with PENDING status
7. Check status with get_templates action

Template Categories:

• MARKETING: Promotional, offers, announcements (subject to 24-hour window limits)
• UTILITY: Account updates, order confirmations, support (better delivery rates)
• AUTHENTICATION: One-time passwords, verification codes (special handling)

Component Types:

• HEADER: Optional, supports TEXT or MEDIA (IMAGE, VIDEO, DOCUMENT)
• BODY: Required, main message text with {{1}}, {{2}} placeholders
• FOOTER: Optional, small disclaimer text (no placeholders)
• BUTTONS: Optional, up to 3 buttons (QUICK_REPLY, URL, PHONE_NUMBER)

Action 3: get_templates¶

Retrieve all message templates for a WABA.

Output Variables:

task_58001_run; // true/false
task_58001_run_text; // "Successfully retrieved templates."
task_58001_action; // "get_templates"
task_58001_templates; // Array of template objects
task_58001_count; // Number of templates returned

Template Object Structure:

{
  "name": "order_confirmation",
  "status": "APPROVED",
  "category": "UTILITY",
  "language": "en_US",
  "id": "1234567890",
  "components": [/* components array */]
}

How It Works:

1. Calls: GET https://graph.facebook.com/v18.0/{waba_id}/message_templates
2. Query params: ?fields=name,status,category,language,components&limit=100
3. Optionally filters by status
4. Returns array of templates
5. Use in If Conditions to check template availability

Status Values:

• APPROVED: Ready to use in send_template
• PENDING: Awaiting Meta review (24-48 hours)
• REJECTED: Not approved (check rejection reason)
• DISABLED: Previously approved but now disabled

Action 4: send_text¶

Send plain text message within 24-hour conversational window.

Output Variables:

task_58001_run; // true/false
task_58001_run_text; // "Text message sent successfully."
task_58001_action; // "send_text"
task_58001_message_id; // wamid.xxx
task_58001_recipient; // Recipient number

How It Works:

1. Validates 24-hour conversation window exists
2. Sends via: POST https://graph.facebook.com/v18.0/{phone_number_id}/messages
3. Request body:

   {
     "messaging_product": "whatsapp",
     "to": "27821234567",
     "type": "text",
     "text": {
       "preview_url": true,
       "body": "Thank you for contacting us!"
     }
   }
   

4. Returns message ID

24-Hour Window:

• Session starts when customer messages your business
• Window lasts 24 hours from last customer message
• Outside window, use send_template instead
• Meta returns error if window expired

Link Preview:

Set preview_url: true to show preview for URLs in message:

Check out our product: https://example.com/product

Shows rich preview with image, title, description.

Action 5: send_media¶

Send media file (image, video, document, audio).

Either media_url OR media_id required

Output Variables:

task_58001_run; // true/false
task_58001_run_text; // "Media sent successfully."
task_58001_action; // "send_media"
task_58001_message_id; // wamid.xxx
task_58001_recipient; // Recipient number
task_58001_media_type; // Media type sent

How It Works:

1. Validates media type and required fields
2. If media_url provided:
3. Meta downloads from URL
4. URL must be publicly accessible
5. HTTPS preferred
6. If media_id provided:
7. Uses pre-uploaded media
8. Upload via WhatsApp Media API first
9. Sends via: POST https://graph.facebook.com/v18.0/{phone_number_id}/messages
10. Request body (URL example):

    {
      "messaging_product": "whatsapp",
      "to": "27821234567",
      "type": "document",
      "document": {
        "link": "https://example.com/invoice.pdf",
        "caption": "Your invoice for December",
        "filename": "invoice_dec2024.pdf"
      }
    }
    

Media Types:

Media URL Requirements:

• Public URL (no authentication required)
• HTTPS strongly recommended
• Valid content-type header
• File size within limits
• Hosted on reliable server

Action 6: get_message_status¶

Check delivery/read status of sent message.

Output Variables:

task_58001_run; // true/false
task_58001_run_text; // "Message status retrieved."
task_58001_action; // "get_message_status"
task_58001_data; // Full status object
task_58001_data.status; // "sent", "delivered", "read", "failed"
task_58001_data.timestamp; // Unix timestamp
task_58001_data.errors; // Error details if failed

How It Works:

1. Queries: GET https://graph.facebook.com/v18.0/{message_id}
2. Returns status and timestamp
3. Use to verify delivery or troubleshoot failures

Status Values:

• sent: Message sent from Meta server
• delivered: Message delivered to recipient device
• read: Recipient opened message (if read receipts enabled)
• failed: Delivery failed (check errors)

Use Case:

// Send message
Task 1: WhatsApp Business - Send Template
  Output: {{task_58001_message_id}}

// Wait for delivery
Task 2: Delay 5 seconds

// Check status
Task 3: WhatsApp Business - Get Message Status
  message_id: {{task_58001_message_id}}

// Conditional action
Task 4: If Condition
  Condition: {{task_58001_data.status}} equals "delivered"
  Then: Mark order as notified
  Else: Retry send or alert admin

Action 7: mark_as_read¶

Mark incoming message as read (sends read receipt).

Output Variables:

task_58001_run; // true/false
task_58001_run_text; // "Message marked as read."
task_58001_action; // "mark_as_read"
task_58001_success; // true/false

How It Works:

1. Sends read receipt via: POST https://graph.facebook.com/v18.0/{phone_number_id}/messages
2. Request body:

   {
     "messaging_product": "whatsapp",
     "status": "read",
     "message_id": "wamid.xxx"
   }
   

3. Customer sees double blue checkmarks
4. Indicates message received and processed

Use Case:

// Incoming message webhook
Trigger: Webhook In
  Receives: {{task_46001_message_id}}, {{task_46001_sender}}, {{task_46001_message_text}}

// Process message
Task 1: Workflow Note - log the message against the client
  Insert message into database

// Send read receipt
Task 2: WhatsApp Business - Mark As Read
  message_id: {{task_46001_message_id}}

// Auto-reply
Task 3: WhatsApp Business - Send Text
  recipient: {{task_46001_sender}}
  message_text: Thank you! We received your message.

Real-World Examples¶

Reply automatically to an inbound message¶

WhatsApp Message Received
  └─ Chat Thread          read the conversation so far
      └─ AI Prompt        draft a reply, memory key {{task_61001_session_id}}
          └─ WhatsApp Business   send it

Send a template outside the messaging window¶

Schedule
  └─ Match to Client            look the client up
      └─ WhatsApp Business      send an approved template

session_open tells you whether the 24-hour window is still open. Outside it, only templates can be sent.

Confirm an order over WhatsApp¶

Webhook In
  └─ Phone Formatter          normalise the number
      └─ WhatsApp Business    send the confirmation

Troubleshooting¶

Error: "No app connection selected"¶

Cause: OAuth connection not configured

Solutions:

1. Go to Settings → App Connections
2. Create WhatsApp Business connection
3. Complete OAuth authorization
4. Select connection in task dropdown

Error: "Invalid or expired access token"¶

Cause: OAuth token expired (30-minute lifetime)

Solutions:

1. BaseCloud automatically refreshes tokens
2. If error persists, re-authorize connection:
3. Settings → App Connections
4. Edit WhatsApp connection
5. Click Re-authorize
6. Check OAuth scopes are correct:
7. whatsapp_business_management
8. whatsapp_business_messaging

Error: "Phone number ID not found" (404)¶

Cause: Phone number doesn't exist or no access permission

Solutions:

1. Verify phone number is registered in your WABA
2. Check Facebook Business Manager permissions
3. Use correct phone number ID (not phone number itself)
4. Reload phone numbers in task dropdown (🔄 button)
5. Verify OAuth connection has access to correct WABA

Detailed Troubleshooting:

If phone registered but error persists:

• Token may not have whatsapp_business_management scope
• Phone may be in different WABA than selected
• Business verification may be incomplete
• Check WhatsApp Manager: https://business.facebook.com/wa/manage/

Error: "Insufficient permissions" (403)¶

Cause: Missing OAuth scopes or Business Manager role

Solutions:

1. Verify OAuth scopes:
2. whatsapp_business_management - Required
3. whatsapp_business_messaging - Required
4. Check Business Manager role (Admin or Editor)
5. Re-authorize app connection with all scopes
6. Verify business account verification status

Template Not Found¶

Cause: Template name doesn't exist or not approved

Solutions:

1. Use get_templates action to list available templates
2. Check template status is "APPROVED"
3. Verify exact template name (case-sensitive, lowercase, underscores)
4. Wait 24-48 hours if recently submitted

Template Parameter Mismatch¶

Cause: Wrong number of parameters or incorrect order

Solutions:

1. Check template definition in WhatsApp Manager
2. Count placeholders: {{1}}, {{2}}, {{3}}
3. Provide parameters in JSON array matching order:

   ["value for {{1}}", "value for {{2}}", "value for {{3}}"]
   

4. Verify parameter types match template (all strings)

Session Message Failed (24-Hour Window)¶

Cause: No active conversation window for text/media send

Solutions:

1. Use send_template action instead (works anytime)
2. Customer must message your business first to open window
3. Window lasts 24 hours from last customer message
4. Check message timestamp to confirm window active

Media Upload Failed¶

Cause: Media URL inaccessible, wrong format, or too large

Solutions:

1. Verify URL is publicly accessible (test in browser)
2. Use HTTPS URLs (HTTP may fail)
3. Check file size within limits:
4. Images: 5 MB
5. Videos: 16 MB
6. Documents: 100 MB
7. Audio: 16 MB
8. Verify correct MIME type/file extension
9. Alternative: Upload to WhatsApp first, use media_id

Message Status Returns "failed"¶

Cause: Various delivery issues

Solutions:

1. Use get_message_status to get error details
2. Common failures:
3. Invalid recipient number
4. Recipient blocked your number
5. Recipient phone offline extended period
6. Message content policy violation
7. Check {{task_58001_data.errors}} for specific error code
8. Retry with template if text/media failed

Quality Rating is YELLOW or RED¶

Cause: High spam reports, low engagement, policy violations

Solutions:

1. Immediate Actions:
2. Reduce sending volume
3. Only message engaged customers
4. Verify opt-in compliance

5. Remove inactive recipients

6. Long-term Improvements:

7. Use utility templates instead of marketing
8. Increase engagement (ask questions, provide value)
9. Honor opt-outs immediately

10. Follow WhatsApp Commerce Policy

11. Prevention:

12. Monitor quality rating daily (see Example 5)
13. Maintain high response rates
14. Avoid spam trigger words
15. Segment audiences carefully

Business Account Discovery Failed¶

Cause: No Business Manager access or permissions issue

Solutions:

1. Verify Facebook Business Manager account exists
2. Check you're Admin or Editor on Business Account
3. Complete business verification (required for production)
4. Re-authorize app connection
5. Check Business Manager at: https://business.facebook.com/settings/whatsapp-business-accounts

Rate Limiting / 429 Errors¶

Cause: Exceeded messaging rate limits

Solutions:

1. Tier Limits (vary by quality rating and verification):
2. Tier 1: 1,000 messages/24 hours
3. Tier 2: 10,000 messages/24 hours
4. Tier 3: 100,000 messages/24 hours

5. Tier 4 (Unlimited): Request from Meta

6. Immediate Actions:

7. Add delays in bulk send loops (3-5 seconds)
8. Spread campaigns over multiple days

9. Implement exponential backoff on errors

10. Long-term:

11. Request tier upgrade: https://business.facebook.com/wa/manage/
12. Maintain GREEN quality rating for highest limits
13. Use multiple phone numbers for high volume

Best Practices¶

OAuth Management¶

1. Connection Setup:
2. Create separate app connections for dev/staging/production
3. Use descriptive connection names: "WhatsApp - Main Account", "WhatsApp - Client ABC"

4. Document which connection uses which WABA

5. Token Refresh:

6. BaseCloud handles automatic refresh (30-min access, 90-day refresh)
7. Monitor for refresh failures (check connection status)

8. Re-authorize connection if issues persist

9. Multi-WABA:

10. Use one app connection per WABA
11. Store connection ID in client records for dynamic selection
12. Test each connection after setup

Template Strategy¶

1. Design Templates:
2. Use UTILITY category for transactional messages (better delivery)
3. Use MARKETING for promotional content (subject to limits)
4. Keep body text concise (< 1024 characters)

5. Add footer with opt-out instructions

6. Approval Process:

7. Submit templates in batches
8. Allow 48 hours for approval
9. Keep rejection reasons for learning

10. Create template library for reuse

11. Parameter Management:

12. Use meaningful parameter names in docs
13. Validate parameter values before sending
14. Provide example values in template submission
15. Test templates with edge cases (long names, special chars)

Message Delivery¶

1. Session vs Template:
2. Use templates for initial outreach (no 24-hour window needed)
3. Use text/media for ongoing conversations (cheaper)
4. Track conversation status to choose appropriately

5. Template fallback if session expired

6. Status Tracking:

7. Use get_message_status for critical messages
8. Log message IDs for troubleshooting
9. Implement retry logic for failed sends

10. Alert admins on persistent failures

11. Quality Maintenance:

12. Monitor quality rating weekly (Example 5)
13. Only message engaged customers
14. Verify opt-in status before sends
15. Quick response to customer messages

Performance Optimization¶

1. Rate Limiting:
2. Add 3-5 second delays in bulk send loops
3. Batch campaigns (100 messages, delay, next 100)
4. Spread large campaigns over hours/days

5. Monitor tier limits

6. Caching:

7. Cache template list (reload hourly, not per automation)
8. Cache business account/phone number lists

9. Store frequently-used values in variables

10. Error Handling:

11. Wrap critical sends in If Conditions (validate data)
12. Implement exponential backoff for retries
13. Log failures for analysis
14. Provide fallback channels (email, SMS)

Compliance¶

1. Opt-In Management:
2. Maintain whatsapp_opt_in field in CRM
3. Verify opt-in before every send
4. Provide clear opt-out mechanism

5. Honor opt-outs within 24 hours

6. Content Policies:

7. Follow WhatsApp Commerce Policy
8. Avoid: Adult content, gambling, misleading claims
9. Required for financial: Clear pricing, terms

10. Healthcare: Follow additional regulations

11. Data Privacy:

12. Don't share customer data between WABAs
13. Encrypt sensitive data in parameters
14. Follow GDPR/POPIA requirements
15. Provide data access/deletion mechanisms

FAQ¶

Q: What's the difference between WhatsApp Business and WATI?

A:

• WhatsApp Business: Official Meta API, OAuth 2.0, multi-WABA support, template management, status tracking
• WATI: Third-party platform, simple Bearer token, media retrieval, contact sync
• Choose WhatsApp Business for: Enterprise, multi-tenant, official Meta integration
• Choose WATI for: Simpler setup, media handling, existing WATI subscription

Q: Can I use both simultaneously on the same phone number?

A: No, a WhatsApp number can only connect to one platform at a time. Choose one platform per number.

Q: How long does OAuth token last?

A: Access token: 30 minutes (auto-refreshed). Refresh token: 90 days. BaseCloud handles refresh automatically.

Q: What happens if business verification fails?

A: Limited to 250 messages/24 hours. Complete verification for higher limits and production use.

Q: Can I send messages outside 24-hour window?

A: Yes, using approved templates (send_template action). Templates work anytime.

Q: How do I increase messaging limits?

A:

1. Maintain GREEN quality rating
2. Complete business verification
3. Request tier upgrade in WhatsApp Manager
4. Meta reviews and approves based on usage patterns

Q: Can I manage multiple client WABAs?

A: Yes! Create one app connection per WABA. Use connection selector in tasks.

Q: How do I track message delivery?

A: Use get_message_status action with message ID (wamid) from send response.

Q: What's the cost per message?

A: Meta charges per conversation (24-hour window):

• User-initiated: Free (first 1,000/month per number)
• Business-initiated (templates): Varies by country (~$0.03-$0.05 USD)
• Check current rates: https://developers.facebook.com/docs/whatsapp/pricing

Q: Can I send bulk messages?

A: Yes, use Loop task with delays. Respect rate limits based on your tier and quality rating.

Q: How do I create templates programmatically?

A: Use create_template action with JSON components structure (see Action 2).

Q: What if template is rejected?

A: Check rejection reason in WhatsApp Manager. Common issues:

• Policy violations (spam, misleading content)
• Formatting errors
• Missing required elements
• Revise and resubmit

Q: Can I send interactive buttons?

A: Yes, in templates. Use BUTTONS component with QUICK_REPLY, URL, or PHONE_NUMBER types.

Q: How do I handle incoming messages?

A: Configure webhook in Meta App Dashboard. Use Webhook In trigger to receive messages. Use mark_as_read and send_text to respond.

Related Tasks¶

• WATI - Alternative WhatsApp platform integration
• Email - Fallback communication channel
• SMS - Alternative text messaging
• If Statement - Message routing logic
• Loop - Bulk message sending
• Delay - Rate limiting in campaigns
• Webhook In - Receive WhatsApp webhooks
• Match to Client - Match phone numbers to clients

Technical Details¶

• Type ID: 58
• Function: taskWhatsAppBusiness() in automationService.js (lines 10128-10208)
• Service: whatsappService.js (552 lines, 10+ functions)
• API Version: Meta Graph API v18.0
• Authentication: OAuth 2.0 (Facebook)
• Scopes: whatsapp_business_management, whatsapp_business_messaging
• Output Prefix: task_58001_*
• Token Lifetime: 30 minutes (access), 90 days (refresh)
• Rate Limits: Tier-based (1K-100K+ messages/24hr)
• Quality Ratings: GREEN, YELLOW, RED (affects limits)
• Message ID Format: wamid.xxx (WhatsApp Message ID)