API reference

Conversations

A conversation is your DM thread with one lead on X, and its ID is the lead's ID. Read every message of a thread, list them in bulk, reply from your X account, and keep the Conversations board in order. New replies also arrive as the reply.received webhook.

Endpoints

GET/v1/conversations
GET/v1/conversations/:id
POST/v1/conversations/:conversation_id/mark_read
POST/v1/conversations/:conversation_id/mark_unread
POST/v1/conversations/:conversation_id/move
POST/v1/conversations/:conversation_id/pin
POST/v1/conversations/:conversation_id/unpin
DELETE/v1/conversations/:conversation_id
GET/v1/conversations/:conversation_id/messages
POST/v1/conversations/:conversation_id/messages
POST/v1/conversations/:conversation_id/messages/:message_id/reactions
DELETE/v1/conversations/:conversation_id/messages/:message_id/reactions
DELETE/v1/conversations/:conversation_id/messages/:message_id
GET/v1/conversations/:conversation_id/translation
PATCH/v1/conversations/:conversation_id/translation
POST/v1/conversations/:conversation_id/translate

The conversation object

Your DM thread with one lead on X. Its ID is the lead's ID.

Attributes

idstring
Unique identifier for the conversation, the same as lead_id.
objectstring
Always conversation.
lead_idstring
The lead you are talking to.
profileobject
The lead's X profile, as on the lead object.
unreadboolean
True when the lead's last message is not read yet.
last_message_atstring
When the last message was sent, ISO 8601.
messages_countinteger
Messages in the thread.
last_messageobject or null
The last message.
personaobject or null
The lead's persona.
columnobject or null
The column of your Conversations board the conversation sits in, like Interested. See Pipeline columns.
historystring
complete when messages is the whole thread. recent while Gemlead holds only the latest messages of a long thread, before it reads the rest from X once. Only with messages.
completerecent
messagesarray of objects
Every message of the thread, oldest first. When you retrieve one conversation, or list them with include_messages.

Conversation object

{
  "id": "msgOtJ8dvT",
  "object": "conversation",
  "lead_id": "msgOtJ8dvT",
  "profile": {
    "x_user_id": "1460283925",
    "username": "jane_builds",
    "name": "Jane Doe",
    "bio": "Runs a paid trading community. Daily setups, no hype.",
    "followers_count": 12400,
    "following_count": 380,
    "location": "Austin, TX",
    "website": "https://janedoe.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
    "verified": true,
    "url": "https://x.com/jane_builds"
  },
  "unread": true,
  "last_message_at": "2026-11-06T08:12:44.000Z",
  "messages_count": 4,
  "last_message": {
    "id": "1985321409876543210",
    "object": "message",
    "direction": "inbound",
    "text": "Yes, I want to charge for my Discord. How does it work?",
    "created_at": "2026-11-06T08:12:44.000Z",
    "media": [],
    "reactions": [],
    "encrypted": false,
    "reply_to_message_id": null
  },
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "column": {
    "id": "q7m2xk4p",
    "name": "Interested"
  }
}

List conversations

GET/v1/conversationsread scopeMCPlist_conversations

Returns your conversations, the most recent message first.

Query parameters

unreadboolean
true for unread conversations only.
personastring
Only conversations with leads of this persona ID.
include_messagesboolean
true to get each conversation with all its messages, oldest first, and history. Pages are heavier, so keep limit at 25 or less.
limitinteger
How many objects to return, from 1 to 100. Defaults to 25.
cursorstring
The next_cursor of the previous page, to get the page after it. See Pagination.

Returns

A list of conversation objects, with messages only when include_messages is true.

Errors

400parameter_invalid
A parameter has a value the API does not accept. param names it.

GET/v1/conversations

curl -G https://gemlead.ai/api/v1/conversations \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d unread=true

Response200

