# 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 Chat API
  version: 1.0.0
extends: openapi/x-chat-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: 16
- target: $.paths['/2/chat/conversations'].get
  update:
    x-apievangelist-phrasing:
      intent: List my Chat inbox conversations
      effect: read
      questions:
      - Which encrypted Chat conversations are in my inbox?
      - Can I page through all of my X Chat conversations?
      instructions:
      - text: List the conversations in my Chat inbox.
      - text: Show my {max_results} most recent Chat conversations.
        slots:
          max_results: query.max_results
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/chat/conversations/group'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an encrypted Chat group
      effect: write
      questions:
      - How do I finish creating an encrypted Chat group after initializing it?
      - Can I set a group name, description and admins when creating a Chat group?
      instructions:
      - text: Create Chat group {conversation_id} with members {group_members}, key version {conversation_key_version} and participant keys {conversation_participant_keys}.
        slots:
          conversation_id: requestBody.conversation_id
          group_members: requestBody.group_members
          conversation_key_version: requestBody.conversation_key_version
          conversation_participant_keys: requestBody.conversation_participant_keys
      - text: Set up group {conversation_id} named {group_name} for {group_members} using keys {conversation_participant_keys} v{conversation_key_version}.
        slots:
          conversation_id: requestBody.conversation_id
          group_name: requestBody.group_name
          group_members: requestBody.group_members
          conversation_participant_keys: requestBody.conversation_participant_keys
          conversation_key_version: requestBody.conversation_key_version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/chat/conversations/group/initialize'].post
  update:
    x-apievangelist-phrasing:
      intent: Reserve an ID for a new Chat group
      effect: write
      questions:
      - What's the first step to create a new Chat group conversation?
      - How do I get a conversation ID before configuring a group chat?
      instructions:
      - text: Initialize a new Chat group and give me its conversation ID.
      - text: Reserve a fresh group conversation ID for XChat.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/chat/conversations/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Chat conversation's details
      effect: read
      questions:
      - How can I see whether a Chat conversation is muted and who its admins are?
      - What metadata does a single Chat conversation expose?
      instructions:
      - text: Show the details of Chat conversation {id}.
        slots:
          id: path.id
      - text: Get Chat conversation {id} with its members expanded via {expansions}.
        slots:
          id: path.id
          expansions: query.expansions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/chat/conversations/{id}/events'].get
  update:
    x-apievangelist-phrasing:
      intent: Read messages in a Chat conversation
      effect: read
      questions:
      - Where can I get the message history of a Chat conversation?
      - Can I see key change events alongside messages in an XChat thread?
      instructions:
      - text: Get the messages and key events in Chat conversation {id}.
        slots:
          id: path.id
      - text: Load the last {max_results} events from my Chat with {id}.
        slots:
          max_results: query.max_results
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/chat/conversations/{id}/keys'].post
  update:
    x-apievangelist-phrasing:
      intent: Initialize or rotate a Chat conversation key
      effect: write
      questions:
      - What do I need to call before sending the first message in a new 1:1 encrypted chat?
      - How do I rotate the encryption key on an existing Chat conversation?
      instructions:
      - text: Set up encryption keys for Chat {id} at version {conversation_key_version} with {conversation_participant_keys}.
        slots:
          id: path.id
          conversation_key_version: requestBody.conversation_key_version
          conversation_participant_keys: requestBody.conversation_participant_keys
      - text: Rotate conversation {id}'s key to version {conversation_key_version} using participant keys {conversation_participant_keys}.
        slots:
          id: path.id
          conversation_key_version: requestBody.conversation_key_version
          conversation_participant_keys: requestBody.conversation_participant_keys
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/chat/conversations/{id}/members'].post
  update:
    x-apievangelist-phrasing:
      intent: Add members to a Chat group
      effect: write
      questions:
      - Can I invite more people into an existing encrypted group chat?
      - Does adding members to a Chat group rotate the conversation key?
      instructions:
      - text: Add users {user_ids} to Chat group {id}.
        slots:
          user_ids: requestBody.user_ids
          id: path.id
      - text: Bring {user_ids} into group conversation {id} with new key version {conversation_key_version}.
        slots:
          user_ids: requestBody.user_ids
          id: path.id
          conversation_key_version: requestBody.conversation_key_version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/chat/conversations/{id}/messages'].post
  update:
    x-apievangelist-phrasing:
      intent: Send an encrypted Chat message
      effect: write
      questions:
      - How do I send an encrypted message into an XChat conversation?
      - Can I send a 1:1 Chat message using just the recipient's user ID?
      instructions:
      - text: Send encrypted message {message_id} with payload {encoded_message_create_event} to Chat {id}.
        slots:
          message_id: requestBody.message_id
          encoded_message_create_event: requestBody.encoded_message_create_event
          id: path.id
      - text: Deliver the encoded Chat message {encoded_message_create_event} as {message_id} to recipient {id}.
        slots:
          encoded_message_create_event: requestBody.encoded_message_create_event
          message_id: requestBody.message_id
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/chat/conversations/{id}/messages/delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete messages from a Chat conversation
      effect: destructive
      questions:
      - How do I unsend Chat messages for everyone in the conversation?
      - Can I delete chat messages only from my own view?
      instructions:
      - text: Delete messages {sequence_ids} in Chat {id} using {delete_message_action} signed with {action_signatures}.
        slots:
          sequence_ids: requestBody.sequence_ids
          id: path.id
          delete_message_action: requestBody.delete_message_action
          action_signatures: requestBody.action_signatures
      - text: Remove Chat messages {sequence_ids} from conversation {id} for everyone ({delete_message_action}, signatures {action_signatures}).
        slots:
          sequence_ids: requestBody.sequence_ids
          id: path.id
          delete_message_action: requestBody.delete_message_action
          action_signatures: requestBody.action_signatures
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/chat/conversations/{id}/read'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark a Chat conversation as read
      effect: write
      questions:
      - Is it possible to mark an XChat conversation read up to a certain message?
      - Can I clear the unread state on a Chat thread through the API?
      instructions:
      - text: Mark Chat {id} as read up to sequence {seen_until_sequence_id}.
        slots:
          id: path.id
          seen_until_sequence_id: requestBody.seen_until_sequence_id
      - text: Set conversation {id} read through message {seen_until_sequence_id}.
        slots:
          id: path.id
          seen_until_sequence_id: requestBody.seen_until_sequence_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/chat/conversations/{id}/typing'].post
  update:
    x-apievangelist-phrasing:
      intent: Show a typing indicator in Chat
      effect: write
      questions:
      - Can I show the other person that I'm typing in a Chat conversation?
      - Can a bot send a typing indicator in XChat?
      instructions:
      - text: Send a typing indicator to Chat {id}.
        slots:
          id: path.id
      - text: Show that I'm typing in conversation {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/chat/media/upload/initialize'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a Chat media upload
      effect: write
      questions:
      - How do I begin uploading an attachment to an XChat conversation?
      - What size information do I need to start a Chat media upload?
      instructions:
      - text: Start a Chat media upload of {total_bytes} bytes for conversation {conversation_id}.
        slots:
          total_bytes: requestBody.total_bytes
          conversation_id: requestBody.conversation_id
      - text: Open an XChat upload session in {conversation_id} for a {total_bytes}-byte file.
        slots:
          conversation_id: requestBody.conversation_id
          total_bytes: requestBody.total_bytes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/chat/media/upload/{id}/append'].post
  update:
    x-apievangelist-phrasing:
      intent: Append a chunk to a Chat media upload
      effect: write
      questions:
      - What call sends the next chunk of an XChat attachment upload?
      - Which segment index should each Chat media chunk carry?
      instructions:
      - text: Append segment {segment_index} of {media} to Chat upload {id} in {conversation_id} with hash key {media_hash_key}.
        slots:
          segment_index: requestBody.segment_index
          media: requestBody.media
          id: path.id
          conversation_id: requestBody.conversation_id
          media_hash_key: requestBody.media_hash_key
      - text: Upload chunk {segment_index} ({media}) to XChat session {id}, conversation {conversation_id}, key {media_hash_key}.
        slots:
          segment_index: requestBody.segment_index
          media: requestBody.media
          id: path.id
          conversation_id: requestBody.conversation_id
          media_hash_key: requestBody.media_hash_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/chat/media/upload/{id}/finalize'].post
  update:
    x-apievangelist-phrasing:
      intent: Finish a Chat media upload
      effect: write
      questions:
      - How do I complete an XChat attachment upload after sending all chunks?
      - Can I set an expiry on Chat media when finalizing the upload?
      instructions:
      - text: Finalize Chat upload {id} in {conversation_id} with {num_parts} parts and hash key {media_hash_key}.
        slots:
          id: path.id
          conversation_id: requestBody.conversation_id
          num_parts: requestBody.num_parts
          media_hash_key: requestBody.media_hash_key
      - text: Close XChat upload {id} ({num_parts} parts, key {media_hash_key}) in {conversation_id} with TTL {ttl_msec}.
        slots:
          id: path.id
          num_parts: requestBody.num_parts
          media_hash_key: requestBody.media_hash_key
          conversation_id: requestBody.conversation_id
          ttl_msec: requestBody.ttl_msec
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/chat/media/{id}/{media_hash_key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Download encrypted Chat media
      effect: read
      questions:
      - How do I download an attachment someone sent me in XChat?
      - Does Chat media come back as raw encrypted bytes?
      instructions:
      - text: Download Chat media {media_hash_key} from conversation {id}.
        slots:
          media_hash_key: path.media_hash_key
          id: path.id
      - text: Fetch the encrypted attachment bytes for {media_hash_key} in Chat {id}.
        slots:
          media_hash_key: path.media_hash_key
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/public_keys'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a public key for Chat encryption
      effect: write
      questions:
      - How do I register my public key so others can send me encrypted Chat messages?
      - Can I publish a new version of my Chat encryption key?
      instructions:
      - text: Register public key {public_key} version {version} for user {id}.
        slots:
          public_key: requestBody.public_key
          version: requestBody.version
          id: path.id
      - text: Add Chat encryption key {public_key} as version {version} on {id}.
        slots:
          public_key: requestBody.public_key
          version: requestBody.version
          id: path.id
      method: generated
      generated: '2026-09-26'