API Evangelist conversational phrasing for X API v2 Direct Messages API

# 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'