---
title: "Instagram Messaging API"
description: "Connect an Instagram professional account with OAuth and reply to Instagram DMs by API: text, media, quick replies, generic templates and reactions."
canonical: "https://omnichannels.ai/developers/instagram/"
language: "en"
updated: "2026-10-10"
publisher: "BroadNet Technologies"
brand: "OmniChannels.ai"
section: "Messaging channels"
---

# Instagram Messaging API

Canonical: https://omnichannels.ai/developers/instagram/
Language: en
Publisher: OmniChannels.ai by BroadNet Technologies

The Instagram API sends direct messages from your Instagram professional account to people who have messaged it. Connect the account once through OAuth, then send through `POST /instagram/message/sendbulk`.

## Connect your Instagram account

1. Call `POST /instagram/oauth/generate-link` with your token to get an encrypted onboarding link.
2. Open the link as an admin of the account and approve Meta's permissions.
3. DMs then arrive in the Omni Inbox and on your webhook, and you can reply through the API.

```bash title="cURL"
curl -X POST https://api.broadnet.me/instagram/oauth/generate-link \
  -H "Authorization: Bearer $BROADNET_TOKEN"
```

## Messaging rules

Instagram messaging is conversational. You can message people who have messaged your account, using the Instagram-scoped recipient ID you receive with their message (not a username or phone number).

- Replies are allowed within Meta's standard 24-hour window after the person's last message.
- A human agent can follow up later where Meta permits it, by adding `tag=HUMAN_AGENT`.
- Cold outreach to people who have not messaged you is not possible through the API.

Check Meta's Instagram messaging policy for the current rules.

## Send a message

```bash title="cURL"
curl -X POST https://api.broadnet.me/instagram/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=17841400000000000 \
  -F campaignName=dm-support \
  -F messageType=TEXT \
  -F "content=Thanks for reaching out. Your size is back in stock."
```

```js title="Node.js"
const form = new FormData();
form.append("batchId", "0");
form.append("destinationNo", "17841400000000000"); // Instagram-scoped recipient ID
form.append("campaignName", "dm-support");
form.append("messageType", "TEXT");
form.append("content", "Thanks for reaching out. Your size is back in stock.");

const res = await fetch("https://api.broadnet.me/instagram/message/sendbulk", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BROADNET_TOKEN}` },
  body: form,
});
console.log(res.status, await res.text());
```

```python title="Python"
import os
import requests

fields = {
    "batchId": "0",
    "destinationNo": "17841400000000000",  # Instagram-scoped recipient ID
    "campaignName": "dm-support",
    "messageType": "TEXT",
    "content": "Thanks for reaching out. Your size is back in stock.",
}
r = requests.post(
    "https://api.broadnet.me/instagram/message/sendbulk",
    headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
    files={k: (None, v) for k, v in fields.items()},
    timeout=30,
)
print(r.status_code, r.text)
```

## Request fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `destinationNo` | string | Yes | One or more recipient IDs, comma-separated. |
| `messageType` | string | Yes | See the table below. |
| `content` | string | `TEXT`, `QUICK_REPLY` | Message text. |
| `mediaUrl` | string | Media types | HTTPS URL of the media (for `MEDIA_SHARE`, the ID of your published post). |
| `file` | file | Media types | Upload the media instead of linking it. |
| `caption` | string | No | Caption for media. |
| `quickReplyJson` | string (JSON) | `QUICK_REPLY` | Quick reply options. |
| `templateJson` | string (JSON) | `GENERIC_TEMPLATE` | One card, or several for a carousel. |
| `templatePayloadJson` | string (JSON) | `PRODUCT_TEMPLATE` | Product template payload. |
| `replyToMid` | string | No | Message ID to quote-reply to. |
| `replyToMessageId`, `emoji` | string | `REACTION` | The message to react to, and the emoji. |
| `tag` | string | No | `HUMAN_AGENT` for a human follow-up outside the standard window. |
| `batchId` | string | No | `0` starts a new batch. |
| `campaignName`, `allowDuplicate`, `delay` | string | No | Reporting label, de-duplication and throttle. |
| `scheduled`, `scheduleTime`, `gmt` | string | No | Schedule the send. |

| `messageType` | What it sends |
| --- | --- |
| `TEXT` | Plain text. |
| `IMAGE`, `VIDEO`, `AUDIO`, `FILE`, `STICKER` | Media by URL or upload. |
| `LIKE_HEART` | The heart sticker. |
| `QUICK_REPLY` | Text with quick reply options, including email and phone number prompts. |
| `GENERIC_TEMPLATE` | Card or carousel with buttons. |
| `PRODUCT_TEMPLATE` | A catalog product. |
| `MEDIA_SHARE` | Shares one of your published posts. |
| `REACTION` | Reacts to a message. |

### Quick replies

```bash title="cURL"
curl -X POST https://api.broadnet.me/instagram/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=17841400000000000 \
  -F messageType=QUICK_REPLY \
  -F "content=What can we help with?" \
  -F 'quickReplyJson=[{"content_type":"text","title":"Order status","payload":"ORDER"},{"content_type":"text","title":"Returns","payload":"RETURNS"},{"content_type":"user_email"}]'
```

### Card with buttons

```bash title="cURL"
curl -X POST https://api.broadnet.me/instagram/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=17841400000000000 \
  -F messageType=GENERIC_TEMPLATE \
  -F 'templateJson=[{"title":"Linen shirt","subtitle":"Back in stock","imageUrl":"https://cdn.example.com/omnidemo/shirt.jpg","buttons":[{"type":"web_url","title":"View","url":"https://example.com/shirt"},{"type":"postback","title":"Reserve","payload":"RESERVE_SHIRT"}]}]'
```

## Read receipts and typing

| Method | Path | Description |
| --- | --- | --- |
| POST | `/instagram/message/read` | Mark the conversation as read (`recipientId`). |
| POST | `/instagram/message/typing` | Show a typing indicator. |

## Saved templates and batches

| Method | Path | Description |
| --- | --- | --- |
| POST | `/instagram/template` | Save a text template. |
| GET | `/instagram/template/list` | List saved templates. |
| POST | `/instagram/template/send?templateName=…&destinationNo=…` | Send a saved template by name. |
| POST | `/instagram/message/all-bulk` | List batches with filters. |
| GET | `/instagram/message/edit?batch_Id=…` | Batch details. |
| GET | `/instagram/message/pause?batch_Id=…` | Pause a batch. |
| GET | `/instagram/message/resume?batch_Id=…` | Resume a batch. |
| DELETE | `/instagram/message/abort?batch_Id=…` | Abort a batch. |

## Next steps

- [Messenger](/developers/messenger/): the same pattern for Facebook Pages.
- [Webhooks](/developers/webhooks/): receive DMs and delivery statuses.
- [Errors and limits](/developers/errors-and-limits/): `502` errors carry Meta's error details.