Reply to Instagram DMs with images and carousel cards through an API
Send rich media in Instagram direct messages: text, images, videos, and product cards shown as a carousel. Here's what Meta's API allows and how to structure each message type.

On this page
You built a bot that receives Instagram DMs and replies automatically. Instagram's messaging API lets you send text, images, and videos, and also product cards displayed as a carousel. Here is what the API allows, how to structure a request with rich media, and the limits that apply.
The short answer
- Platforms: Instagram and Facebook Messenger only. TikTok, LinkedIn, and Pinterest have no DM API for third-party apps.
- Message types: Text (up to 1,000 characters), one image or video from a URL, or 1 to 10 product cards as a carousel.
- Window: Reply within 24 hours of the person's last message. After that, the conversation closes and replies are refused.
- Limits per plan: Free does not allow DM replies through the API. Pro Eksis gets 60 replies per hour per workspace. Super Eksis gets 600 per workspace. There is also a hard limit of 20 replies per hour into any one conversation.
- REST API base: https://api.eksis.io/v1/conversations/{conversationId}/messages
What Meta allows you to send
Instagram's Messaging API documentation lists four message types. The eksis REST endpoint wraps them:
| What you send | API field | Example |
|---|---|---|
| Text | text |
"Yes, we have size 10 in stock." |
| Image from URL | mediaUrl + mediaType: image |
https://shop.example/product.jpg |
| Video from URL | mediaUrl + mediaType: video |
https://shop.example/product.mp4 |
| Product cards (carousel) | cards |
Array of 1 to 10 cards, each with title, subtitle, image, button |
You can combine text with one attachment. Text and image go out as two separate messages, text first. An image or video alone, or a product card carousel alone, counts as one message.
The 24-hour reply window
Instagram and Facebook give businesses a 24-hour window to reply to a customer's message. The window starts when the person sends their first message in a new conversation, or resets when they send a new message after the window has closed.
Before replying, check the conversation's replyWindow field:
{
"state": "open",
"expiresAt": "2026-11-12T09:15:00.000Z"
}
statecan beopen,closing, orclosed.expiresAttells you when it expires.
If the window is closed, a reply is refused with the error code dm.window_closed. Hand the conversation to a person on your customer's team instead of retrying automatically.
Sending text
A text reply is the simplest. Up to 1,000 characters, plain text or with line breaks.
curl -X POST https://api.eksis.io/v1/conversations/CONVERSATION_ID/messages \
-H "Authorization: Bearer $EKSIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Yes, size 10 is in stock."}'
The response includes the message id and its status:
{
"data": {
"id": "MESSAGE_ID",
"messageIds": ["MESSAGE_ID"],
"conversationId": "CONVERSATION_ID",
"status": "sent"
}
}
Sending an image or video from a URL
To send an image or video without uploading it first, pass a URL:
curl -X POST https://api.eksis.io/v1/conversations/CONVERSATION_ID/messages \
-H "Authorization: Bearer $EKSIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Here it is in blue:",
"mediaUrl": "https://shop.example/product-blue.jpg",
"mediaType": "image"
}'
The URL must be https and publicly accessible. Send one attachment per reply: mediaId (a file already in your eksis media library), mediaUrl, or cards, not more than one.
When you include both text and media, they go out as two messages. The text message arrives first, then the image or video.
Sending product cards as a carousel
Product cards are shown as a swipeable carousel on Instagram and Facebook. Each card can have a title, subtitle, image, a link, and up to 3 buttons. This is useful for e-commerce bots that send product recommendations in reply to a customer's question.
curl -X POST https://api.eksis.io/v1/conversations/CONVERSATION_ID/messages \
-H "Authorization: Bearer $EKSIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Here are two shirts in size 10:",
"cards": [
{
"title": "Linen shirt",
"subtitle": "In stock, white",
"imageUrl": "https://shop.example/linen-white.jpg",
"url": "https://shop.example/linen",
"buttons": [
{
"label": "Buy now",
"url": "https://shop.example/cart?add=linen"
}
]
},
{
"title": "Oxford shirt",
"subtitle": "In stock, white",
"imageUrl": "https://shop.example/oxford-white.jpg",
"url": "https://shop.example/oxford",
"buttons": [
{
"label": "Buy now",
"url": "https://shop.example/cart?add=oxford"
}
]
}
]
}'
Card field rules
| Field | Required | Limit | Notes |
|---|---|---|---|
title |
Yes | 80 characters | Every card needs one |
subtitle |
No | 80 characters | Optional context |
imageUrl |
No | Must be HTTPS | Recommended for user experience |
url |
No | Must be HTTPS | Link when the card is tapped |
buttons |
No | Up to 3 buttons | Each button needs label and url, both required. Label up to 20 characters. |
Each card must have at least a title, and then at least one of: subtitle, image, link, or button. A card with just a title and nothing else is rejected with a validation error.
Cards only work on Instagram and Facebook. If you try to send a card carousel to another platform through the API, the request fails with the error code dm.cards_unsupported. Check the conversation's platform field first and send text or an image instead on other networks.
Response and error handling
A successful reply returns the message ids and status:
{
"data": {
"id": "MESSAGE_ID_2",
"messageIds": ["MESSAGE_ID_1", "MESSAGE_ID_2"],
"conversationId": "CONVERSATION_ID",
"status": "sent"
}
}
messageIds is a list because text and media are split into separate messages. The id field is always the last message id.
Common errors:
| Error code | Reason | Resolution |
|---|---|---|
dm.window_closed |
24-hour reply window has expired | Hand the conversation to a person on your team |
dm.cards_unsupported |
The conversation is not on Instagram or Facebook | Check conversation.platform and send text or an image instead |
dm.too_many_replies |
Your workspace exceeded its hourly quota | Wait before retrying. The response includes retry-after seconds. |
dm.conversation_too_many_replies |
More than 20 replies have been sent to this one conversation in the last hour | This prevents a bot from replying to itself repeatedly. Wait before retrying. |
424 |
The platform refused the reply | The platform thinks something is wrong with your message. Retrying will not help. Log it and ask the user. |
503 |
The platform is busy | You can retry after a delay. |
Quotas and limits
Two caps apply:
Per workspace, per hour
- Free: No API replies allowed. Use Pro Eksis or Super Eksis.
- Pro Eksis: 60 replies per hour.
- Super Eksis: 600 replies per hour.
Per conversation, per hour
- All plans: 20 replies per hour to any one conversation.
This second limit prevents a bot running in two channels from replying to each other in a loop. Both limits come with a retry-after header in the error response telling you how many seconds to wait.
Replies sent by your team from the eksis inbox do not count against these limits.
Example: A simple FAQ bot
Here is a flow for a bot that answers a customer's question:
- Receive a webhook when a DM arrives (Eksis Trigger, or set up webhooks directly).
- Parse the message text to identify the question.
- Look up the answer in your FAQ.
- Check if
replyWindow.stateisopen. - Send a text reply with the answer, or if you have related products, send a carousel of product cards.
- Log the reply for your team to review.
If the window is closing or closed, skip the reply and send the conversation to a person to answer instead.
Platforms and support
DM replies through the REST API work on Instagram and Facebook only. These are the platforms that:
- Accept DMs from customers.
- Expose their DM API to third-party apps.
- Allow the 24-hour reply window.
TikTok, LinkedIn, and Pinterest have no equivalent DM API for third-party applications.
Sources
- Meta Messaging API documentation (read November 11, 2026)
- eksis Direct messages guide (read November 11, 2026)
- eksis conversation endpoints (read November 11, 2026)
- How to auto-reply to Instagram comments
Frequently Asked Questions
Can I send a reply after the 24-hour window closes?
No. Instagram and Facebook enforce the 24-hour window. After that, the API refuses replies with the error dm.window_closed. You can still read the conversation, but you cannot reply. Hand it to a person on your team to answer manually.
Can I send an image I upload from my own server?
You can send a URL to an image anywhere public. Upload the image to your server or a CDN, get the HTTPS URL, and pass it in the reply. If you have an image file on your computer or in your app, convert it to a URL first.
Can I send multiple images in one message?
No. You can send one image, one video, or a carousel of product cards. For multiple images, send separate messages or add images to the product cards in a carousel.
How do I know if a customer's reply window is still open?
Call the get conversation endpoint before replying. The response includes replyWindow with state and expiresAt. If the state is closed, the window has expired.
Can my bot send a greeting without the customer writing first?
No. The DM API only allows replies. You cannot start a conversation. The customer must write first, and then you have 24 hours to respond.
Do replies count against my daily API quota?
Yes. Each reply counts as one request against your workspace's daily quota. The quota is separate from the hourly reply limit.