{
  "object": "list",
  "data": [
    {
      "id": "msgOtJ8dvT",
      "object": "conversation",
      "lead_id": "msgOtJ8dvT",
      "profile": {
        "x_user_id": "1460283925",
        "username": "jane_builds",
        "name": "Jane Doe",
        "bio": "Runs a paid trading community. Daily setups, no hype.",
        "followers_count": 12400,
        "following_count": 380,
        "location": "Austin, TX",
        "website": "https://janedoe.com",
        "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
        "verified": true,
        "url": "https://x.com/jane_builds"
      },
      "unread": true,
      "last_message_at": "2026-11-06T08:12:44.000Z",
      "messages_count": 4,
      "last_message": {
        "id": "1985321409876543210",
        "object": "message",
        "direction": "inbound",
        "text": "Yes, I want to charge for my Discord. How does it work?",
        "created_at": "2026-11-06T08:12:44.000Z",
        "media": [],
        "reactions": [],
        "encrypted": false,
        "reply_to_message_id": null
      },
      "persona": {
        "id": "lvWBPnytpS",
        "name": "Tipsters"
      },
      "column": {
        "id": "q7m2xk4p",
        "name": "Interested"
      }
    }
  ],
  "has_more": true,
  "next_cursor": "eyJzIjoiMjAyNi0xMS0wNVQxNDowMzo0MC4xMTdaIn0"
}

Retrieve a conversation

GET/v1/conversations/:idread scopeMCPget_conversation

Returns one conversation with all its messages, oldest first.

Path parameters

idstringRequired
The conversation's ID.

Returns

A conversation object with messages and history.

Errors

404resource_missing
No conversation with this ID on the key's account.

GET/v1/conversations/:id

curl https://gemlead.ai/api/v1/conversations/msgOtJ8dvT \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Response200

{
  "id": "msgOtJ8dvT",
  "object": "conversation",
  "lead_id": "msgOtJ8dvT",
  "profile": {
    "x_user_id": "1460283925",
    "username": "jane_builds",
    "name": "Jane Doe",
    "bio": "Runs a paid trading community. Daily setups, no hype.",
    "followers_count": 12400,
    "following_count": 380,
    "location": "Austin, TX",
    "website": "https://janedoe.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
    "verified": true,
    "url": "https://x.com/jane_builds"
  },
  "unread": true,
  "last_message_at": "2026-11-06T08:12:44.000Z",
  "messages_count": 4,
  "last_message": {
    "id": "1985321409876543210",
    "object": "message",
    "direction": "inbound",
    "text": "Yes, I want to charge for my Discord. How does it work?",
    "created_at": "2026-11-06T08:12:44.000Z",
    "media": [],
    "reactions": [],
    "encrypted": false,
    "reply_to_message_id": null
  },
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "column": {
    "id": "q7m2xk4p",
    "name": "Interested"
  },
  "history": "complete",
  "messages": [
    {
      "id": "1985321409876543210",
      "object": "message",
      "direction": "inbound",
      "text": "Yes, I want to charge for my Discord. How does it work?",
      "created_at": "2026-11-06T08:12:44.000Z",
      "media": [],
      "reactions": [],
      "encrypted": false,
      "reply_to_message_id": null
    },
    {
      "id": "1985329981234567890",
      "object": "message",
      "direction": "outbound",
      "text": "Happy to show you. Do you sell picks monthly or per event?",
      "created_at": "2026-11-06T08:20:03.000Z",
      "media": [],
      "reactions": [
        {
          "emoji": "👍",
          "direction": "inbound",
          "created_at": "2026-11-06T08:24:51.000Z"
        }
      ],
      "encrypted": false,
      "reply_to_message_id": "1985321409876543210"
    }
  ]
}

Mark as read

POST/v1/conversations/:conversation_id/mark_readwrite scopeMCPupdate_conversation

Marks the conversation as read in Gemlead, and on X with a read receipt.

Path parameters

conversation_idstringRequired
The conversation's ID.

Returns

The conversation object.

Errors

404resource_missing
No conversation with this ID on the key's account.
409x_session_expired
The X account's session expired. Reconnect it in the app, then try again.
502upstream_unavailable
X or a Gemlead service did not answer. Nothing changed, try again in a minute.

POST/v1/conversations/:conversation_id/mark_read

curl -X POST \
  https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/mark_read \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Response200

