Limits
Look up the size, length and rate limits that apply to incoming webhooks, the bot HTTP API, the event stream, event webhooks, attachments and interactive cards.
Limits in bytes count UTF-8 bytes: each English letter, digit or space is 1 byte, and accented letters, other scripts and emoji take 2 to 4 bytes each.
Message text
Section titled “Message text”| What | Limit |
|---|---|
content of a webhook post, message, thread reply or reply update | 80,000 bytes, counted on the text itself, not its JSON-escaped form |
content_chunk in a reply update | 80,000 bytes |
| Push notification and chat list preview of a Markdown message | Plain text, cut to 240 characters |
Text over the limit is rejected with 400 content_too_long.
| What | Limit | If it’s longer |
|---|---|---|
| Incoming webhook Name | 1–100 bytes | The webhook isn’t created |
| Incoming webhook Description | 500 bytes | The webhook isn’t created |
| Incoming webhook Display Name | 32 bytes; empty means Webhook | The webhook isn’t created |
username in a webhook post | 32 bytes | 500 send_failed |
Sender name of a top-level bot message: username, or the bot’s name when you don’t send one | 32 bytes | 500 send_failed |
username in a thread reply | 64 bytes | 500 create_failed |
| Bot name | 64 bytes. Keep it to 32 so that messages sent without username work. | — |
| Bot username | Up to 32 characters: a–z, 0–9 and _, saved in lowercase. The desktop app requires 5–32 characters, starting with a letter. | — |
Typing status_text | 80 bytes | 400 status_text_too_long |
Incoming webhooks
Section titled “Incoming webhooks”| What | Limit |
|---|---|
| Requests per webhook | 60 in any 60 seconds and 1,000 in any hour |
| Requests that count | Every request to an active webhook with a valid URL, including ones rejected for bad JSON or content |
| Over the limit | 429 rate_limit_exceeded, with no Retry-After header |
| Changing the limits | Not possible in the apps. The webhook’s page shows them under Rate Limit. |
Bot HTTP API
Section titled “Bot HTTP API”| What | Limit |
|---|---|
Chat list (GET /bots/v1/chats) | 100 chats, most recently added first, with no pagination. total counts all of the bot’s chats. |
| Typing indicator | One start event per bot and chat every 3 seconds. Extra starts return success but aren’t shown. On iPhone, the indicator disappears about 10 seconds after the last event. |
| Reply updates | About 2–4 per second recommended, one at a time per reply |
| Activity request body | 4,096 bytes |
| Activity history per reply | The last 32 entries |
| Attachment download | 10 MiB (10,485,760 bytes) per file; larger files return 413 |
| File upload | Thread replies only, when the owner allows it. 1–4 files per reply, 10 MiB per file, 30 files per bot per hour. PNG, JPEG, GIF, WebP, PDF and UTF-8 text, detected from the contents |
Event stream
Section titled “Event stream”| What | Limit |
|---|---|
| Connections per bot | 1. A new connection closes the previous one. |
| Chats per connection | Up to 10,000 of the bot’s chats |
| Event rate per bot | 100 events per minute, with bursts of up to 100. Events over the limit aren’t sent live. chat_added and chat_removed don’t count. |
| Server pings | Every 30 seconds. The connection closes if no answer arrives within 10 seconds. |
| Keepalive from your client | Send a short text frame every minute or two; its content is ignored. Currently, a connection that receives nothing from your client for 5 minutes closes, even if your client answers pings. |
Replay with last_event_id | The bot’s last 100 events from the past 5 minutes, best effort. Events that happen while no connection is open usually aren’t kept, and DonutChat restarts clear the buffer. |
| Message size to allow in your client | At least 1 MiB. One event can carry 80,000 bytes of text before JSON escaping. |
An unknown or expired last_event_id replays everything still buffered, so skip events you’ve already handled. See Event stream.
Event webhooks
Section titled “Event webhooks”| What | Limit |
|---|---|
| URL | A public https URL |
| Attempts per event | Up to 3. Network errors, 408, 429 and 5xx responses are retried; other 4xx responses end delivery. |
| Time per attempt | 10 seconds. Redirects aren’t followed. |
| Automatic switch-off | After 20 deliveries in a row fail. Switch the webhook back on in the app. |
See Event webhooks.
Interactive cards
Section titled “Interactive cards”Character limits count Unicode code points.
| What | Limit |
|---|---|
| Card block, including both fence lines | 2,800 bytes |
donut-ui blocks per message | 8, counting invalid blocks. With more, no cards render. |
| Message size for cards to render | 64,000 bytes. Larger messages show as Markdown without cards. |
Card id and action id | 1–64 characters: A–Z, a–z, 0–9, _ and - |
title | 120 characters, required |
body | 800 characters |
facts | 8 items. Each label up to 60 characters, each value up to 200. |
actions | 1–4 for confirmation and choice; none for status and facts |
Action label | 60 characters |
See Interactive cards.