> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tedro.io/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Setup

> Connect your WhatsApp Business number to Tedro using Meta Embedded Signup and understand WhatsApp messaging policies.

# WhatsApp Setup

Connect your WhatsApp Business number to Tedro with Meta's one-click Embedded Signup flow. This guide covers prerequisites, the connection process, messaging policies, and troubleshooting.

## Prerequisites

Before connecting WhatsApp, make sure you have:

* A **Meta Business Account** ([business.facebook.com](https://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)
* A Tedro workspace with **Admin** role

<Note>
  If you don't have WhatsApp Business API access yet, apply through the [Meta Business Suite](https://business.facebook.com). Approval typically takes 1-2 business days.
</Note>

## Connecting Your Number

<Steps>
  ### Open Channel Settings

  Navigate to **Settings > Channels** in your Tedro workspace.

  ### Start the Connection

  Click **Connect Channel** and select **WhatsApp** from the channel options.

  ### Authorize with Meta

  The Meta Embedded Signup flow opens in a popup window. Follow the prompts to:

  1. Log in to your Meta Business Account (if not already signed in)
  2. Select the **WhatsApp Business Account** you want to connect
  3. Choose the **phone number** to link
  4. Grant the required permissions for Tedro to send and receive messages on your behalf

  ### Verify the Connection

  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.
</Steps>

## Webhook Configuration

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

```
https://api.tedro.io/webhooks/whatsapp
```

The platform handles:

* **Webhook verification** (Meta's challenge handshake)
* **Inbound message processing**
* **Secure request validation**
* **Duplicate message prevention**

<Warning>
  Do not manually modify the webhook URL in Meta's App Dashboard unless instructed by Tedro support. Incorrect webhook configuration will prevent message delivery.
</Warning>

## 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 Tedro automatically respects at runtime. Understanding these policies is essential for building compliant workflows.

### 24-Hour Customer Service Window

<Warning>
  WhatsApp only allows **free-form messages** within **24 hours** of a customer's last inbound message. This is called the "customer service window."
</Warning>

* **Inside the window** (within 24h of last customer message): You can send any free-form text message.
* **Outside the window** (more than 24h since last customer message): You **must** use a pre-approved **message template**.

Tedro enforces this automatically. If a free-form 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:

* Tedro automatically marks the contact as opted out
* **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)

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

### 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](https://business.facebook.com) 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 template message 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

<Note>
  Template approval is handled entirely by Meta. Tedro does not control the approval process. For detailed guidance, see [Meta's template documentation](https://developers.facebook.com/docs/whatsapp/message-templates).
</Note>

### Handoff Requirement

Every published workflow in Tedro must have at least one reachable 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 template message node instead of a free-form message node.       |
| Template messages failing         | Verify the template is approved in Meta Business Suite and the template name matches exactly.                     |
| Opt-out not working               | Confirm the contact is marked as opted out. Check the STOP keyword detection in run logs.                         |
| Webhook verification failing      | Do not modify the webhook URL manually. Contact Tedro support if the auto-registration failed.                    |

## What's Next

<CardGroup cols={2}>
  <Card title="Instagram DMs" icon="instagram" href="/channels/instagram-dms">
    Connect your Instagram account to receive and respond to direct messages.
  </Card>

  <Card title="Facebook Messenger" icon="facebook" href="/channels/facebook-messenger">
    Handle Messenger conversations from your Facebook Page.
  </Card>

  <Card title="Inbox" icon="inbox" href="/platform/inbox">
    Manage all your WhatsApp conversations from the unified inbox.
  </Card>
</CardGroup>