{
  "id": "msgOtJ8dvT",
  "object": "conversation",
  "lead_id": "msgOtJ8dvT",
  "profile": {
    "x_user_id": "1460283925",
    "username": "jane_builds",
    "name": "Jane Doe",
    "bio": "Runs a paid trading community. Daily setups, no hype.",
    "followers_count": 12400,
    "following_count": 380,
    "location": "Austin, TX",
    "website": "https://janedoe.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
    "verified": true,
    "url": "https://x.com/jane_builds"
  },
  "unread": false,
  "last_message_at": "2026-11-06T08:12:44.000Z",
  "messages_count": 4,
  "last_message": {
    "id": "1985321409876543210",
    "object": "message",
    "direction": "inbound",
    "text": "Yes, I want to charge for my Discord. How does it work?",
    "created_at": "2026-11-06T08:12:44.000Z",
    "media": [],
    "reactions": [],
    "encrypted": false,
    "reply_to_message_id": null
  },
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "column": {
    "id": "q7m2xk4p",
    "name": "Interested"
  }
}

Mark as unread

POST/v1/conversations/:conversation_id/mark_unreadwrite scopeMCPupdate_conversation

Marks the conversation as unread in Gemlead.

Path parameters

conversation_idstringRequired
The conversation's ID.

Returns

The conversation object.

Errors

404resource_missing
No conversation with this ID on the key's account.
409x_session_expired
The X account's session expired. Reconnect it in the app, then try again.
502upstream_unavailable
X or a Gemlead service did not answer. Nothing changed, try again in a minute.

POST/v1/conversations/:conversation_id/mark_unread

curl -X POST \
  https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/mark_unread \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Response200

{
  "id": "msgOtJ8dvT",
  "object": "conversation",
  "lead_id": "msgOtJ8dvT",
  "profile": {
    "x_user_id": "1460283925",
    "username": "jane_builds",
    "name": "Jane Doe",
    "bio": "Runs a paid trading community. Daily setups, no hype.",
    "followers_count": 12400,
    "following_count": 380,
    "location": "Austin, TX",
    "website": "https://janedoe.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
    "verified": true,
    "url": "https://x.com/jane_builds"
  },
  "unread": true,
  "last_message_at": "2026-11-06T08:12:44.000Z",
  "messages_count": 4,
  "last_message": {
    "id": "1985321409876543210",
    "object": "message",
    "direction": "inbound",
    "text": "Yes, I want to charge for my Discord. How does it work?",
    "created_at": "2026-11-06T08:12:44.000Z",
    "media": [],
    "reactions": [],
    "encrypted": false,
    "reply_to_message_id": null
  },
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "column": {
    "id": "q7m2xk4p",
    "name": "Interested"
  }
}

Move a conversation

POST/v1/conversations/:conversation_id/movewrite scopeMCPupdate_conversation

Moves the conversation to another column of the Conversations board.

Path parameters

conversation_idstringRequired
The conversation's ID.

Body parameters

column_idstringRequired
The column's ID, from List pipeline columns.

Returns

The conversation object.

Errors

404resource_missing
No conversation with this ID on the key's account.
404resource_missing
No column with this ID on the account's board.
400parameter_missing
A required parameter is missing. param names it.

POST/v1/conversations/:conversation_id/move

curl -X POST \
  https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/move \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "column_id": "z3c6lf8a"
  }'

Response200

{
  "id": "msgOtJ8dvT",
  "object": "conversation",
  "lead_id": "msgOtJ8dvT",
  "profile": {
    "x_user_id": "1460283925",
    "username": "jane_builds",
    "name": "Jane Doe",
    "bio": "Runs a paid trading community. Daily setups, no hype.",
    "followers_count": 12400,
    "following_count": 380,
    "location": "Austin, TX",
    "website": "https://janedoe.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
    "verified": true,
    "url": "https://x.com/jane_builds"
  },
  "unread": true,
  "last_message_at": "2026-11-06T08:12:44.000Z",
  "messages_count": 4,
  "last_message": {
    "id": "1985321409876543210",
    "object": "message",
    "direction": "inbound",
    "text": "Yes, I want to charge for my Discord. How does it work?",
    "created_at": "2026-11-06T08:12:44.000Z",
    "media": [],
    "reactions": [],
    "encrypted": false,
    "reply_to_message_id": null
  },
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "column": {
    "id": "z3c6lf8a",
    "name": "Call booked"
  }
}

