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

# Limits and usage

> Read effective WhatsApp safeguards and channel-specific usage

WhatsApp has its own configurable limits and counters. Sending an iMessage does not consume a WhatsApp allowance or count as a WhatsApp recipient reply. An existing dedicated iMessage number is an eligibility requirement, not a shared usage ledger.

## Read effective limits

```text theme={null}
GET /api/v1/whatsapp/limits
```

Use `agent_identity_id` to select an agent when authenticating with an organization-wide credential. The response contains `agent_identity_id`, effective `limits`, and available `usage` counters. Dictionary keys retain their `whatsapp.` prefix. The daily usage counter counts outgoing messages, including replies, in the agent's rolling 24-hour window.

```bash cURL theme={null}
curl "https://inkbox.ai/api/v1/whatsapp/limits?agent_identity_id=11111111-1111-4111-8111-111111111111" \
  -H "X-API-Key: YOUR_API_KEY"
```

```python Python theme={null}
current = identity.get_whatsapp_limits()
print(current.limits["whatsapp.max_media_bytes"])
print(current.limits["whatsapp.max_text_length"])
print(current.limits["whatsapp.pre_reply_max_text_length"])
print(current.limits["whatsapp.outbound_new_contact_min_interval_seconds"])
print(current.usage["whatsapp.texts_per_agent_identity_per_24h"])
```

```typescript TypeScript theme={null}
const current = await identity.getWhatsAppLimits();
console.log(current.limits["whatsapp.max_media_bytes"]);
console.log(current.limits["whatsapp.max_text_length"]);
console.log(current.limits["whatsapp.pre_reply_max_text_length"]);
console.log(current.limits["whatsapp.outbound_new_contact_min_interval_seconds"]);
console.log(current.usage["whatsapp.texts_per_agent_identity_per_24h"]);
```

```bash CLI theme={null}
inkbox whatsapp limits --identity my-agent
```

Example response with the initial policy values:

```json theme={null}
{
  "agent_identity_id": "11111111-1111-4111-8111-111111111111",
  "limits": {
    "whatsapp.texts_per_agent_identity_per_24h": 1000,
    "whatsapp.outbound_new_contacts_per_line_per_hour": 5,
    "whatsapp.outbound_new_contacts_per_line_per_24h": 10,
    "whatsapp.consecutive_unanswered_messages": 15,
    "whatsapp.follow_up_contacts_per_line_per_24h": 75,
    "whatsapp.conversations_per_line_per_24h": 450,
    "whatsapp.outbound_new_contact_min_interval_seconds": 60,
    "whatsapp.pre_reply_messages": 3,
    "whatsapp.pre_reply_max_text_length": 159,
    "whatsapp.max_text_length": 4000,
    "whatsapp.max_media_bytes": 5242880,
    "whatsapp.pre_reply_links_allowed": 0,
    "whatsapp.pre_reply_media_allowed": 0,
    "whatsapp.pre_reply_phone_numbers_allowed": 0,
    "whatsapp.pre_reply_email_addresses_allowed": 0
  },
  "usage": {
    "whatsapp.texts_per_agent_identity_per_24h": 2
  }
}
```

Check these effective values before validating an attachment or draft. The transport ceilings are 20 MiB for one attachment and 4,000 Unicode code points for text; an organization's policy can be lower. The send and upload endpoints enforce the current policy again, including changes made after a limits read.

## Independent safeguards

Group sends count toward the daily message allowance, consecutive-unanswered limit, and distinct-conversation limit alongside direct messages. An allowed incoming message from another participant in the current connection resets that group’s unanswered count. First-contact and follow-up limits apply only to direct conversations.

The API exposes limits for daily messages, direct first-contact outreach, unanswered messages, follow-ups, distinct conversations, minimum spacing, and text/media sizes. In a direct conversation, before that recipient's first WhatsApp reply, the initial policy allows up to three opening messages of at most 159 Unicode code points each. Links, phone numbers, media, and email addresses are not allowed in those messages by default. Four independent settings control those content permissions separately from the opening-message count and length.

| Policy key | Initial fallback |
| :- | :- |
| `whatsapp.texts_per_agent_identity_per_24h` | 1,000 |
| `whatsapp.outbound_new_contacts_per_line_per_hour` | 5 |
| `whatsapp.outbound_new_contacts_per_line_per_24h` | 10 |
| `whatsapp.consecutive_unanswered_messages` | 15 |
| `whatsapp.follow_up_contacts_per_line_per_24h` | 75 |
| `whatsapp.conversations_per_line_per_24h` | 450 |
| `whatsapp.outbound_new_contact_min_interval_seconds` | 60 seconds |
| `whatsapp.pre_reply_messages` | 3 |
| `whatsapp.pre_reply_max_text_length` | 159 code points |
| `whatsapp.max_text_length` | 4,000 code points |
| `whatsapp.max_media_bytes` | 5 MiB |
| `whatsapp.pre_reply_links_allowed` | 0 (not allowed) |
| `whatsapp.pre_reply_media_allowed` | 0 (not allowed) |
| `whatsapp.pre_reply_phone_numbers_allowed` | 0 (not allowed) |
| `whatsapp.pre_reply_email_addresses_allowed` | 0 (not allowed) |

The initial daily allowance is 1,000 outgoing messages per agent in a rolling 24-hour window, including replies. This allowance remains configurable. Read the limits endpoint for your agent's effective values instead of inferring them from this fallback table. Access approval remains separate from these limits.

A policy rejection is not permission to switch identities or channels, split a message, create a new logical-send key, or automatically retry. Follow the response's error and retry guidance, and inspect the original [logical send](https://inkbox.ai/docs/api/message-sends.md) if acceptance is uncertain.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.