Direct messages
Receive DMs on your customers' channels and reply with text, an image, a video, or up to 10 product cards.
Direct messages through the API start on Pro Eksis, like the rest of the REST API. On the MCP server, a Free workspace gets 402 with plan.feature_locked from the conversation tools. Reading needs a key with the viewer role and replying needs editor.
The flow is always the same: someone writes to a connected channel, eksis sends message.received, and your server replies to that conversation.
The incoming message
{
"id": "evt_...",
"type": "message.received",
"createdAt": "2026-11-10T09:15:02.000Z",
"workspaceId": "WORKSPACE_ID",
"data": {
"conversation": {
"id": "CONVERSATION_ID",
"channelId": "CHANNEL_ID",
"platform": "instagram",
"contact": { "name": "Someone", "username": "someone" }
},
"message": {
"id": "MESSAGE_ID",
"kind": "message",
"text": "Do you have the linen shirt in size M?",
"attachments": [],
"createdAt": "2026-11-10T09:15:00.000Z"
}
}
}conversation.channelIdtells you which customer the message is for.message.kindisstory_replywhen the person answered a story, andmessageotherwise.message.attachmentslists photos, videos, or files the person sent, each withtypeandurl. The links point at the platform and expire after a while, so download what you need to keep.contact.nameandcontact.usernamecan benullwhen the platform does not share them.
Event reference: Direct message received.
The reply window
Platforms let a business reply only after the person writes first, and only for a while after their last message. On Instagram that is 24 hours. You cannot start a conversation through eksis.
Each conversation carries replyWindow with state (open, closing, or closed) and expiresAt. A reply after the window closed is refused with 422 and dm.window_closed. Hand those conversations to a person on your customer's team instead of retrying.
Reply
Send the reply to POST /v1/conversations/{conversationId}/messages. A reply holds text, one attachment, or both:
| Field | What it sends |
|---|---|
text | Up to 1,000 characters. |
mediaId | An image or video from the workspace media library. |
mediaUrl + mediaType | An https link to an image or a video, without uploading it first. mediaType is image (the default) or video. |
cards | 1 to 10 cards shown as a swipeable carousel. Instagram and Facebook only. |
Send at most one of mediaId, mediaUrl, and cards in a reply. When a reply has text and an attachment, the text goes out first as its own message, then the attachment.
Text
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 M is in stock."}'An image from a link
{
"text": "Here it is in blue:",
"mediaUrl": "https://shop.example/img/linen-blue.jpg",
"mediaType": "image"
}Product cards
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 M:",
"cards": [
{
"title": "Linen shirt",
"subtitle": "In stock, size M",
"imageUrl": "https://shop.example/img/linen.jpg",
"url": "https://shop.example/p/linen",
"buttons": [{ "label": "Buy", "url": "https://shop.example/cart?add=linen" }]
},
{
"title": "Oxford shirt",
"subtitle": "In stock, size M",
"imageUrl": "https://shop.example/img/oxford.jpg",
"url": "https://shop.example/p/oxford"
}
]
}'| Card field | Rule |
|---|---|
title | Required, up to 80 characters. |
subtitle | Up to 80 characters. |
imageUrl | An https image link. |
url | An https link opened when the card itself is tapped. |
buttons | Up to 3, each with label (up to 20 characters) and an https url. |
Besides its title, every card needs at least one of subtitle, imageUrl, url, or buttons. Cards on any platform other than Instagram and Facebook are refused with 422 and dm.cards_unsupported, so check conversation.platform and send text or an image there instead.
The answer
{
"data": {
"id": "MESSAGE_ID_2",
"messageIds": ["MESSAGE_ID_1", "MESSAGE_ID_2"],
"conversationId": "CONVERSATION_ID",
"status": "sent"
}
}messageIds lists every message the reply became, in the order they were sent, and id is the last one. The reply is sent to the platform before the answer comes back: 424 means the platform refused it and retrying will not help, 503 means the platform is busy and you can try again later. Reference: Reply to a conversation.
Reply limits
Two caps apply to replies sent through the API and MCP:
- Per workspace, per hour: 60 on Pro Eksis, 600 on each Super Eksis workspace. Beyond it,
429withdm.too_many_replies. - Per conversation, per hour: 20 on every plan. Beyond it,
429withdm.conversation_too_many_replies. This stops a bot that answers itself, for example two channels running your bot that write to each other.
Both answers carry a retry-after header in seconds. Replies your customer's team sends from the eksis inbox do not count. See Limits and errors.
Read conversations
| Endpoint | Use |
|---|---|
| List conversations | Newest first, filtered by status, channels, or a search q. Each item has unreadCount, lastMessageAt, and replyWindow. |
| Read one conversation | The conversation with its 20 latest messages and its reply window. |
| List messages | The full history, page by page with cursor. |
| Mark a conversation read | Clears the unread count in eksis. Nothing changes on the platform. |
From an AI assistant
The MCP tool reply_to_conversation takes the same fields as the REST reply, including mediaUrl and cards.