Pin a conversation

POST/v1/conversations/:conversation_id/pinwrite scopeMCPupdate_conversation

Pins the conversation in your X inbox.

Path parameters

conversation_idstringRequired
The conversation's ID.

Returns

The conversation object.

Errors

404resource_missing
No conversation with this ID on the key's account.
409x_session_expired
The X account's session expired. Reconnect it in the app, then try again.
502upstream_unavailable
X or a Gemlead service did not answer. Nothing changed, try again in a minute.

POST/v1/conversations/:conversation_id/pin

curl -X POST \
  https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/pin \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Response200

{
  "id": "msgOtJ8dvT",
  "object": "conversation",
  "lead_id": "msgOtJ8dvT",
  "profile": {
    "x_user_id": "1460283925",
    "username": "jane_builds",
    "name": "Jane Doe",
    "bio": "Runs a paid trading community. Daily setups, no hype.",
    "followers_count": 12400,
    "following_count": 380,
    "location": "Austin, TX",
    "website": "https://janedoe.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
    "verified": true,
    "url": "https://x.com/jane_builds"
  },
  "unread": true,
  "last_message_at": "2026-11-06T08:12:44.000Z",
  "messages_count": 4,
  "last_message": {
    "id": "1985321409876543210",
    "object": "message",
    "direction": "inbound",
    "text": "Yes, I want to charge for my Discord. How does it work?",
    "created_at": "2026-11-06T08:12:44.000Z",
    "media": [],
    "reactions": [],
    "encrypted": false,
    "reply_to_message_id": null
  },
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "column": {
    "id": "q7m2xk4p",
    "name": "Interested"
  }
}

Unpin a conversation

POST/v1/conversations/:conversation_id/unpinwrite scopeMCPupdate_conversation

Unpins the conversation in your X inbox.

Path parameters

conversation_idstringRequired
The conversation's ID.

Returns

The conversation object.

Errors

404resource_missing
No conversation with this ID on the key's account.
409x_session_expired
The X account's session expired. Reconnect it in the app, then try again.
502upstream_unavailable
X or a Gemlead service did not answer. Nothing changed, try again in a minute.

POST/v1/conversations/:conversation_id/unpin

curl -X POST \
  https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/unpin \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Response200

{
  "id": "msgOtJ8dvT",
  "object": "conversation",
  "lead_id": "msgOtJ8dvT",
  "profile": {
    "x_user_id": "1460283925",
    "username": "jane_builds",
    "name": "Jane Doe",
    "bio": "Runs a paid trading community. Daily setups, no hype.",
    "followers_count": 12400,
    "following_count": 380,
    "location": "Austin, TX",
    "website": "https://janedoe.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
    "verified": true,
    "url": "https://x.com/jane_builds"
  },
  "unread": true,
  "last_message_at": "2026-11-06T08:12:44.000Z",
  "messages_count": 4,
  "last_message": {
    "id": "1985321409876543210",
    "object": "message",
    "direction": "inbound",
    "text": "Yes, I want to charge for my Discord. How does it work?",
    "created_at": "2026-11-06T08:12:44.000Z",
    "media": [],
    "reactions": [],
    "encrypted": false,
    "reply_to_message_id": null
  },
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "column": {
    "id": "q7m2xk4p",
    "name": "Interested"
  }
}

Delete a conversation

DELETE/v1/conversations/:conversation_idwrite scopeMCPdelete_conversation

Deletes the conversation in Gemlead and in your X inbox. Its lead stops in every campaign. This cannot be undone.

Path parameters

conversation_idstringRequired
The conversation's ID.

Returns

An object with the conversation's id and deleted set to true.

Errors

404resource_missing
No conversation with this ID on the key's account.
409x_session_expired
The X account's session expired. Reconnect it in the app, then try again.
502upstream_unavailable
X or a Gemlead service did not answer. Nothing changed, try again in a minute.

DELETE/v1/conversations/:conversation_id

