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

# Send a Message

> Send a session text, an approved template, or media (image/video/audio/document/sticker) over WhatsApp

## Endpoint

```
POST https://api.minimo.it/public/v1/templates/whatsapp/send
```

**Permission:** `WhatsApp` or `Transactional` (either is accepted).

This single endpoint sends several kinds of WhatsApp message, selected by the `type` field:

* `type: "text"` — a free-form **session message**, only valid inside the 24-hour
  customer-initiated window. This is what a bot uses to reply to an inbound message.
* `type: "template"` — a Meta-approved **template**, valid any time (subject to template
  category rules).
* `type: "image" | "video" | "audio" | "document" | "sticker"` — a free-form **media
  message**. Like a session text, media is only deliverable inside the 24-hour window.

<Info>
  The company is resolved from your API key. The body carries a deprecated `companyId` field that is **ignored** — never
  send it.
</Info>

## Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `recipient` | string | yes | Destination phone number in E.164 (e.g. `393391234567`). |
| `type` | `"text"` \| `"template"` \| `"image"` \| `"video"` \| `"audio"` \| `"document"` \| `"sticker"` | yes | Which kind of message to send. |
| `text` | string | when `type: "text"` | The free-form session message body. |
| `template` | object | when `type: "template"` | The template reference and parameters (see below). |
| `media` | object | when `type` is a media kind | The media file to send (see below). Must not be combined with `text` or `template`. |
| `sender` | string | no | Which connected number to send **from**, for multi-number companies. Phone number or Meta `phone_number_id`. Omit to use the preferred number. |
| `contactSource` | string | no | Label applied if this send creates a brand-new contact (default `WhatsApp`). Existing contacts are never modified. Max 64 chars. |

### `template` object

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | one of `name` / `id` | Meta template name. The only way to send a template authored on the Meta/360dialog console. |
| `id` | string | one of `name` / `id` | Stable Minimo template family id (from [List Templates](/api-reference/messaging-channels/whatsapp/list-templates)). Survives template version changes. |
| `languageCode` | string | no | Approved language, e.g. `it`, `en_US`. Omit to let Minimo resolve it (costs a lookup). |
| `components` | array | no | Components filling the template placeholders. |

<Warning>Pass **exactly one** of `template.id` or `template.name`. Sending both, or neither, is a `400`.</Warning>

### `media` object

| Field | Type | Required | Description |
| - | - | - | - |
| `link` | string | one of `link` / `providerMediaId` | Publicly reachable URL of the file. The provider downloads it at send time, so it must be HTTPS-reachable with the correct Content-Type. |
| `providerMediaId` | string | one of `link` / `providerMediaId` | Id of a media already uploaded to the sending number on the provider. Sent by id — nothing is fetched. Must belong to the sending number. |
| `caption` | string | no | Caption shown under the media. Only for `image`, `video` and `document` (rejected on `audio` and `sticker`). Max 1024 chars. |
| `filename` | string | no | Original filename shown to the recipient. Only meaningful for `document`. Max 240 chars. |

<Warning>Pass **exactly one** of `media.link` or `media.providerMediaId`. Sending both, or neither, is a `400`.</Warning>

## Send a session text

