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

# Notes & Limits

> Double-handling with the native assistant, current limits, and common errors

## Double-handling with the native assistant

Registering an inbound webhook is **additive**: it never disables Minimo's own native WhatsApp
assistant. The contract is:

* **No webhook registered** → the native assistant handles the conversation as usual (unchanged
  behavior).
* **Webhook registered + native assistant OFF on that channel** → your bot owns the replies. This
  is the intended Path B setup.
* **Webhook registered + native assistant ON** → the customer gets **two** replies (one from the
  native assistant, one from your bot). Minimo does not auto-resolve this; it is treated as an
  operator misconfiguration.

<Warning>
  When you connect your own bot, **turn the native WhatsApp assistant off** on that channel in the dashboard. Otherwise
  every inbound message is answered twice.
</Warning>

Your bot is responsible for sending the reply — Minimo does not generate one on your behalf when a
webhook is in play. Receiving the envelope and producing a response is entirely your code; you
send it back with the [Send endpoint](/api-reference/whatsapp-transport/send).

## Current limits

* **One event.** Only `whatsapp.message.received` is forwarded today. Delivery-status events
  (sent / delivered / read) and template-approval updates are not pushed on this surface — poll
  [List WhatsApp Templates](/api-reference/messaging-channels/whatsapp/list-templates) for template
  status.
* **No media bytes in the webhook.** The envelope carries a `providerMediaId`, not the file —
  fetch the bytes from the provider yourself. Stored history (the Read API) does expose a
  fetchable `media.url`.
* **Session text needs an open window.** A `type: "text"` send only succeeds inside the 24-hour
  window opened by the customer's last message. Outside it, use an approved template.
* **Read API page size** is clamped to a maximum of **100**.
* **Webhook retries** stop after 5 attempts; a dead-letter is recorded in the delivery logs.
* **Events are at-least-once.** Dedup on `X-Minimo-Delivery` (the `wamid`).

## Common errors

| Situation | Response | Notes |
| - | - | - |
| Missing or malformed `Authorization` header | `401` — `Missing API key` | Header must be `Bearer mn-{CLIENT_ID}-{SECRET}`. |
| Valid key, but missing the required permission | `401` — `Insufficient permissions` | The webhook & read-API endpoints need the `WhatsApp` permission; send also accepts `Transactional`. |
| Both `template.id` and `template.name` (or neither) on a template send | `400` | Pass exactly one. |
| Unknown / foreign `sender` on send | `WHATSAPP_SENDER_NOT_FOUND` | Source values from [List Senders](/api-reference/messaging-channels/whatsapp/list-senders). |
| `chatId` not owned by your company (or nonexistent) | `404` — `Conversation not found` | Read API is strictly tenant-scoped. |
| Webhook `secret` shorter than 16 chars | `400` | Validation on create/update. |
| `events` containing anything but `whatsapp.message.received` | `400` | Only that event is registrable today. |

## Security checklist

* Issue a **WhatsApp-only** API key for your bot (least privilege), not a broad key.
* Always register webhooks with a **secret** and verify `X-Minimo-Signature` on every delivery.
* Verify against the **raw** request body, byte-for-byte — see
  [Verify the signature](/api-reference/whatsapp-transport/webhooks#verify-the-signature).
* Respond `2xx` fast and process asynchronously; a slow endpoint burns your retry budget.
* Never log or expose the webhook secret or the API key.

## Related

* [Overview](/api-reference/whatsapp-transport/overview)
* [Send a Message](/api-reference/whatsapp-transport/send)
* [Inbound Webhook](/api-reference/whatsapp-transport/webhooks)
* [Read API](/api-reference/whatsapp-transport/conversations)


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