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

Outputs¶

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

Always emitted¶

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_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": "welcome_new_customer",
     "parameters": [
       {
         "name": "customer_name",
         "value": "John Doe"
       },
       {
         "name": "order_number",
         "value": "12345"
       }
     ]
   }
   

6. Returns WATI's answer in response

The template name is also sent as the broadcast name, so the send shows under that name in WATI.

A parameter must have its value. A parameter name saved without its value row fails the task straight away — WhatsApp parameter "customer_name" (1) has no value row — instead of sending a template with a gap in it. Remove the parameter and add it again.

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

File URL Requirements:

• BaseCloud downloads the file from the URL itself, so it must be reachable without signing in
• The file type and size must be ones WhatsApp accepts — WATI refuses the rest, and the task fails with its answer

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 WATI's answer in response

The attribute names are the ones your WATI account defines — check them in WATI before mapping values to them.

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. Records the file in BaseCloud (not attached to a client)
7. Returns Azure URL and file metadata

Use Case:

When customer sends image/document via WhatsApp:

1. A Webhook In trigger receives the media URL WATI posts
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¶

Send a WhatsApp template when a lead arrives¶

Form Submission
  └─ Phone Formatter   normalise the number
      └─ WATI          send the welcome template

WATI needs the number in international format, so normalise it first.

Send an appointment reminder¶

Schedule
  └─ Match to Client   look the client up
      └─ WATI          send the reminder template

Share a document over WhatsApp¶

Webhook In
  └─ PDF       generate the document
      └─ WATI  send it as a file, using {{task_36001_document_url}}

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. Check token hasn't expired (regenerate if needed)

Error: "No WhatsApp number is configured"¶

Cause: Recipient number field is empty

Solutions:

1. Provide number with country code, no + symbol: 27821234567
2. Verify number exists in client record
3. If it comes from an earlier task, check that task ran and has the number — a Phone Formatter normalises it

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 WhatsApp accepts the file's type and size
4. Test the URL in a 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

Rate Limiting / 429 Errors¶

Cause: Sending messages too quickly

Solutions:

1. BaseCloud already backs off and retries a rate-limited call — the run shows "Rate limited — rescheduled for retry."
2. In a Loop sending many messages, add a Delay between them
3. WATI's limits vary by plan — contact WATI to raise them

Best Practices¶

1. Keep the Access Token out of sight. It is withheld when the workflow is read; rotate it in WATI if it may have leaked.
2. Use templates for the first message. Session messages and files only reach someone who messaged in the last 24 hours.
3. Name template parameters clearly (customer_name, not param1) — they must match the template's placeholders exactly.
4. Generate files with a PDF task and send its document_url.
5. Archive what customers send with get_media, so the file stays in BaseCloud after WATI's link expires.

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: Keep the opt-out on the client — for example a custom field — and check it with an If before the WATI task.

Q: Can I schedule messages for later?

A: Start the workflow from a Timer Trigger, or put a Delay before the WATI task.

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 can post delivery events to a webhook — catch them with a Webhook In trigger.

Q: Can I receive messages from customers?

A: Yes — point WATI's webhook at a Webhook In trigger.

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
• 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