curl -X DELETE \
  https://gemlead.ai/api/v1/conversations/msgOtJ8dvT \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Response200

{
  "id": "msgOtJ8dvT",
  "object": "conversation",
  "deleted": true
}

The message object

One DM in a conversation, sent by you or by the lead.

Attributes

idstring
The message's ID on X.
objectstring
Always message.
directionstring
inbound when the lead wrote it, outbound when you did.
inboundoutbound
textstring
The message's text.
created_atstring
When it was sent, ISO 8601.
mediaarray of objects
What is attached to the message, each with its type and url. Images on X come through a Gemlead link.
reactionsarray of objects
The emoji reactions on the message, oldest first, one per person and emoji.
encryptedboolean
true for an X Chat message Gemlead cannot read yet. Its text and media stay empty until the X Chat passcode unlocks it.
reply_to_message_idstring or null
The ID of the message it replies to, null when it replies to none.

Message object

{
  "id": "1985321409876543210",
  "object": "message",
  "direction": "inbound",
  "text": "Yes, I want to charge for my Discord. How does it work?",
  "created_at": "2026-11-06T08:12:44.000Z",
  "media": [],
  "reactions": [],
  "encrypted": false,
  "reply_to_message_id": null
}

List messages

GET/v1/conversations/:conversation_id/messagesread scopeMCPlist_messages

Returns the whole history of a conversation from X, newest first, page by page.

Path parameters

conversation_idstringRequired
The conversation's ID.

Query parameters

limitinteger
How many messages to return, from 1 to 50. Defaults to 25.
cursorstring
The next_cursor of the previous page, for older messages.

Returns

A list of message objects.

Errors

404resource_missing
No conversation with this ID on the key's account.
400parameter_invalid
A parameter has a value the API does not accept. param names it.
409x_session_expired
The X account's session expired. Reconnect it in the app, then try again.
502upstream_unavailable
X or a Gemlead service did not answer. Nothing changed, try again in a minute.

GET/v1/conversations/:conversation_id/messages

curl -G \
  https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/messages \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d limit=50

Response200

{
  "object": "list",
  "data": [
    {
      "id": "1985329981234567890",
      "object": "message",
      "direction": "outbound",
      "text": "Happy to show you. Do you sell picks monthly or per event?",
      "created_at": "2026-11-06T08:20:03.000Z",
      "media": [],
      "reactions": [
        {
          "emoji": "👍",
          "direction": "inbound",
          "created_at": "2026-11-06T08:24:51.000Z"
        }
      ],
      "encrypted": false,
      "reply_to_message_id": "1985321409876543210"
    },
    {
      "id": "1985321409876543210",
      "object": "message",
      "direction": "inbound",
      "text": "Yes, I want to charge for my Discord. How does it work?",
      "created_at": "2026-11-06T08:12:44.000Z",
      "media": [],
      "reactions": [],
      "encrypted": false,
      "reply_to_message_id": null
    }
  ],
  "has_more": true,
  "next_cursor": "eyJzIjoiMjAyNi0xMS0wNVQxNDowMzo0MC4xMTdaIn0"
}

Send a message

POST/v1/conversations/:conversation_id/messageswrite scopeMCPsend_message

Sends a DM to the lead from your X account, right away. Send text, a file, or both. The recipient always comes from the conversation.

Path parameters

conversation_idstringRequired
The conversation's ID.

Body parameters

textstring
The message, up to 10 000 characters. Required without media.
mediaobject
A file to send with the message. Give its url, or its data with its mime_type. Gemlead reads its type from the file itself. Images go up to 5 MB and GIFs up to 15 MB. Videos and voice notes go as large as X takes them, send a url for those too big for a request body.
reply_to_message_idstring
Reply to this message, one of the conversation's last 20. A reply with media needs an X Chat conversation.

Returns

The sent message, with its conversation_id, reply_to_message_id and transport, x_chat or classic.

Errors

