The API reference moved here from eksis.io/developers.

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

message.received
{
  "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.channelId tells you which customer the message is for.
  • message.kind is story_reply when the person answered a story, and message otherwise.
  • message.attachments lists photos, videos, or files the person sent, each with type and url. The links point at the platform and expire after a while, so download what you need to keep.
  • contact.name and contact.username can be null when 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:

FieldWhat it sends
textUp to 1,000 characters.
mediaIdAn image or video from the workspace media library.
mediaUrl + mediaTypeAn https link to an image or a video, without uploading it first. mediaType is image (the default) or video.
cards1 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."}'
{
  "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 fieldRule
titleRequired, up to 80 characters.
subtitleUp to 80 characters.
imageUrlAn https image link.
urlAn https link opened when the card itself is tapped.
buttonsUp 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, 429 with dm.too_many_replies.
  • Per conversation, per hour: 20 on every plan. Beyond it, 429 with dm.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

EndpointUse
List conversationsNewest first, filtered by status, channels, or a search q. Each item has unreadCount, lastMessageAt, and replyWindow.
Read one conversationThe conversation with its 20 latest messages and its reply window.
List messagesThe full history, page by page with cursor.
Mark a conversation readClears 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.

On this page