# Send an outbound WhatsApp Web message

`POST https://api.chat-data.com/api/v2/send-whatsapp-web-message-outbound`

Canonical: https://www.chat-data.com/api-reference/send-whatsapp-web-message-outbound

## Authentication

Send an API key as a Bearer token: `Authorization: Bearer $CHAT_DATA_API_KEY`. Workspace keys reach every chatbot in the workspace; chatbot-scoped keys reach only their chatbot. Keep keys on the server.

## Description

Send an outbound WhatsApp Web message to a phone number. The message is added to the conversation with that number, which is created if it does not exist yet, and a lead is created for the number if there is none.
When the recipient replies, their message is threaded into the same conversation.

An identical request (same chatbot, recipient, text, files and format) within 5 minutes of an accepted one is rejected with a 409 and not sent again.

---

# 🚨 CRITICAL: WhatsApp Web Ban Prevention Guide

**IMPORTANT:** This endpoint uses the unofficial WhatsApp Web protocol. **Account bans are common and permanent.** Follow these guidelines carefully to avoid losing your WhatsApp number.

## ⚠️ Terms of Service Warning

**Using WhatsApp Web for bulk messaging or automation violates WhatsApp's Terms of Service.**
- Risk of permanent account ban with no appeal process
- You could lose your personal WhatsApp number forever
- WhatsApp does not officially support automation on personal accounts
- **For compliant messaging, follow the "[Sending WhatsApp template messages](https://cookbook.chat-data.com/docs/whatsapp-integration#sending-whats-app-template-messages)" guide to send template messages via make.com or n8n using the WhatsApp Business API. When users reply, our workflow AI action can be configured to fetch the conversation context and use AI to respond automatically.**

**Use this endpoint at your own risk. These guidelines help reduce ban risk but do not guarantee safety.**

---

## 📊 Daily Limits by Account Age

| Account Age            | Max NEW Contacts/Day | Total Messages/Day |
|------------------------|----------------------|--------------------|
| First 10 days          | 20 contacts          | 40-50 messages     |
| New (2-6 months)       | 100-150 contacts     | 100-200 messages   |
| Established (6-12 mo)  | 200-300 contacts     | 200-300 messages   |
| Mature (2+ years)      | Up to 500 contacts   | 400-500 messages   |

**Note:** These are community-reported estimates, not official WhatsApp limits. Actual limits may vary by region, account history, and WhatsApp's detection algorithms.

**Conservative recommendation:** Max 200 new contacts/day regardless of account age.

---

## 🌍 Additional Risk Factors

### Regional Variations
- **India & Brazil:** Significantly stricter enforcement due to high spam rates
- Ban thresholds may be lower in these regions
- Consider even more conservative limits if sending from/to these countries

### Multi-Session Limitations
- WhatsApp Web supports **4-5 concurrent linked devices maximum**
- Connecting too many sessions simultaneously can trigger security flags
- Avoid frequent session connects/disconnects
- May need to re-authenticate after WhatsApp app updates

---

## ⚠️ Critical Ban Triggers (Avoid These!)

### Instant Ban Scenarios:
1. **Spam Reports:** 5-10 spam reports = permanent ban
   - 10% spam rate (10 blocks out of 100 contacts) = high ban risk
2. **Cold Messaging:** Sending without opt-in consent = guaranteed ban
3. **Speed Violations:**
   - Sending identical messages to 100+ contacts in <1 hour
   - No delays between messages (instant sending)
4. **Low Engagement:** Consistently low response/reply rates may flag account as spam
5. **New Account Abuse:** New account sending 100+ messages on day 1

---

## 🎯 Recommended Implementation Strategies

**Note:** No strategy guarantees ban prevention. WhatsApp's detection algorithms are proprietary and can change without notice. These are community best practices.

### Conservative Approach (Safest - Recommended for New Accounts)

**Limits:**
- Max 50 NEW contacts per day (first month)
- Max 100 total messages per day
- 45-60 second delay between messages (randomized)
- Recommended: Send during business hours (9 AM - 6 PM) for better engagement

**Batch Strategy:**
- 20 contacts per batch
- 15-minute cooldown between batches
- Stop immediately if response rate drops below 40%

**Warm-up Schedule (First 30 Days):**
- Days 1-10: Max 20 NEW contacts/day
- Days 11-20: Max 50 NEW contacts/day
- Days 21-30: Max 100 NEW contacts/day
- After 30 days: Max 150-200 NEW contacts/day

### Standard Approach (After 1-2 Months)

