add_dm_conversation

posts:writeuses credits

Track an X DM conversation and draft the next message in the user's voice. handle is the person's X handle. Pass messages so far, oldest first, as { from: 'them' | 'me', text } using the user's exact words (e.g. pasted from X); with no messages it drafts an opening message. notes is what the user knows about the person or wants from the chat.

Adding someone already tracked appends to their conversation. Drafting spends AI credits (draft: false skips it). Nothing is sent: show the user draftText and give them sendOnXUrl to send it on X.

Input

handlestring & stringrequired
messagesarray<object>
at most 20 items · default []
Item fields
- fromstringrequired
  one of them, me
- textstringrequired
  min length 1 · max length 4000
notesstring
max length 1000
draftboolean
default true
guidancestring
min length 1 · max length 500

Permission

Needs the posts:write scope: create drafts. It changes your workspace, so clients may ask you to confirm each call.

Example call

Your assistant sends this for you. It is shown so you can see the shape of a call, with placeholder values for the required fields.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_dm_conversation",
    "arguments": {
      "handle": "string"
    }
  }
}

Same action over the REST API

The tool runs POST /v1/orgs/{orgId}/dms as the signed-in user, with the same validation, approval rules and limits. See it in the X DMs API reference.