# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand. overlay: 1.0.0 info: title: API Evangelist conversational phrasing for X API v2 Direct Messages API version: 1.0.0 extends: openapi/x-direct-messages-api-openapi.yml actions: - target: $.info update: x-apievangelist-phrasing: method: generated generated: '2026-09-26' generator: build-phrasing.py label: Generated by API Evangelist operations: 9 - target: $.paths['/2/dm_conversations'].post update: x-apievangelist-phrasing: intent: Start a group DM conversation effect: write questions: - How do I start a new group Direct Message with several people? - Does creating a DM conversation support one-to-one chats or only groups? instructions: - text: Start a {conversation_type} DM with {participant_ids} and send {message}. slots: conversation_type: requestBody.conversation_type participant_ids: requestBody.participant_ids message: requestBody.message - text: Create a new {conversation_type} conversation including {participant_ids}, opening with {message}. slots: conversation_type: requestBody.conversation_type participant_ids: requestBody.participant_ids message: requestBody.message method: generated generated: '2026-09-26' - target: $.paths['/2/dm_conversations/media/{dm_id}/{media_id}/{resource_id}'].get update: x-apievangelist-phrasing: intent: Download media from a legacy DM effect: read questions: - Can I download a photo or video attached to an older Direct Message? - Do I have to be in the conversation to fetch DM attachment bytes? instructions: - text: Download media {media_id} resource {resource_id} from DM {dm_id}. slots: media_id: path.media_id resource_id: path.resource_id dm_id: path.dm_id - text: Save the attachment {resource_id} of media {media_id} in legacy DM event {dm_id}. slots: resource_id: path.resource_id media_id: path.media_id dm_id: path.dm_id method: generated generated: '2026-09-26' - target: $.paths['/2/dm_conversations/with/{participant_id}/dm_events'].get update: x-apievangelist-phrasing: intent: Get my DM history with one person effect: read questions: - What have I and a specific user said to each other in DMs? - Can I pull my one-to-one DM history with someone using just their user ID? instructions: - text: Show my DM history with user {participant_id}. slots: participant_id: path.participant_id - text: Get the last {max_results} DM events between me and {participant_id}. slots: max_results: query.max_results participant_id: path.participant_id method: generated generated: '2026-09-26' - target: $.paths['/2/dm_conversations/with/{participant_id}/messages'].post update: x-apievangelist-phrasing: intent: Send a DM to a user effect: write questions: - How do I send a Direct Message to someone by their user ID? - Can I attach media when DMing a user directly? instructions: - text: DM user {participant_id} saying {text}. slots: participant_id: path.participant_id text: requestBody.text - text: Send {participant_id} a direct message with attachment {attachments}. slots: participant_id: path.participant_id attachments: requestBody.attachments method: generated generated: '2026-09-26' - target: $.paths['/2/dm_conversations/{dm_conversation_id}/messages'].post update: x-apievangelist-phrasing: intent: Send a message into an existing DM conversation effect: write questions: - Can I post a message into a group DM conversation I'm already part of? - What's the call to reply inside an existing DM thread by its conversation ID? instructions: - text: Send {text} to DM conversation {dm_conversation_id}. slots: text: requestBody.text dm_conversation_id: path.dm_conversation_id - text: Post attachment {attachments} into conversation {dm_conversation_id}. slots: attachments: requestBody.attachments dm_conversation_id: path.dm_conversation_id method: generated generated: '2026-09-26' - target: $.paths['/2/dm_conversations/{id}/dm_events'].get update: x-apievangelist-phrasing: intent: Read the events in a DM conversation effect: read questions: - Which messages are in a particular group DM conversation? - Can I filter a conversation's DM events by event type? instructions: - text: Show the DM events in conversation {id}. slots: id: path.id - text: Get {event_types} events from DM conversation {id}. slots: event_types: query.event_types id: path.id method: generated generated: '2026-09-26' - target: $.paths['/2/dm_events'].get update: x-apievangelist-phrasing: intent: List my recent DM events across conversations effect: read questions: - What are my most recent Direct Messages across all conversations? - Can I list only join or leave events in my DMs? instructions: - text: List my recent DM events across all conversations. - text: Show my latest {max_results} DM events of type {event_types}. slots: max_results: query.max_results event_types: query.event_types method: generated generated: '2026-09-26' - target: $.paths['/2/dm_events/{event_id}'].get update: x-apievangelist-phrasing: intent: Get a single DM event effect: read questions: - Can I look up one specific Direct Message event by its ID? - What details come back for a single DM event? instructions: - text: Get DM event {event_id}. slots: event_id: path.event_id - text: Show the direct message with event ID {event_id}. slots: event_id: path.event_id method: generated generated: '2026-09-26' - target: $.paths['/2/dm_events/{event_id}'].delete update: x-apievangelist-phrasing: intent: Delete a DM I sent effect: destructive questions: - Can I delete a Direct Message I sent? - What happens if I try to delete a DM event I don't own? instructions: - text: Delete DM event {event_id}. slots: event_id: path.event_id - text: Remove my direct message {event_id}. slots: event_id: path.event_id method: generated generated: '2026-09-26'