**Limits:**
- Max 150 NEW contacts per day
- Max 200 total messages per day
- 30-50 second delay between messages (randomized)

**Batch Strategy:**
- 30 contacts per batch
- 10-minute cooldown between batches
- Stop if response rate drops below 45%

### Aggressive Approach (Mature Accounts Only - 2+ Years)

**Limits:**
- Max 300 NEW contacts per day
- Max 400 total messages per day
- 20-40 second delay between messages (randomized)

**Batch Strategy:**
- 50 contacts per batch
- 10-minute cooldown between batches
- Stop if response rate drops below 50%

**⚠️ Warning:** Even mature accounts can be banned. Use with caution.

---

## ✅ Success Checklist

Before sending messages, ensure:
- [ ] Messages are **personalized** (not identical mass messages)
- [ ] Account has completed **warm-up period** (if new)
- [ ] Consider sending during **business hours** (9 AM - 6 PM) for better engagement
- [ ] Rate limiting is **implemented and tested**
- [ ] Response rate monitoring is **active**
- [ ] Daily quotas are **tracked per account**
- [ ] Batch processing with **cooldowns is configured**

---

## 🛑 Failure Indicators - Stop Immediately If:

- Response rate drops below 30%
- You receive 2-3 spam reports
- Messages fail to deliver
- You receive a warning message from this API
- Contacts start blocking you

**Recovery:** If you see these signs, stop all outbound messaging for 24-48 hours and review your strategy.

---

## 🏢 For Business/High-Volume Use

If you need to send:
- More than 200 messages per day
- Marketing or promotional content
- Business-critical communications

**Use a workflow automation platform with WhatsApp Business API integration instead.** Follow the "[Sending WhatsApp template messages](https://cookbook.chat-data.com/docs/whatsapp-integration#sending-whats-app-template-messages)" guide to send messages via make.com or n8n with our provided access token.
When the user replies, you can use our workflow AI action, triggered on the first user message, to fetch the conversation context and respond automatically with AI.

The unofficial WhatsApp Web protocol is not suitable for business operations and carries high ban risk.

---

**Audio messages:** To send audio messages, make sure your [plan](/pricing) includes audio messages and enable audio in Settings → Chat Interface.

## Request body (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| chatbotId | string | yes | The unique identifier of the chatbot. |
| phone | string | yes | Recipient phone number in E.164 format, with or without the leading '+' (for example 14155550123). |
| message | string | yes | The message text to send. It must not be empty. |
| files | array of object | no | An optional array of file objects to be attached to the message, at most 3. |
| files[].name | string | yes | The name of the file. |
| files[].type | string | yes | The MIME type of the file (for example image/png or application/pdf). |
| files[].url | string | yes | The public http(s) URL of the file. |
| format | string | no | Format of the message. When set to 'audio', the message text is converted to audio using text-to-speech. **Audio requirements:** - Requires a [plan](/pricing) that includes audio messages. - Audio must be enabled in the chatbot settings: Settings → Chat Interface → Enable Audio. - **Note:** If audio is not enabled, the API falls back to text and sends the message as text instead. Valid values: 'text' (default, sends a text message) or 'audio' (converts the text to audio using text-to-speech, or falls back to text if audio is not enabled). |

## Example request

```bash
curl 'https://api.chat-data.com/api/v2/send-whatsapp-web-message-outbound' \
  -H "Authorization: Bearer $CHAT_DATA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "chatbotId": "6650f1c2a9e4b83d2c7a1f05",
  "phone": "14155550123",
  "message": "Hi Jane, your order #10482 has shipped. Reply here if you have any questions."
}'
```

## Example response (200)

```json
{
  "status": "success",
  "conversationId": "14155550100:14155550123",
  "leadUUID": "14155550123",
  "actualFormat": "text"
}
```

## Responses

| Status | Description |
| --- | --- |
| 200 | Message sent successfully. |
| 400 | The message could not be sent. For example: `chatbotId`, `phone` or `message` is missing, the phone number is invalid, `format` is not `text` or `audio`, `files` is not an array or has an invalid item or more than 3 items, WhatsApp Web is not set up for the chatbot, or the WhatsApp Web session is offline, expired or has no phone number yet. |
| 401 | Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which. |
| 403 | The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace. |
| 409 | An identical message (same chatbot, recipient, text, files and format) was already accepted in the last 5 minutes. It is not sent again. |
| 429 | The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying. |
| 500 | The message could not be sent through WhatsApp Web; `message` contains the error (`fetch failed` when the WhatsApp Web relay cannot be reached). When the relay rejects the message, its HTTP status is returned instead of 500. |