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

# Send WhatsApp Message

> Send a WhatsApp message — text, template, media, interactive, location, or contacts.

## Request Headers

**Authorization** `string` *required*

Bearer token. Format: `Bearer nc_live_your_api_key`

**Idempotency-Key** `string`

Unique key to prevent duplicate sends. Responses are cached for 24 hours. See [Idempotency](https://docs.notvis.com/idempotency.md).

## Request Body

**to** `string | string[]` *required*

Recipient WhatsApp number(s) in E.164 format (e.g., `+919876543210`). Accepts a single string or an array of up to 1,000 numbers for batch sending.

**type** `string` *required*

Message type. One of: `text`, `template`, `image`, `document`, `video`, `audio`, `sticker`, `location`, `contacts`, `interactive`.

### Text Message

**text** `object`

Required when `type` is `text`.

**Properties**

**body** `string` *required*

Message text. Maximum 4,096 characters.

**preview\_url** `boolean` (default: false)

Enable link preview for URLs in the message body.

### Template Message

**template** `object`

Required when `type` is `template`.

**Properties**

**name** `string` *required*

Template name as approved by Meta.

**language** `string` *required*

Template language code (e.g., `en_US`, `hi`).

**components** `array`

Template components with dynamic parameters.

**Component properties**

**type** `string` *required*

Component type: `header`, `body`, or `button`.

**sub\_type** `string`

Button sub-type: `url` or `quick_reply`. Required for button components.

**index** `integer`

Button index (0-based). Required for button components.

**parameters** `array` *required*

Array of parameter objects with `type` (`text`, `image`, `document`, `video`) and corresponding value.

### Media Messages

**image** `object`

Required when `type` is `image`. Supports JPEG/PNG, max 5MB.

**Properties**

**link** `string`

Public HTTPS URL of the image. Either `link` or `id` is required.

**id** `string`

Pre-uploaded media ID from Meta. Either `link` or `id` is required.

**caption** `string`

Optional caption text.

**document** `object`

Required when `type` is `document`. Supports PDF, DOC, XLS, etc. Max 100MB.

**Properties**

**link** `string`

Either `link` or `id` required. Must be HTTPS.

**id** `string`

Pre-uploaded media ID.

**filename** `string`

Display filename (e.g., `invoice.pdf`).

**caption** `string`

Optional caption.

**video** `object`

Required when `type` is `video`. MP4/3GPP, max 16MB.

**Properties**

**link** `string`

Either `link` or `id` required. Must be HTTPS.

**id** `string`

Pre-uploaded media ID.

**caption** `string`

Optional caption.

**audio** `object`

Required when `type` is `audio`. AAC/MP4/OGG, max 16MB.

**Properties**

**link** `string`

Either `link` or `id` required. Must be HTTPS.

**id** `string`

Pre-uploaded media ID.

**sticker** `object`

Required when `type` is `sticker`. WebP format, 512x512px.

**Properties**

**link** `string`

Either `link` or `id` required. Must be HTTPS.

**id** `string`

Pre-uploaded media ID.

### Location Message

**location** `object`

Required when `type` is `location`.

**Properties**

**latitude** `number` *required*

Latitude (-90 to 90).

**longitude** `number` *required*

Longitude (-180 to 180).

**name** `string`

Location name (e.g., `Godrej Reserve`).

**address** `string`

Full address.

### Contacts Message

**contacts** `array`

Required when `type` is `contacts`. Array of contact cards.

**Contact properties**

**name** `object` *required*

`formatted_name` is required. Optional: `first_name`, `last_name`, `prefix`, `suffix`.

**phones** `array`

Array of `{ phone, type }` objects.

**emails** `array`

Array of `{ email, type }` objects.

**addresses** `array`

Array of address objects with `street`, `city`, `state`, `zip`, `country`.

**org** `object`

Organization: `{ company, department, title }`.

### Interactive Message

**interactive** `object`

Required when `type` is `interactive`. Supports buttons, lists, and CTA URLs.

**Properties**

**type** `string` *required*

Interactive type: `button`, `list`, or `cta_url`.

**header** `object`

Optional header with `type` (`text`, `image`, `video`, `document`) and corresponding content.

**body** `object` *required*

Message body: `{ text: "..." }`.

**footer** `object`

Optional footer: `{ text: "..." }`.

**action** `object` *required*

Action content depends on the interactive type. See examples below.

### Optional Fields

**context** `object`

Reply to a specific message. `{ message_id: "wamid.xxx" }`

**schedule\_at** `string`

ISO 8601 timestamp for scheduled delivery. Must be in the future, max 7 days ahead.

**callback\_url** `string`

HTTPS URL to receive delivery status webhooks (`sent`, `delivered`, `read`, `failed`).

**tags** `string[]`

Tags for categorization. Maximum 10 tags.

**metadata** `object`

Custom key-value pairs passed through to webhooks.

## Response

### Single recipient (202 Accepted)

**message\_id** `string`

Unique identifier for the queued message.

**status** `string`

`"queued"` or `"scheduled"`.

**to** `string`

Normalized E.164 phone number.

**created\_at** `string`

ISO 8601 timestamp.

### Batch (multiple recipients)

**messages** `array`

Array of message objects, one per recipient.

```bash cURL (Text) theme={null}
curl -X POST https://api.notvis.com/v1/whatsapp/messages \
  -H "Authorization: Bearer nc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "type": "text",
    "text": {
      "body": "Hello! Your order #1234 has been shipped.",
      "preview_url": false
    },
    "callback_url": "https://example.com/webhooks/wa",
    "metadata": { "order_id": "1234" }
  }'
```

```bash cURL (Template) theme={null}
curl -X POST https://api.notvis.com/v1/whatsapp/messages \
  -H "Authorization: Bearer nc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "language": "en_US",
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "Rahul" },
            { "type": "text", "text": "#1234" }
          ]
        }
      ]
    }
  }'
```

```bash cURL (Interactive Buttons) theme={null}
curl -X POST https://api.notvis.com/v1/whatsapp/messages \
  -H "Authorization: Bearer nc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "type": "interactive",
    "interactive": {
      "type": "button",
      "body": { "text": "Would you like to schedule a site visit?" },
      "action": {
        "buttons": [
          { "id": "yes", "title": "Yes, book now" },
          { "id": "no", "title": "Not now" },
          { "id": "info", "title": "More info" }
        ]
      }
    }
  }'
```

```bash cURL (Interactive List) theme={null}
curl -X POST https://api.notvis.com/v1/whatsapp/messages \
  -H "Authorization: Bearer nc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "type": "interactive",
    "interactive": {
      "type": "list",
      "body": { "text": "Choose a property to explore:" },
      "action": {
        "button": "View Properties",
        "sections": [
          {
            "title": "Mumbai",
            "rows": [
              { "id": "prop_1", "title": "Godrej Reserve", "description": "Kandivali East, from 1.2 Cr" },
              { "id": "prop_2", "title": "Lodha Palava", "description": "Dombivli, from 65L" }
            ]
          }
        ]
      }
    }
  }'
```

```bash cURL (Location) theme={null}
curl -X POST https://api.notvis.com/v1/whatsapp/messages \
  -H "Authorization: Bearer nc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "type": "location",
    "location": {
      "latitude": 19.2094,
      "longitude": 72.8567,
      "name": "Godrej Reserve Sales Gallery",
      "address": "Kandivali East, Mumbai 400101"
    }
  }'
```

```bash cURL (Image) theme={null}
curl -X POST https://api.notvis.com/v1/whatsapp/messages \
  -H "Authorization: Bearer nc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "type": "image",
    "image": {
      "link": "https://cdn.example.com/brochure.jpg",
      "caption": "Project brochure"
    }
  }'
```

```bash cURL (Batch) theme={null}
curl -X POST https://api.notvis.com/v1/whatsapp/messages \
  -H "Authorization: Bearer nc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["+919876543210", "+919876543211", "+919876543212"],
    "type": "template",
    "template": {
      "name": "hello_world",
      "language": "en_US"
    }
  }'
```

```bash cURL (Reply-to) theme={null}
curl -X POST https://api.notvis.com/v1/whatsapp/messages \
  -H "Authorization: Bearer nc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "type": "text",
    "text": { "body": "Thanks for your interest! Here are the details..." },
    "context": { "message_id": "wamid.HBgMOTE4MDEwNzE5MzEw..." }
  }'
```

```javascript Node.js theme={null}
const response = await fetch('https://api.notvis.com/v1/whatsapp/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer nc_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '+919876543210',
    type: 'template',
    template: {
      name: 'order_confirmation',
      language: 'en_US',
      components: [{
        type: 'body',
        parameters: [
          { type: 'text', text: 'Rahul' },
          { type: 'text', text: '#1234' },
        ],
      }],
    },
    callback_url: 'https://example.com/webhooks/wa',
  }),
});

const data = await response.json();
console.log(data.message_id);
```

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

response = requests.post(
    'https://api.notvis.com/v1/whatsapp/messages',
    headers={'Authorization': 'Bearer nc_live_your_api_key'},
    json={
        'to': '+919876543210',
        'type': 'text',
        'text': {'body': 'Hello from Notvis!'},
        'callback_url': 'https://example.com/webhooks/wa',
    },
)

print(response.json()['message_id'])
```

```json 202 Single Recipient theme={null}
{
  "message_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "queued",
  "to": "+919876543210",
  "created_at": "2026-10-31T10:00:00Z"
}
```

```json 202 Batch theme={null}
{
  "messages": [
    {
      "message_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "queued",
      "to": "+919876543210",
      "created_at": "2026-10-31T10:00:00Z"
    },
    {
      "message_id": "a23bc45d-67ef-8901-b234-5c6d7e8f9012",
      "status": "queued",
      "to": "+919876543211",
      "created_at": "2026-10-31T10:00:00Z"
    }
  ]
}
```

```json 202 Scheduled theme={null}
{
  "message_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "scheduled",
  "to": "+919876543210",
  "created_at": "2026-10-31T10:00:00Z"
}
```

```json 400 Validation Error theme={null}
{
  "code": 400,
  "message": "validation failed",
  "details": {
    "to": "invalid phone number: 12345 (expected E.164 format like +919876543210)",
    "type": "must be one of: text, template, image, document, video, audio, sticker, location, contacts, interactive"
  }
}
```


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