> ## 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.

# Connect Your Bot — Overview

> Use Minimo as a WhatsApp transport layer: receive inbound messages on your backend and reply with your own bot or AI

## What this is

Minimo runs the WhatsApp Business plumbing — the Meta Cloud API / 360dialog / Twilio
connection, the number, the inbox, templates and delivery — and lets **your** backend own the
conversation logic. You receive every inbound message on a signed webhook, run whatever bot or
AI you want, and send the reply back through one API.

In other words: **Minimo is the transport, you are the brain.** This is the path an external
product (for example a legal-AI like IUS) takes to put its own assistant on a WhatsApp number
without building a WhatsApp integration from scratch.

<Info>
  This surface assumes you already have a WhatsApp number connected to your company in Minimo (via
  [Channels](https://app.minimo.it/channels)). Onboarding a number is a separate, dashboard-driven flow and is not part
  of this API.
</Info>

## The flow

<Steps>
  <Step title="A customer messages your WhatsApp number">
    Meta (or 360dialog / Twilio) delivers the message to Minimo.
  </Step>

  <Step title="Minimo forwards a normalized event to your webhook">
    Minimo pushes a stable, provider-agnostic JSON envelope for the `whatsapp.message.received` event to the URL you
    registered — HMAC-signed, retried, and idempotent per message. See [Inbound
    Webhook](/api-reference/whatsapp-transport/webhooks).
  </Step>

  <Step title="Your backend decides the reply">
    Your bot / AI reads the envelope and produces a response. Minimo does not run any logic here — this is entirely your
    code.
  </Step>

  <Step title="You send the reply through the Minimo API">
    Call the [Send endpoint](/api-reference/whatsapp-transport/send) with either a free-form session text (inside the
    24-hour window) or an approved template. Minimo delivers it over the right provider and records it in the inbox.
  </Step>

  <Step title="(Optional) Read history on demand">
    Use the [Read API](/api-reference/whatsapp-transport/conversations) to backfill conversation history — handy on bot
    restarts, for a custom chat UI, or for debugging.
  </Step>
</Steps>

## Authentication

Every request authenticates with a Minimo **API key** in the `Authorization` header:

```bash theme={null}
Authorization: Bearer mn-{CLIENT_ID}-{SECRET}
```

Create the key in [Account Settings → API Keys](https://app.minimo.it/account) and grant it the
**WhatsApp** permission.

<Note>
  The **WhatsApp** permission (`whatsapp`) is a least-privilege scope for exactly this transport
  surface: sending WhatsApp messages, managing inbound webhook registrations, and reading
  WhatsApp conversation history. Issue a WhatsApp-only key for your bot instead of a broad key.

  The [Send endpoint](/api-reference/whatsapp-transport/send) also accepts a legacy
  `Transactional` key for backward compatibility, but the webhook and read-API endpoints require
  the `WhatsApp` permission.
</Note>

The company (tenant) is always resolved **from the API key** — you never pass a company id in the
body or headers. A key can only ever read and write its own company's data.

## Base URL

All endpoints on this surface are served from the new API host:

```
https://api.minimo.it
```

| Endpoint | Method | Purpose |
| - | - | - |
| `/public/v1/templates/whatsapp/send` | `POST` | Send a session text or a template |
| `/public/v1/webhooks/registrations` | `GET` `POST` `PUT` `DELETE` | Manage inbound webhook registrations |
| `/public/v1/whatsapp/conversations` | `GET` | List WhatsApp conversations |
| `/public/v1/whatsapp/conversations/:chatId/messages` | `GET` | List a conversation's messages |

## Coexistence with the native assistant

Forwarding is **additive**: registering a webhook never disables Minimo's own native WhatsApp
assistant. If you connect your own bot, turn the native assistant **off** on that channel so you
don't get two replies to one message. See
[Notes & Limits](/api-reference/whatsapp-transport/notes#double-handling-with-the-native-assistant)
for the full contract.

## Next steps

<CardGroup cols={2}>
  <Card title="Send messages" icon="paper-plane" href="/api-reference/whatsapp-transport/send">
    Reply with a session text or an approved template.
  </Card>

  <Card title="Receive inbound" icon="webhook" href="/api-reference/whatsapp-transport/webhooks">
    Register a webhook, read the envelope, verify the signature.
  </Card>

  <Card title="Read history" icon="clock-rotate-left" href="/api-reference/whatsapp-transport/conversations">
    Page through conversations and messages.
  </Card>

  <Card title="Notes & limits" icon="circle-info" href="/api-reference/whatsapp-transport/notes">
    Double-handling, current limits, common errors.
  </Card>
</CardGroup>


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