Instagram Messaging API | OmniChannels.ai Docs

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#

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

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#

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

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

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#

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#

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: the same pattern for Facebook Pages.
Webhooks: receive DMs and delivery statuses.
Errors and limits: 502 errors carry Meta's error details.

Ready to send your first message?

Request test credentials. An engineer sets up your account, and test sends go to your own verified numbers.

Request test access