# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Canvas LMS REST Conversations API
  version: 1.0.0
extends: openapi/canvas-conversations-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 12
- target: $.paths['/v1/conversations'].get
  update:
    x-apievangelist-phrasing:
      intent: List my inbox conversations
      effect: read
      questions:
      - How do I see my Canvas inbox conversations, newest first?
      - Can I filter my conversations to only unread or starred ones?
      - Can I show only conversations from one course?
      instructions:
      - text: List my conversations.
      - text: Show my {scope} conversations.
        slots:
          scope: query.scope
      - text: List my conversations filtered to {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/conversations'].put
  update:
    x-apievangelist-phrasing:
      intent: Apply one change to many conversations
      effect: write
      questions:
      - How do I mark a bunch of conversations as read at once?
      - Can I archive or star several conversations in a single request?
      instructions:
      - text: Apply {event} to conversations {conversation_ids}.
        slots:
          event: requestBody.event
          conversation_ids: requestBody.conversation_ids
      - text: Bulk {event} the conversations {conversation_ids}.
        slots:
          event: requestBody.event
          conversation_ids: requestBody.conversation_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/conversations'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a new inbox message
      effect: write
      questions:
      - How do I send a private message to a student in Canvas?
      - Can I message a whole course section in one go?
      - Will messaging the same people reuse an existing conversation?
      instructions:
      - text: 'Message {recipients}: {body}'
        slots:
          recipients: requestBody.recipients
          body: requestBody.body
      - text: Start a conversation with {recipients} titled {subject} saying {body}.
        slots:
          recipients: requestBody.recipients
          subject: requestBody.subject
          body: requestBody.body
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/conversations/batches'].get
  update:
    x-apievangelist-phrasing:
      intent: Check my bulk message batches in progress
      effect: read
      questions:
      - Is my bulk private message still being sent?
      - What conversation batches are currently running for me?
      instructions:
      - text: Show my running conversation batches.
      - text: Check whether my bulk messages have finished sending.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/conversations/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a single conversation
      effect: read
      questions:
      - How do I open one conversation with all its messages?
      - Can I read a conversation without marking it as read?
      instructions:
      - text: Open conversation {id}.
        slots:
          id: path.id
      - text: Show all messages and participants in conversation {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/conversations/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Star, archive or mute a conversation
      effect: write
      questions:
      - How do I star or archive one conversation?
      - Can I unsubscribe from a conversation so I stop getting notified?
      instructions:
      - text: Set conversation {id} to {workflow_state}.
        slots:
          id: path.id
          workflow_state: requestBody.conversation[workflow_state]
      - text: Star conversation {id}.
        slots:
          id: path.id
      - text: Unsubscribe me from conversation {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/conversations/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a conversation from my inbox
      effect: destructive
      questions:
      - How do I delete a whole conversation from my inbox?
      - Does deleting a conversation remove it for the other participants too?
      instructions:
      - text: Delete conversation {id}.
        slots:
          id: path.id
      - text: Remove conversation {id} and all its messages from my view.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/conversations/mark_all_as_read'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark all my conversations as read
      effect: write
      questions:
      - Can I clear every unread conversation in my inbox at once?
      - What's the quickest way to mark my whole inbox as read?
      instructions:
      - text: Mark all my conversations as read.
      - text: Clear my entire unread inbox.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/conversations/{id}/add_recipients'].post
  update:
    x-apievangelist-phrasing:
      intent: Add people to a group conversation
      effect: write
      questions:
      - How do I add more people to an existing group conversation?
      - Can I bring a new student into a conversation already underway?
      instructions:
      - text: Add {recipients} to conversation {id}.
        slots:
          recipients: requestBody.recipients
          id: path.id
      - text: Invite {recipients} into group conversation {id}.
        slots:
          recipients: requestBody.recipients
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/conversations/{id}/add_message'].post
  update:
    x-apievangelist-phrasing:
      intent: Reply in an existing conversation
      effect: write
      questions:
      - How do I reply to a conversation that's already going?
      - Can I reply to only some of the people in a conversation?
      instructions:
      - text: Reply to conversation {id} with {body}.
        slots:
          id: path.id
          body: requestBody.body
      - text: Reply to conversation {id} with {body}, sent only to {recipients}.
        slots:
          id: path.id
          body: requestBody.body
          recipients: requestBody.recipients
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/conversations/{id}/remove_messages'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete specific messages from a conversation
      effect: destructive
      questions:
      - How do I delete individual messages from a conversation?
      - What happens if I delete every message in a conversation?
      instructions:
      - text: Delete messages {remove} from conversation {id}.
        slots:
          remove: requestBody.remove
          id: path.id
      - text: Remove message {remove} from my view of conversation {id}.
        slots:
          remove: requestBody.remove
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/conversations/unread_count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count my unread conversations
      effect: read
      questions:
      - How many unread conversations do I have?
      - What's my unread inbox count in Canvas?
      instructions:
      - text: Tell me how many unread conversations I have.
      - text: Get my unread conversation count.
      method: generated
      generated: '2026-10-01'