WATI WhatsApp API¶

Overview¶

The WATI task integrates BaseCloud CRM with WATI's WhatsApp Business API platform, enabling automated WhatsApp messaging including templates, session messages, file sharing, and contact management.

Key Features:

• 5 Actions: Send messages, files, templates, update contacts, retrieve media
• Bearer Token Auth: Simple API key authentication
• Template Messaging: Pre-approved marketing templates with dynamic parameters
• Session Messaging: 24-hour conversational window
• Media Handling: Send files and retrieve media from WATI
• Contact Sync: Update contact attributes in WATI system

Use Cases:

• Automated lead follow-up with template messages
• Invoice delivery via WhatsApp with PDF attachments
• Customer support automation with session messaging
• Contact data synchronization between CRM and WATI
• Marketing campaigns with approved templates

Prerequisites¶

1. WATI Account¶

WATI Setup:

• Active WATI subscription: https://www.wati.io
• WhatsApp Business number configured in WATI
• Access to WATI Dashboard
• Message templates approved by WhatsApp

2. API Credentials¶

Obtain from WATI Dashboard:

1. Log into WATI Dashboard
2. Navigate to Settings → API or Integrations → API
3. Copy API Endpoint URL (format: https://live-server-XXXXX.wati.io)
4. Copy Access Token (Bearer token)
5. Note: Each WATI account has unique endpoint and token

API Endpoint Format:

https://live-server-12345.wati.io

Access Token Format:

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

3. WhatsApp Number¶

• WhatsApp Business number must be active in WATI
• Number cannot be used simultaneously on other platforms
• Verify number is connected and operational in WATI Dashboard

4. Message Templates (Optional)¶

For Template Messaging:

1. Create templates in WATI Dashboard
2. Submit for WhatsApp approval
3. Wait for approval (usually 24-48 hours)
4. Note template names for use in tasks

Configuration¶

Action 1: send_session_message¶

Send text message within 24-hour conversational window.

Output Variables:

task_23001_run           // true/false
task_23001_run_text      // "Successfully sent message."
task_23001_response      // Full WATI API response

How It Works:

1. Validates required fields (endpoint, token, number, text)
2. Constructs URL: POST {endpoint}/api/v1/sendSessionMessage/{number}?messageText={text}
3. Adds Authorization header with Bearer token
4. Sends message via WATI API
5. Returns success status and API response

24-Hour Window:

• Session messages only work within 24 hours of last customer message
• Outside window, use send_template_message instead
• WATI returns error if session expired

Action 2: send_template_message¶

Send pre-approved WhatsApp template message (works anytime).

Add as many parameter pairs as needed

Output Variables:

task_23001_run           // true/false
task_23001_run_text      // "Successfully sent message."
task_23001_response      // Full WATI API response with message ID

How It Works:

1. Validates required fields
2. Collects all parameter_name_X and parameter_value_X pairs
3. Builds parameter array matching template placeholders
4. Constructs URL: POST {endpoint}/api/v1/sendTemplateMessage?whatsappNumber={number}
5. POST body:

   {
     "template_name": "welcome_new_customer",
     "broadcast_name": "BaseCloud Automation",
     "parameters": [
       {
         "name": "customer_name",
         "value": "John Doe"
       },
       {
         "name": "order_number",
         "value": "12345"
       }
     ]
   }
   

6. Returns success with message ID

Template Parameters:

Templates defined in WATI use placeholders like {{customer_name}}. Parameter names must match exactly.

Example template:

Hello {{customer_name}}, 
Your order #{{order_number}} is confirmed! 
Delivery: {{delivery_date}}

Requires 3 parameters: customer_name, order_number, delivery_date

Action 3: send_session_file¶

Send file/media within 24-hour conversational window.

Output Variables:

task_23001_run           // true/false
task_23001_run_text      // "Successfully sent file."
task_23001_response      // Full WATI API response

How It Works:

1. Validates required fields
2. Downloads file from file_url
3. Creates FormData with file and caption
4. Uploads via: POST {endpoint}/api/v1/sendSessionFile/{number}
5. WATI processes and sends to recipient

Supported File Types:

• Images: JPG, PNG, GIF (max 5MB)
• Videos: MP4, 3GP (max 16MB)
• Documents: PDF, DOC, DOCX, XLS, XLSX, PPT (max 100MB)
• Audio: MP3, OGG, AMR (max 16MB)

File URL Requirements:

• Must be publicly accessible (no authentication)
• HTTPS preferred
• Valid content type
• File size within WhatsApp limits

Action 4: update_contact¶

Update contact attributes in WATI system.

Add as many parameter pairs as needed

Output Variables:

task_23001_run           // true/false
task_23001_run_text      // "Successfully updated contact."
task_23001_response      // Updated contact object

How It Works:

1. Collects all parameter_name_X and parameter_value_X pairs
2. Builds custom attributes array
3. Sends to: POST {endpoint}/api/v1/updateContactAttributes/{number}
4. POST body:

   {
     "customParams": [
       {
         "name": "first_name",
         "value": "John"
       },
       {
         "name": "email",
         "value": "john@example.com"
       }
     ]
   }
   

5. Returns updated contact data

Common Attributes:

• first_name, last_name - Contact names
• email - Email address
• company - Company name
• city, country - Location data
• Custom attributes defined in WATI

Action 5: get_media¶

Retrieve media file from WATI and upload to Azure storage.

Output Variables:

task_23001_run                    // true/false
task_23001_run_text               // "Successfully fetched media."
task_23001_response               // Full file object
  task_23001_response.id          // File database ID
  task_23001_response.owner_id    // BaseCloud owner ID
  task_23001_response.file_url    // Azure Blob Storage URL
  task_23001_response.file_name   // Sanitized filename (basecloud_wa_*)
  task_23001_response.size        // File size in bytes
  task_23001_response.contentType // MIME type

How It Works:

1. Validates file URL has fileName query parameter
2. Extracts filename from URL
3. Downloads file from WATI: GET {file_url} with Authorization header
4. Sanitizes filename: basecloud_wa_{original_filename}
5. Uploads to Azure Blob Storage (owner-specific container)
6. Creates database record in files table
7. Returns Azure URL and file metadata

Use Case:

When customer sends image/document via WhatsApp:

1. Webhook trigger receives media URL from WATI
2. Use get_media action to download and store
3. Azure URL can be used in other tasks (attach to email, save to client record, etc.)

Real-World Examples¶

Example 1: Automated Lead Follow-Up¶

Scenario: When lead submits form, send WhatsApp welcome message with company info.

Workflow:

1. Trigger: Website Form Submission

2. Task: New Client - Create Lead

   first_name: {{task_55001_first_name}}
   phone: {{task_55001_phone}}
   

3. Task: WATI - Send Template Message

   wati_action: send_template_message
   API Endpoint: https://live-server-12345.wati.io
   Access Token: Bearer {{stored_wati_token}}
   whatsappNumber: {{task_55001_phone}}
   template_name: new_lead_welcome
   parameter_name_1: first_name
   parameter_value_1: {{task_55001_first_name}}
   parameter_name_2: company_name
   parameter_value_2: BaseCloud CRM
   

4. Task: Edit Client - Tag

   Field: tags
   Value: WhatsApp Welcome Sent
   

5. Task: Workflow Note

   Note: Welcome template sent to {{task_55001_first_name}} at {{task_55001_phone}}
   Type: Marketing
   

Result: Instant WhatsApp engagement with new leads using approved template.

Example 2: Invoice Delivery with PDF¶

Scenario: When invoice is created, send PDF via WhatsApp with payment link.

Workflow:

1. Trigger: CRM Event - Invoice Created

2. Task: Generate PDF Invoice

   invoice_id: {{task_47001_invoice_id}}
   

3. Task: If Condition - Has WhatsApp Number

   Condition: {{client_whatsapp_number}} is not empty
   

4. Task (Inside If): WATI - Send Session File

   wati_action: send_session_file
   API Endpoint: https://live-server-12345.wati.io
   Access Token: Bearer {{wati_token}}
   whatsappNumber: {{client_whatsapp_number}}
   file_url: {{task_36001_document_url}}
   caption: Invoice #{{task_47001_invoice_number}} - Amount: R{{task_47001_total}}
   

5. Task (Inside If): Delay 5 seconds

6. Task (Inside If): WATI - Send Session Message

   wati_action: send_session_message
   messageText: Pay online: {{task_47001_payment_link}}
   

7. Task: Workflow Note

   Note: Invoice {{task_47001_invoice_number}} sent via WhatsApp with payment link
   

Result: Customers receive invoice PDF and payment link directly on WhatsApp for easy payment.

Example 3: Contact Data Synchronization¶

Scenario: Keep WATI contact attributes synchronized with CRM client data.

Workflow:

1. Trigger: CRM Event - Client Updated

2. Task: If Condition - Has WhatsApp

   Condition: {{client_whatsapp_number}} is not empty
   

3. Task (Inside If): WATI - Update Contact

   wati_action: update_contact
   API Endpoint: https://live-server-12345.wati.io
   Access Token: Bearer {{wati_token}}
   whatsappNumber: {{client_whatsapp_number}}
   parameter_name_1: first_name
   parameter_value_1: {{client_first_name}}
   parameter_name_2: last_name
   parameter_value_2: {{client_last_name}}
   parameter_name_3: email
   parameter_value_3: {{client_email}}
   parameter_name_4: company
   parameter_value_4: {{client_company_name}}
   parameter_name_5: city
   parameter_value_5: {{client_city}}
   parameter_name_6: status
   parameter_value_6: {{client_status}}
   

4. Task: Workflow Note

   Note: WATI contact updated for {{client_first_name}} {{client_last_name}}
   

Result: WATI always has latest client data for personalized messaging and segmentation.

Example 4: Marketing Campaign with Templates¶

Scenario: Send promotional message to all active clients using approved template.

Workflow:

1. Trigger: Manual Button - Launch Campaign

2. Task: MySQL Query - Get Active Clients

   SELECT client_id, first_name, whatsapp_number, loyalty_points
   FROM clients
   WHERE status = 'Active'
     AND whatsapp_number IS NOT NULL
     AND whatsapp_opt_in = 1
   

3. Task: Loop - Process Each Client

   Loop through MySQL results
   

4. Task (Inside Loop): WATI - Send Template Message

   wati_action: send_template_message
   API Endpoint: https://live-server-12345.wati.io
   Access Token: Bearer {{wati_token}}
   whatsappNumber: {{loop_item_whatsapp_number}}
   template_name: special_offer_announcement
   parameter_name_1: customer_name
   parameter_value_1: {{loop_item_first_name}}
   parameter_name_2: loyalty_points
   parameter_value_2: {{loop_item_loyalty_points}}
   parameter_name_3: offer_code
   parameter_value_3: SAVE20
   

5. Task (Inside Loop): Delay 2 seconds

   Reason: Rate limiting prevention
   

6. Task (Inside Loop): MySQL - Log Campaign

   INSERT INTO campaign_logs (client_id, campaign_name, sent_date)
   VALUES ({{loop_item_client_id}}, 'Special Offer Q1', NOW())
   

7. Task: Email - Campaign Summary

   To: marketing@company.com
   Subject: WhatsApp Campaign Complete
   Body: Sent to {{loop_count}} clients
   

Result: Bulk WhatsApp marketing with personalized messages and compliance tracking.

Example 5: Customer Support with Media¶

Scenario: Customer sends image via WhatsApp, automatically create support ticket with image.

Workflow:

1. Trigger: WATI Webhook - Message Received

2. Condition: Message has media

3. Task: Match to Client

   phone: {{task_46001_sender_number}}
   

4. Task: WATI - Get Media

   wati_action: get_media
   API Endpoint: https://live-server-12345.wati.io
   Access Token: Bearer {{wati_token}}
   file_url: {{task_46001_media_url}}
   

5. Task: MySQL - Create Support Ticket

   INSERT INTO support_tickets 
   (client_id, message, media_url, status, created_date)
   VALUES (
     {{task_15001_client_id}},
     '{{task_46001_message_text}}',
     '{{task_23001_response.file_url}}',
     'Open',
     NOW()
   )
   

6. Task: WATI - Send Session Message

   wati_action: send_session_message
   whatsappNumber: {{task_46001_sender_number}}
   messageText: Thank you! Support ticket #{{mysql_insert_id}} created. We'll respond within 2 hours.
   

7. Task: Email - Alert Support Team

   To: support@company.com
   Subject: New WhatsApp Support Request
   Body: Ticket #{{mysql_insert_id}} from {{client_first_name}}
         Image: {{task_23001_response.file_url}}
   

Result: Seamless support ticket creation from WhatsApp messages with media attachment.

Troubleshooting¶

Error: "No API endpoint provided"¶

Cause: API Endpoint field is empty

Solutions:

1. Obtain endpoint from WATI Dashboard → Settings → API
2. Format: https://live-server-XXXXX.wati.io (no trailing slash)
3. Verify URL is accessible (test in browser)

Error: "No Access Token provided"¶

Cause: Access Token field is empty

Solutions:

1. Copy full token from WATI Dashboard
2. Include "Bearer " prefix: Bearer eyJhbGci...
3. Store in Variable task for reuse
4. Check token hasn't expired (regenerate if needed)

Error: "No whatsappNumber provided"¶

Cause: Recipient number field is empty

Solutions:

1. Provide number with country code, no + symbol: 27821234567
2. Verify number exists in client record
3. Check variable reference: {{client_whatsapp_number}}
4. Validate number format (digits only)

Session Message Failed (Outside 24-Hour Window)¶

Cause: Attempting session message without active conversation

Solutions:

1. Use send_template_message instead (works anytime)
2. Check last customer message timestamp in WATI
3. Customer must message first to open 24-hour window
4. Use template for initial outreach

Template Not Found¶

Cause: Template name doesn't exist or not approved

Solutions:

1. Verify template exists in WATI Dashboard → Templates
2. Check template status is "Approved" (not Pending/Rejected)
3. Match exact template name (case-sensitive)
4. Wait for WhatsApp approval if recently submitted

Template Parameters Mismatch¶

Cause: Parameter names don't match template placeholders

Solutions:

1. Check template definition in WATI Dashboard
2. Match parameter names exactly: {{customer_name}} requires parameter_name_1: customer_name
3. Provide all required parameters
4. Order doesn't matter, names must match

File Upload Failed¶

Cause: File URL inaccessible or invalid format

Solutions:

1. Verify URL is publicly accessible (no authentication)
2. Use HTTPS URLs when possible
3. Check file size within limits (images 5MB, documents 100MB)
4. Ensure valid file extension
5. Test URL in browser first

Media Retrieval Error: "Invalid filepath within URL"¶

Cause: get_media file_url missing fileName query parameter

Solutions:

1. WATI media URLs include fileName: https://...?fileName=image.jpg
2. Don't construct URLs manually - use from webhook
3. Verify {{task_46001_media_url}} contains full URL with params

Contact Update Not Reflecting¶

Cause: Attribute names don't match WATI custom fields

Solutions:

1. Check custom attribute names in WATI Dashboard → Settings → Custom Attributes
2. Use exact spelling and casing
3. Create custom attributes in WATI first
4. Standard fields: first_name, last_name, email, company

Rate Limiting / 429 Errors¶

Cause: Sending messages too quickly

Solutions:

1. Add Delay tasks between messages in loops (2-5 seconds)
2. WATI has rate limits (varies by plan)
3. Implement exponential backoff for retries
4. Contact WATI support to increase limits

Best Practices¶

Authentication Security¶

1. Store Credentials Securely:
2. Use Variable task to store API Endpoint and Access Token
3. Reference variables: {{wati_api_endpoint}}, {{wati_access_token}}

4. Never hardcode in automation tasks

5. Token Management:

6. Rotate tokens periodically
7. Use separate tokens for dev/staging/production
8. Monitor token usage in WATI Dashboard

Template Design¶

1. Plan Templates:
2. Design templates for common scenarios (welcome, invoice, reminder)
3. Keep templates short and actionable

4. Include clear call-to-action

5. Parameter Naming:

6. Use descriptive parameter names: customer_name, not param1
7. Document parameter mappings in workflow notes

8. Validate parameter values before sending

9. Approval Process:

10. Submit templates for approval before building workflows
11. Test with approved templates first
12. Keep rejected template reasons for future submissions

Message Strategy¶

1. Session vs Template:
2. Use session messages for ongoing conversations (cheaper)
3. Use templates for initial outreach and marketing

4. Track conversation status to choose appropriately

5. Timing:

6. Respect customer time zones
7. Avoid late night/early morning sends

8. Use Timer triggers for scheduled campaigns

9. Opt-In Compliance:

10. Maintain opt-in status in CRM (whatsapp_opt_in field)
11. Provide unsubscribe mechanism
12. Respect opt-out immediately

File Handling¶

1. File URLs:
2. Generate PDFs with public URLs (PDF task Type 36)
3. Use Azure/S3 signed URLs for temporary access

4. Verify URLs accessible before sending

5. File Sizes:

6. Compress images before sending (max 5MB)
7. Split large documents if needed

8. Provide fallback (email) for large files

9. Media Storage:

10. Use get_media to archive customer-sent files
11. Store Azure URLs in client records
12. Set retention policies for media

Error Handling¶

1. Validation:
2. Check required fields before WATI task
3. Use If Conditions to verify data exists

4. Provide fallback workflows for failures

5. Logging:

6. Always add Workflow Notes for WATI actions
7. Include message IDs, recipients, template names

8. Log failures for troubleshooting

9. Retries:

10. Implement retry logic for transient failures
11. Use exponential backoff (delay 5s, 15s, 30s)
12. Alert admins after 3 failed attempts

Performance¶

1. Rate Limiting:
2. Add 2-second delays in bulk sending loops
3. Monitor WATI usage dashboard

4. Schedule large campaigns during off-peak

5. Caching:

6. Cache template list (reload periodically)
7. Store contact attributes locally
8. Minimize API calls where possible

FAQ¶

Q: Can I use WATI and WhatsApp Business simultaneously?

A: No, WhatsApp number can only be connected to one platform at a time. Choose WATI or Meta WhatsApp Business Cloud API.

Q: What's the difference between session and template messages?

A: - Session Messages: Free text, requires active conversation (24-hour window) - Template Messages: Pre-approved, can send anytime, costs per message

Q: How do I get templates approved?

A: Create template in WATI Dashboard → Submit for WhatsApp review → Wait 24-48 hours for approval.

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

A: No, WhatsApp requires approved templates for initial outreach and messaging outside conversation windows.

Q: What file types can I send?

A: Images (JPG, PNG, GIF), videos (MP4), documents (PDF, DOC, XLS, PPT), audio (MP3, OGG).

Q: How do I handle opt-outs?

A: Maintain whatsapp_opt_in field in CRM. Check before sending. Provide "Reply STOP to opt out" in templates.

Q: Can I schedule messages for later?

A: Use Timer Trigger to schedule automation runs at specific times/dates.

Q: What happens if recipient number is invalid?

A: WATI returns error in response. Check {{task_23001_response}} for error details.

Q: Can I send bulk messages?

A: Yes, use Loop task with delays. Ensure compliance with WhatsApp policies and opt-ins.

Q: How do I track message delivery?

A: WATI provides delivery status in webhook responses. Set up webhook trigger to capture delivery events.

Q: Can I receive messages from customers?

A: Yes, use WATI Webhook Trigger to handle incoming messages.

Q: What's the cost per message?

A: Varies by WATI plan. Session messages usually free, template messages charged per send.

Related Tasks¶

• WhatsApp Business - Alternative using Meta's official API
• Email - Fallback communication channel
• SMS - Alternative text messaging
• PDF - Generate documents to send
• Loop - Bulk message sending
• If Statement - Message routing logic
• Delay - Rate limiting in loops
• Webhook In - Receive WATI webhooks

Technical Details¶

• Type ID: 23
• Function: taskWATI() in automationService.js (lines 5448-5744)
• API Version: WATI API v1
• Authentication: Bearer Token
• Output Prefix: task_23001_*
• Rate Limits: Varies by WATI plan
• Session Window: 24 hours from last customer message