404resource_missing
No conversation with this ID on the key's account.
400parameter_missing
A required parameter is missing. param names it.
400parameter_invalid
A parameter has a value the API does not accept. param names it.
400media_kind_unsupported
The conversation cannot take this kind of file, like a voice note without X Chat.
429dm_paused
X limits the account's DMs for now. Retry-After says when they start again.
429dm_rate_limited
More than 10 DMs in the minute.
429dm_daily_limit
300 DMs today in UTC, or X's own daily quota for the account.
400recipient_not_messageable
X refused, the lead closed their DMs or blocked the account.
409conversation_unavailable
The conversation has no X user to write to yet.
409x_session_expired
The X account's session expired. Reconnect it in the app, then try again.
502upstream_unavailable
X or a Gemlead service did not answer. Nothing changed, try again in a minute.

POST/v1/conversations/:conversation_id/messages

curl -X POST \
  https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/messages \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Happy to show you. Do you sell picks monthly or per event?"
  }'

Response200

{
  "id": "1985329981234567890",
  "object": "message",
  "conversation_id": "msgOtJ8dvT",
  "direction": "outbound",
  "text": "Happy to show you. Do you sell picks monthly or per event?",
  "created_at": "2026-11-06T08:20:03.000Z",
  "media": [],
  "reactions": [],
  "encrypted": false,
  "reply_to_message_id": null,
  "transport": "x_chat"
}

Add a reaction

POST/v1/conversations/:conversation_id/messages/:message_id/reactionswrite scopeMCPreact_to_message

Reacts to a message with an emoji, from your X account.

Path parameters

conversation_idstringRequired
The conversation's ID.
message_idstringRequired
The message's ID, one of the conversation's last 20.

Body parameters

emojistringRequired
The emoji, like ❤️ or 👍.

Returns

An object with the conversation_id, the message_id and the emoji.

Errors

404resource_missing
No message with this ID on the key's account.
400parameter_missing
A required parameter is missing. param names it.
409x_session_expired
The X account's session expired. Reconnect it in the app, then try again.
502upstream_unavailable
X or a Gemlead service did not answer. Nothing changed, try again in a minute.

POST/v1/conversations/:conversation_id/messages/:message_id/reactions

curl -X POST \
  https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/messages/1985321409876543210/reactions \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emoji": "👍"
  }'

Response200

{
  "object": "reaction",
  "conversation_id": "msgOtJ8dvT",
  "message_id": "1985321409876543210",
  "emoji": "👍"
}

Remove a reaction

DELETE/v1/conversations/:conversation_id/messages/:message_id/reactionswrite scopeMCPreact_to_message

Removes your reaction from a message.

Path parameters

conversation_idstringRequired
The conversation's ID.
message_idstringRequired
The message's ID, one of the conversation's last 20.

Query parameters

emojistringRequired
The emoji to remove.

Returns

The reaction with deleted set to true.

Errors

404resource_missing
No message with this ID on the key's account.
400parameter_missing
A required parameter is missing. param names it.
409x_session_expired
The X account's session expired. Reconnect it in the app, then try again.
502upstream_unavailable
X or a Gemlead service did not answer. Nothing changed, try again in a minute.

DELETE/v1/conversations/:conversation_id/messages/:message_id/reactions

curl -X DELETE \
  "https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/messages/1985321409876543210/reactions?emoji=%F0%9F%91%8D" \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Response200

{
  "object": "reaction",
  "conversation_id": "msgOtJ8dvT",
  "message_id": "1985321409876543210",
  "emoji": "👍",
  "deleted": true
}

Delete a message

DELETE/v1/conversations/:conversation_id/messages/:message_idwrite scopeMCPdelete_message

Deletes a message for you, or for both sides when it is yours and the conversation is on X Chat.

Path parameters

conversation_idstringRequired
The conversation's ID.
message_idstringRequired
The message's ID, one of the conversation's last 20.

Query parameters

for_everyoneboolean
true deletes it for both sides, your own messages on X Chat only. Default false.

Returns

An object with the message's id, its conversation_id, deleted set to true and for_everyone.

Errors

404resource_missing
No message with this ID on the key's account.
400parameter_invalid
A parameter has a value the API does not accept. param names it.
409x_session_expired
The X account's session expired. Reconnect it in the app, then try again.
502upstream_unavailable
X or a Gemlead service did not answer. Nothing changed, try again in a minute.

