# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Slack Conversations API
  version: 1.0.0
extends: openapi/slack-conversations-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: 18
- target: $.paths['/conversations.create'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new channel
      effect: write
      questions:
      - How do I create a new Slack channel from code?
      - Can I make the new channel private instead of public?
      instructions:
      - text: Create a public channel named {name}.
        slots:
          name: requestBody.name
      - text: Create channel {name} with private set to {is_private}.
        slots:
          name: requestBody.name
          is_private: requestBody.is_private
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations.history'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a channel's message history
      effect: read
      questions:
      - What messages were posted in a channel over the last few days?
      - Can I fetch only messages between two timestamps?
      instructions:
      - text: Get the latest message history for channel {channel}.
        slots:
          channel: query.channel
      - text: Fetch messages in {channel} posted between {oldest} and {latest}.
        slots:
          channel: query.channel
          oldest: query.oldest
          latest: query.latest
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations.info'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details about a channel
      effect: read
      questions:
      - What are the settings and topic of a particular channel?
      - Can I get a channel's member count along with its details?
      instructions:
      - text: Show details for channel {channel}.
        slots:
          channel: query.channel
      - text: Get info on {channel} including how many members it has.
        slots:
          channel: query.channel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations.invite'].post
  update:
    x-apievangelist-phrasing:
      intent: Invite users to a channel
      effect: write
      questions:
      - How do I add several teammates to a channel at once?
      - Can I invite people into a private channel through the API?
      instructions:
      - text: Invite users {users} to channel {channel}.
        slots:
          users: requestBody.users
          channel: requestBody.channel
      - text: Add {users} as members of {channel}.
        slots:
          users: requestBody.users
          channel: requestBody.channel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations.join'].post
  update:
    x-apievangelist-phrasing:
      intent: Join an existing channel
      effect: write
      questions:
      - Can my app join a public channel on its own?
      - What happens if my bot tries to join a channel it is already in?
      instructions:
      - text: Join channel {channel}.
        slots:
          channel: requestBody.channel
      - text: Have me become a member of {channel} myself.
        slots:
          channel: requestBody.channel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations.kick'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove a user from a channel
      effect: destructive
      questions:
      - How do I remove someone from a channel?
      - Can an admin kick a specific member out of a private channel?
      instructions:
      - text: Remove user {user} from channel {channel}.
        slots:
          user: requestBody.user
          channel: requestBody.channel
      - text: Kick {user} out of {channel}.
        slots:
          user: requestBody.user
          channel: requestBody.channel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations.leave'].post
  update:
    x-apievangelist-phrasing:
      intent: Leave a channel
      effect: write
      questions:
      - Can my bot leave a channel it no longer needs to be in?
      - What is the call to take myself out of a conversation?
      instructions:
      - text: Leave channel {channel}.
        slots:
          channel: requestBody.channel
      - text: Take me out of {channel}.
        slots:
          channel: requestBody.channel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations.list'].get
  update:
    x-apievangelist-phrasing:
      intent: List channels in the workspace
      effect: read
      questions:
      - What channels exist in our workspace?
      - Can I list only private channels and skip archived ones?
      instructions:
      - text: List all channels in the workspace.
      - text: List workspace channels of type {types}, excluding archived ones.
        slots:
          types: query.types
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations.mark'].post
  update:
    x-apievangelist-phrasing:
      intent: Set the read cursor in a channel
      effect: write
      questions:
      - How do I mark a channel as read up to a certain message?
      - Can I move the read marker back to make older messages unread?
      instructions:
      - text: Mark channel {channel} as read up to message {ts}.
        slots:
          channel: requestBody.channel
          ts: requestBody.ts
      - text: Move the read cursor in {channel} to timestamp {ts}.
        slots:
          channel: requestBody.channel
          ts: requestBody.ts
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations.members'].get
  update:
    x-apievangelist-phrasing:
      intent: List the members of a channel
      effect: read
      questions:
      - Who is in a particular channel?
      - Is the channel member list paginated for large channels?
      instructions:
      - text: List the members of channel {channel}.
        slots:
          channel: query.channel
      - text: Get the next {limit} members of {channel} after cursor {cursor}.
        slots:
          limit: query.limit
          channel: query.channel
          cursor: query.cursor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations.open'].post
  update:
    x-apievangelist-phrasing:
      intent: Open a direct or group direct message
      effect: write
      questions:
      - How do I start a DM with a user so my bot can message them privately?
      - Can I open a group DM with several people at once?
      instructions:
      - text: Open a direct message with users {users}.
        slots:
          users: requestBody.users
      - text: Resume the existing DM {channel} and return its full details.
        slots:
          channel: requestBody.channel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations.rename'].post
  update:
    x-apievangelist-phrasing:
      intent: Rename a channel
      effect: write
      questions:
      - Can I change a channel's name after it has been created?
      - What are the rules for renaming a channel through the API?
      instructions:
      - text: Rename channel {channel} to {name}.
        slots:
          channel: requestBody.channel
          name: requestBody.name
      - text: Change the name of {channel} to {name}.
        slots:
          channel: requestBody.channel
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations.replies'].get
  update:
    x-apievangelist-phrasing:
      intent: Read the replies in a message thread
      effect: read
      questions:
      - How do I get all the replies in a thread?
      - Can I fetch only thread replies posted after a certain time?
      instructions:
      - text: Get the thread replies to message {ts} in {channel}.
        slots:
          ts: query.ts
          channel: query.channel
      - text: Show replies in the thread {ts} of {channel} newer than {oldest}.
        slots:
          ts: query.ts
          channel: query.channel
          oldest: query.oldest
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations.setPurpose'].post
  update:
    x-apievangelist-phrasing:
      intent: Set a channel's purpose
      effect: write
      questions:
      - Can I update the purpose description of a channel?
      - Where does a channel's purpose show up versus its topic?
      instructions:
      - text: Set the purpose of {channel} to {purpose}.
        slots:
          channel: requestBody.channel
          purpose: requestBody.purpose
      - text: Change channel {channel}'s description of purpose to {purpose}.
        slots:
          channel: requestBody.channel
          purpose: requestBody.purpose
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations.setTopic'].post
  update:
    x-apievangelist-phrasing:
      intent: Set a channel's topic
      effect: write
      questions:
      - How do I change the topic shown at the top of a channel?
      - Can a bot update a channel topic automatically, like an on-call rotation?
      instructions:
      - text: Set the topic of {channel} to {topic}.
        slots:
          channel: requestBody.channel
          topic: requestBody.topic
      - text: Update channel {channel}'s header topic to read {topic}.
        slots:
          channel: requestBody.channel
          topic: requestBody.topic
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations.unarchive'].post
  update:
    x-apievangelist-phrasing:
      intent: Unarchive a channel
      effect: write
      questions:
      - Can I bring back a channel that was archived?
      - What does it take to restore an archived conversation?
      instructions:
      - text: Unarchive channel {channel}.
        slots:
          channel: requestBody.channel
      - text: Restore the archived conversation {channel}.
        slots:
          channel: requestBody.channel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users.conversations'].get
  update:
    x-apievangelist-phrasing:
      intent: List the channels a user belongs to
      effect: read
      questions:
      - Which channels is a particular user a member of?
      - Can I list only the private channels and DMs I have access to?
      instructions:
      - text: List the channels user {user} belongs to.
        slots:
          user: query.user
      - text: Show my conversations of type {types}, excluding archived ones.
        slots:
          types: query.types
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations.archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive a channel
      effect: destructive
      questions:
      - How do I archive a channel that is no longer used?
      - What scope does my app need to archive a conversation?
      instructions:
      - text: Archive channel {channel}.
        slots:
          channel: requestBody.channel
      - text: Close out the unused channel {channel} by archiving it.
        slots:
          channel: requestBody.channel
      method: generated
      generated: '2026-09-26'