WhatsApp Setup

Connect your WhatsApp Business API number to Agentix and configure messaging.

WhatsApp Setup

This guide covers everything you need to connect your WhatsApp Business API number to Agentix, configure webhooks, and understand WhatsApp’s messaging policies.

Prerequisites

Before connecting WhatsApp, make sure you have:

• A Meta Business Account (business.facebook.com)
• WhatsApp Business API access enabled on your Meta Business Account
• A verified phone number registered with WhatsApp Business API (not a personal WhatsApp number)
• An Agentix workspace with Admin role

If you don’t have WhatsApp Business API access yet, apply through the Meta Business Suite. Approval typically takes 1-2 business days.

Connecting Your Number

1. Open Channel Settings
2. Navigate to Settings > Channels in your Agentix workspace.
3. Start the Connection
4. Click Connect Channel and select WhatsApp from the channel options.
5. Authorize with Meta
6. The Meta Embedded Signup flow opens in a popup window. Follow the prompts to:
8. Verify the Connection
9. Once authorization completes, your channel appears in the Channels list with a Connected status badge. You can verify by clicking Send Test Message on the channel detail page.

Webhook Configuration

Agentix automatically registers its webhook URL with Meta when you connect your number. The webhook endpoint is:

https://api.agentixx.io/webhooks/whatsapp

The platform handles:

• Webhook verification (Meta’s GET challenge/response handshake)
• Inbound message processing (POST events from Meta)
• Webhook signature verification (HMAC-SHA256 validation of every incoming request)
• Replay protection (timestamp validation with a 5-minute window)
• Idempotent processing (dedupe keys prevent duplicate message handling)

Do not manually modify the webhook URL in Meta’s App Dashboard unless instructed by Agentix support. Incorrect webhook configuration will prevent message delivery.

Testing Your Connection

After connecting:

1. Go to Settings > Channels and click on your WhatsApp channel
2. Click the Send Test Message button
3. Enter a phone number to receive the test message
4. Confirm that the message arrives on the target phone

If the test fails, check:

• Your WhatsApp Business API phone number is properly verified in Meta Business Suite
• The access token has the required permissions
• Your Meta Business Account is not restricted or under review

WhatsApp Messaging Policies

WhatsApp enforces strict messaging policies that Agentix automatically respects at runtime. Understanding these policies is essential for building compliant workflows.

24-Hour Customer Service Window

WhatsApp only allows free-form messages within 24 hours of a customer’s last inbound message. This is called the “customer service window.”

• Inside the window (within 24h of last customer message): You can send any text message using the wa.send_message node.
• Outside the window (more than 24h since last customer message): You must use a pre-approved message template via the wa.send_template node.

Agentix enforces this automatically. If a wa.send_message node tries to send outside the window, the runtime blocks it and logs an error in the run steps.

Opt-Out Handling

When a customer sends STOP, unsubscribe, or similar keywords:

• Agentix automatically sets contacts.opted_out = true on the contact record
• All messaging to that contact is halted — no further messages are sent, regardless of workflow logic
• The contact must send a new message to re-engage (which clears the opt-out flag)

Opt-out handling is a WhatsApp policy requirement. Do not attempt to override or bypass it in your workflows.

Message Templates

WhatsApp message templates are pre-approved message formats required for outbound communication outside the 24-hour window.

How templates work:

1. Create templates in the Meta Business Suite under your WhatsApp Business Account
2. Submit templates for Meta review (approval typically takes minutes to a few hours)
3. Once approved, use the template name in your wa.send_template node configuration
4. Templates support parameters — dynamic values like customer names, order numbers, etc.

Template categories:

• Utility: Order updates, appointment reminders, shipping notifications
• Marketing: Promotional offers, product announcements (stricter approval)
• Authentication: One-time passwords, verification codes

Template approval is handled entirely by Meta. Agentix does not control the approval process. For detailed guidance, see Meta’s template documentation.

Handoff Requirement

Every published workflow in Agentix must have at least one reachable wa.handoff node. This ensures that:

• Customers can always reach a human agent
• Complex issues that AI cannot resolve get proper attention
• Your business remains compliant with WhatsApp’s customer service guidelines

The platform validates this at publish time and blocks publishing if no handoff path exists.

Channel Detail Page

Each connected WhatsApp channel has a dedicated detail page (accessible from Settings > Channels > [Channel Name]) showing:

• Connection status and health indicators
• Last webhook received timestamp
• Message count in the last 24 hours
• Associated workflow (if any)
• Channel configuration and management options

Troubleshooting

Issue	Solution
Messages not arriving	Check webhook status on the channel detail page. Verify the Meta App Dashboard shows successful webhook delivery.
”Outside messaging window” errors	The customer hasn’t messaged in 24+ hours. Use a wa.send_template node instead of wa.send_message.
Template messages failing	Verify the template is approved in Meta Business Suite and the template name matches exactly.
Opt-out not working	Ensure the contact’s opted_out field is being set. Check the STOP keyword detection in run logs.
Webhook verification failing	Do not modify the webhook URL manually. Contact Agentix support if the auto-registration failed.