DELETE/v1/conversations/:conversation_id/messages/:message_id

curl -X DELETE \
  "https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/messages/1985329981234567890?for_everyone=true" \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Response200

{
  "id": "1985329981234567890",
  "object": "message",
  "conversation_id": "msgOtJ8dvT",
  "deleted": true,
  "for_everyone": true
}

The conversation translation object

Whether a conversation's messages are translated, and into which language.

Attributes

objectstring
Always conversation_translation.
conversation_idstring
The conversation's ID.
enabledboolean
Whether its messages are translated as they come.
decidedboolean
Whether someone turned it on or off, rather than Gemlead's default.
source_languagestring or null
The lead's language, once detected.
languagestring or null
The language messages are translated into.
shownboolean
Whether the app shows the messages translated.

Conversation translation object

{
  "object": "conversation_translation",
  "conversation_id": "msgOtJ8dvT",
  "enabled": true,
  "decided": true,
  "source_language": "es",
  "language": "en",
  "shown": true
}

Retrieve translation settings

GET/v1/conversations/:conversation_id/translationread scopeMCPupdate_conversation_translation

Returns whether the conversation is translated, and into which language.

Path parameters

conversation_idstringRequired
The conversation's ID.

Returns

A conversation translation object.

Errors

404resource_missing
No conversation with this ID on the key's account.

GET/v1/conversations/:conversation_id/translation

curl \
  https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/translation \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Response200

{
  "object": "conversation_translation",
  "conversation_id": "msgOtJ8dvT",
  "enabled": true,
  "decided": true,
  "source_language": "es",
  "language": "en",
  "shown": true
}

Update translation settings

PATCH/v1/conversations/:conversation_id/translationwrite scopeMCPupdate_conversation_translation

Turns the conversation's translation on or off, and whether the app shows the messages translated.

Path parameters

conversation_idstringRequired
The conversation's ID.

Body parameters

enabledboolean
Translate the messages as they come, yours and theirs.
shownboolean
Show the messages translated in the app. Needs enabled.
languagestring
The language to translate into. Default your language in Gemlead, else English.
enfresitderuptnljazhkoartrhiidplukvithsv

Returns

The updated conversation translation object.

Errors

404resource_missing
No conversation with this ID on the key's account.
400parameter_invalid
A parameter has a value the API does not accept. param names it.
400parameter_unknown
The body has a field this endpoint does not take.

PATCH/v1/conversations/:conversation_id/translation

curl -X PATCH \
  https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/translation \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "shown": true,
    "language": "en"
  }'

Response200

{
  "object": "conversation_translation",
  "conversation_id": "msgOtJ8dvT",
  "enabled": true,
  "decided": true,
  "source_language": "es",
  "language": "en",
  "shown": true
}

Translate messages

POST/v1/conversations/:conversation_id/translatewrite scopeMCPtranslate_messages

Translates the conversation's recent messages. With translation off, translate one message at a time.

Path parameters

conversation_idstringRequired
The conversation's ID.

Body parameters

message_idsarray of strings
The messages to translate, among the last 20. Default all of them, with translation on.
languagestring
The language to translate into. Default your language in Gemlead, else English.
enfresitderuptnljazhkoartrhiidplukvithsv

Returns

An object with the conversation_id, the language, and in data each message's message_id, text and translation.

Errors

404resource_missing
No conversation with this ID on the key's account.
400parameter_invalid
A parameter has a value the API does not accept. param names it.
400translation_off
Translation is off and you asked for more than one message.
502upstream_unavailable
X or a Gemlead service did not answer. Nothing changed, try again in a minute.

POST/v1/conversations/:conversation_id/translate

curl -X POST \
  https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/translate \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message_ids": ["1985321409876543210"],
    "language": "en"
  }'

Response200

{
  "object": "message_translations",
  "conversation_id": "msgOtJ8dvT",
  "language": "en",
  "data": [
    {
      "message_id": "1985321409876543210",
      "text": "Sí, quiero cobrar por mi Discord. Cómo funciona?",
      "translation": "Yes, I want to charge for my Discord. How does it work?"
    }
  ]
}