Use this to reply to an inbound message from your bot. It only succeeds inside the 24-hour window
opened by the customer's last message — which is exactly the case when you are answering a reply.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.minimo.it/public/v1/templates/whatsapp/send \
    -H "Authorization: Bearer mn-abc123-xyz789" \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{
      "recipient": "393391234567",
      "type": "text",
      "text": "Thanks for your message! A contract draft is on its way."
    }'
  ```

  ```javascript Node theme={null}
  const res = await fetch('https://api.minimo.it/public/v1/templates/whatsapp/send', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer mn-abc123-xyz789',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      recipient: '393391234567',
      type: 'text',
      text: 'Thanks for your message! A contract draft is on its way.',
    }),
  });
  const data = await res.json(); // { success: true }
  ```

  ```python Python theme={null}
  import requests

  requests.post(
      "https://api.minimo.it/public/v1/templates/whatsapp/send",
      headers={"Authorization": "Bearer mn-abc123-xyz789"},
      json={
          "recipient": "393391234567",
          "type": "text",
          "text": "Thanks for your message! A contract draft is on its way.",
      },
  )
  ```
</CodeGroup>

## Send a template

Templates are required to **start** a conversation or to message outside the 24-hour window.

<CodeGroup>
  ```bash By name theme={null}
  curl https://api.minimo.it/public/v1/templates/whatsapp/send \
    -H "Authorization: Bearer mn-abc123-xyz789" \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{
      "recipient": "393391234567",
      "type": "template",
      "template": {
        "name": "order_confirmation",
        "languageCode": "it",
        "components": [
          {
            "type": "BODY",
            "parameters": [
              { "type": "text", "text": "Jane Doe" },
              { "type": "text", "text": "ORD-12345" }
            ]
          }
        ]
      }
    }'
  ```

  ```bash By Minimo template id theme={null}
  curl https://api.minimo.it/public/v1/templates/whatsapp/send \
    -H "Authorization: Bearer mn-abc123-xyz789" \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{
      "recipient": "393391234567",
      "type": "template",
      "template": {
        "id": "K3J9XQ2",
        "components": [
          {
            "type": "BODY",
            "parameters": [
              { "type": "text", "text": "Jane Doe" },
              { "type": "text", "text": "ORD-12345" }
            ]
          }
        ]
      }
    }'
  ```
</CodeGroup>

<Note>
  Template authoring, categories (`UTILITY` / `AUTHENTICATION` / `MARKETING`), the 24-hour window, named vs. positional
  variables and the full component reference are covered in detail on [Send WhatsApp
  Template](/api-reference/messaging-channels/whatsapp/send-template). This page documents the same endpoint from the
  "connect your bot" angle.
</Note>

## Send media

Set `type` to the media kind and pass a `media` object. The file is addressed **exactly one way** —
`media.link` (a public URL the provider fetches) or `media.providerMediaId` (a media already
uploaded to the sending number). A `caption` is supported on `image` / `video` / `document`; a
`filename` only on `document`; a `sticker` takes neither. Like a session text, media is only
deliverable inside the 24-hour customer window.

<CodeGroup>
  ```bash cURL theme={null}
  # Image by public URL, with a caption
  curl https://api.minimo.it/public/v1/templates/whatsapp/send \
    -H "Authorization: Bearer mn-abc123-xyz789" \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{
      "recipient": "393391234567",
      "type": "image",
      "media": {
        "link": "https://cdn.example.com/welcome.jpg",
        "caption": "Welcome aboard!"
      }
    }'

  # Document by a pre-uploaded provider media id
  curl https://api.minimo.it/public/v1/templates/whatsapp/send \
    -H "Authorization: Bearer mn-abc123-xyz789" \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{
      "recipient": "393391234567",
      "type": "document",
      "media": {
        "providerMediaId": "1234567890123456",
        "filename": "invoice.pdf"
      }
    }'

  # Sticker (no caption, no filename)
  curl https://api.minimo.it/public/v1/templates/whatsapp/send \
    -H "Authorization: Bearer mn-abc123-xyz789" \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{
      "recipient": "393391234567",
      "type": "sticker",
      "media": { "link": "https://cdn.example.com/sticker.webp" }
    }'
  ```

  ```javascript Node theme={null}
  // Image by public URL, with a caption
  await fetch('https://api.minimo.it/public/v1/templates/whatsapp/send', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer mn-abc123-xyz789',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      recipient: '393391234567',
      type: 'image',
      media: { link: 'https://cdn.example.com/welcome.jpg', caption: 'Welcome aboard!' },
    }),
  });

  // Document by a pre-uploaded provider media id
  await fetch('https://api.minimo.it/public/v1/templates/whatsapp/send', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer mn-abc123-xyz789',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      recipient: '393391234567',
      type: 'document',
      media: { providerMediaId: '1234567890123456', filename: 'invoice.pdf' },
    }),
  });

  // Sticker (no caption, no filename)
  await fetch('https://api.minimo.it/public/v1/templates/whatsapp/send', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer mn-abc123-xyz789',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      recipient: '393391234567',
      type: 'sticker',
      media: { link: 'https://cdn.example.com/sticker.webp' },
    }),
  });
  ```

  ```python Python theme={null}
  import requests

  URL = "https://api.minimo.it/public/v1/templates/whatsapp/send"
  HEADERS = {"Authorization": "Bearer mn-abc123-xyz789"}

  # Image by public URL, with a caption
  requests.post(URL, headers=HEADERS, json={
      "recipient": "393391234567",
      "type": "image",
      "media": {"link": "https://cdn.example.com/welcome.jpg", "caption": "Welcome aboard!"},
  })

  # Document by a pre-uploaded provider media id
  requests.post(URL, headers=HEADERS, json={
      "recipient": "393391234567",
      "type": "document",
      "media": {"providerMediaId": "1234567890123456", "filename": "invoice.pdf"},
  })

  # Sticker (no caption, no filename)
  requests.post(URL, headers=HEADERS, json={
      "recipient": "393391234567",
      "type": "sticker",
      "media": {"link": "https://cdn.example.com/sticker.webp"},
  })
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "success": true
}
```

A `success: true` means Minimo accepted the message and dispatched it to the provider. Delivery
status (sent / delivered / read) is tracked in the Minimo inbox; it is not returned inline here.

## Choosing the sender (multi-number)

If the company has more than one connected number, set `sender` to the number you want to send
**from** — either the phone number (any formatting) or the Meta `phone_number_id`:

```json theme={null}
{
  "recipient": "393391234567",
  "type": "text",
  "sender": "+393517654321",
  "text": "Hi! How can I help?"
}
```

An unknown or foreign `sender` returns `WHATSAPP_SENDER_NOT_FOUND`. Source valid values from
[List WhatsApp Senders](/api-reference/messaging-channels/whatsapp/list-senders).

## Related

* [Inbound Webhook](/api-reference/whatsapp-transport/webhooks) — receive the messages you reply to
* [List WhatsApp Senders](/api-reference/messaging-channels/whatsapp/list-senders)
* [List WhatsApp Templates](/api-reference/messaging-channels/whatsapp/list-templates)


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