WhatsApp

Overview

The WhatsApp provider integrates with the WhatsApp Business Platform Cloud API (via Meta). It supports:

• Text messages
• Template messages
• Interactive buttons
• List messages
• Media (images, documents, audio, video)
• Location sharing

Prerequisites

• Meta Business account
• WhatsApp Business API access
• Verified phone number

Setup

1. Create Meta App

   Go to developers.facebook.com:

   • Create a new app (Business type)
   • Add WhatsApp product
   • Set up WhatsApp Business API

2. Get API Credentials

   In your Meta app dashboard:

   • Go to WhatsApp → Getting Started
   • Copy Phone Number ID
   • Generate an access token. Use a system user or other production-grade token strategy for production deployments.
   • Note your Business Account ID

3. Configure Webhook

   In WhatsApp → Configuration:

   • Set Callback URL: https://your-domain.com/webhook/whatsapp/{tenant}/{team}
   • Set Verify Token (any string you choose)
   • Subscribe to: messages

4. Configure Provider

   answers.json

   {
     "messaging-whatsapp": {
       "enabled": true,
       "public_base_url": "https://your-domain.ngrok-free.app",
       "api_base_url": "https://graph.facebook.com",
       "api_version": "v21.0",
       "phone_number_id": "123456789012345",
       "whatsapp_token": "EAAxxxxx...",
       "whatsapp_verify_token": "your-verify-token",
       "business_account_id": "987654321098765"
     }
   }

5. Run Setup

   gtc setup --answers answers.json ./my-bundle

Configuration Options

Option	Required	Description
enabled	Yes	Enable/disable provider
public_base_url	Yes	Public URL for webhook
phone_number_id	Yes	WhatsApp phone number ID
whatsapp_token	Yes	WhatsApp Cloud API access token
whatsapp_verify_token	Yes	Webhook verification token
business_account_id	No	WhatsApp Business Account ID
api_base_url	No	Graph API base URL (default: https://graph.facebook.com)
api_version	No	Graph API version used by the installed pack

Note

The setup layer also accepts the older access_token alias and stores it as whatsapp_token, but new answers files should use the wizard-generated key. Use gtc wizard --schema or gtc setup to confirm the exact fields for the pack version in your bundle.

Features

Text Messages

- id: reply
  type: reply
  config:
    message: "Hello! How can I help you today?"

Template Messages

Attention

WhatsApp requires pre-approved templates for initiating conversations. Templates must be approved by Meta before use.

- id: send_template
  type: reply
  config:
    template:
      name: "order_confirmation"
      language: "en"
      components:
        - type: body
          parameters:
            - type: text
              text: "{{order_id}}"
            - type: text
              text: "{{customer_name}}"

Interactive Buttons

- id: ask_action
  type: reply
  config:
    interactive:
      type: button
      body:
        text: "What would you like to do?"
      action:
        buttons:
          - type: reply
            reply:
              id: "help"
              title: "Get Help"
          - type: reply
            reply:
              id: "status"
              title: "Check Status"
          - type: reply
            reply:
              id: "human"
              title: "Talk to Human"

List Messages

- id: show_menu
  type: reply
  config:
    interactive:
      type: list
      header:
        type: text
        text: "Support Menu"
      body:
        text: "Please select an option:"
      action:
        button: "View Options"
        sections:
          - title: "Support"
            rows:
              - id: "technical"
                title: "Technical Support"
                description: "Hardware and software issues"
              - id: "billing"
                title: "Billing"
                description: "Payment and invoices"
          - title: "Sales"
            rows:
              - id: "pricing"
                title: "Pricing"
                description: "Product pricing information"

Send Images

- id: send_image
  type: reply
  config:
    media:
      type: image
      link: "https://example.com/product.jpg"
      caption: "Here's the product image"

Send Documents

- id: send_document
  type: reply
  config:
    media:
      type: document
      link: "https://example.com/invoice.pdf"
      filename: "invoice.pdf"
      caption: "Your invoice is attached"

Send Location

- id: send_location
  type: reply
  config:
    location:
      latitude: 37.7749
      longitude: -122.4194
      name: "Our Office"
      address: "123 Main St, San Francisco, CA"

Handling Button Clicks

flows/on_button.ygtc

name: handle_button
version: "1.0"

nodes:
  - id: route_button
    type: branch
    config:
      conditions:
        - expression: "button.id == 'help'"
          to: show_help
        - expression: "button.id == 'status'"
          to: check_status
        - expression: "button.id == 'human'"
          to: escalate
      default: unknown

  - id: show_help
    type: reply
    config:
      message: "Here's how I can help..."

triggers:
  - type: interactive
    target: route_button

Message Templates

Creating Templates

1. Go to Meta Business Suite → WhatsApp Manager → Message Templates
2. Create a new template with required components
3. Submit for approval. Approval timing is controlled by Meta and varies by account, category, and template content.

Template Components

- id: send_notification
  type: reply
  config:
    template:
      name: "appointment_reminder"
      language: "en"
      components:
        - type: header
          parameters:
            - type: image
              image:
                link: "https://example.com/logo.png"
        - type: body
          parameters:
            - type: text
              text: "{{customer_name}}"
            - type: text
              text: "{{appointment_time}}"
        - type: button
          sub_type: quick_reply
          index: 0
          parameters:
            - type: payload
              payload: "confirm"

24-Hour Window

Note

WhatsApp enforces a 24-hour messaging window. After 24 hours without user response, you must use template messages.

Check Window Status

- id: check_window
  type: branch
  config:
    conditions:
      - expression: "last_message_time + 86400 > now"
        to: send_freeform
      default: send_template

- id: send_freeform
  type: reply
  config:
    message: "Thanks for your message!"

- id: send_template
  type: reply
  config:
    template:
      name: "follow_up"
      language: "en"

Troubleshooting

Webhook Verification Failed

1. Verify whatsapp_verify_token matches the token configured in Meta
2. Check webhook URL is publicly accessible
3. Ensure HTTPS is properly configured

Message Not Delivered

• Check phone number format (include country code)
• Verify template is approved (if using templates)
• Check 24-hour window status
• Review Meta webhook logs

Rate Limiting

WhatsApp messaging limits are controlled by Meta and depend on the phone number, account quality, messaging limit, conversation category, and current platform policy. Check WhatsApp Manager and Meta’s current messaging-limits documentation for the exact limit that applies to your number.

Handle gracefully:

- id: reply
  type: reply
  config:
    message: "Response"
    retry_on_rate_limit: true

Security

Attention

Validate webhook signatures to ensure requests are from Meta.

Greentic validates:

• X-Hub-Signature-256 header
• Payload hash with app secret

Best Practices

1. Use templates wisely - Create versatile, approved templates
2. Respect the 24-hour window - Track user engagement
3. Handle opt-outs - Respect STOP/UNSUBSCRIBE requests
4. Keep messages concise - WhatsApp is for quick communication
5. Use rich media - Images and documents enhance UX

Next Steps

• Telegram Provider - Alternative messaging
• Template Guidelines - Meta’s template rules
• Flows Guide - Build complex workflows