# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Knock App Messages API
  version: 1.0.0
extends: openapi/knock-app-messages-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: 27
- target: $.paths['/v1/channels/{channel_id}/messages/bulk/{action}'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk change message statuses on a channel
      effect: write
      questions:
      - How do I mark every message on one channel as read at once?
      - Can I bulk archive a channel's messages older than a certain date?
      instructions:
      - text: Apply {action} to all messages on channel {channel_id}.
        slots:
          action: path.action
          channel_id: path.channel_id
      - text: Apply {action} to channel {channel_id} messages older than {older_than}.
        slots:
          action: path.action
          channel_id: path.channel_id
          older_than: requestBody.older_than
      - text: Run bulk {action} on channel {channel_id} for recipients {recipient_ids}.
        slots:
          action: path.action
          channel_id: path.channel_id
          recipient_ids: requestBody.recipient_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/{message_id}/delivery_logs'].get
  update:
    x-apievangelist-phrasing:
      intent: List a message's delivery logs
      effect: read
      questions:
      - How do I see the raw provider requests and responses for a sent message?
      - Why did a message fail to deliver, according to its delivery logs?
      instructions:
      - text: List delivery logs for message {message_id}.
        slots:
          message_id: path.message_id
      - text: Show the provider delivery attempts for message {message_id}.
        slots:
          message_id: path.message_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages'].get
  update:
    x-apievangelist-phrasing:
      intent: List messages across the environment
      effect: read
      questions:
      - Which notifications were sent across the whole environment recently?
      - Can I filter all messages by delivery status or channel?
      - What messages did a single workflow run produce?
      instructions:
      - text: List all messages in this environment.
      - text: List environment messages with status {status} on channel {channel_id}.
        slots:
          status: query.status[]
          channel_id: query.channel_id
      - text: Show messages produced by workflow run {workflow_run_id}.
        slots:
          workflow_run_id: query.workflow_run_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/{message_id}/unseen'].delete
  update:
    x-apievangelist-phrasing:
      intent: Mark a message unseen (unseen endpoint)
      effect: destructive
      questions:
      - Is there a dedicated unseen endpoint for flipping one message back to unseen?
      - Can I call an /unseen route on a single message instead of removing its seen status?
      instructions:
      - text: Call the unseen endpoint for message {message_id}.
        slots:
          message_id: path.message_id
      - text: Flip message {message_id} to unseen using the /unseen route.
        slots:
          message_id: path.message_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/batch/unarchived'].post
  update:
    x-apievangelist-phrasing:
      intent: Unarchive several messages
      effect: write
      questions:
      - How do I restore a batch of archived notifications to the feed?
      - Can I unarchive many messages in one request?
      instructions:
      - text: Unarchive messages {message_ids}.
        slots:
          message_ids: requestBody.message_ids
      - text: 'Bring these archived messages back into the feed: {message_ids}.'
        slots:
          message_ids: requestBody.message_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/{message_id}/unread'].delete
  update:
    x-apievangelist-phrasing:
      intent: Mark a message unread (unread endpoint)
      effect: destructive
      questions:
      - Is there a dedicated unread endpoint for a single message?
      - Can I call an /unread route on one message instead of removing its read status?
      instructions:
      - text: Call the unread endpoint for message {message_id}.
        slots:
          message_id: path.message_id
      - text: Flip message {message_id} to unread using the /unread route.
        slots:
          message_id: path.message_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/{message_id}/seen'].put
  update:
    x-apievangelist-phrasing:
      intent: Mark a message seen
      effect: write
      questions:
      - How do I record that a user viewed one notification in their feed?
      - What's the difference between seen and read for a single message?
      instructions:
      - text: Mark message {message_id} as seen.
        slots:
          message_id: path.message_id
      - text: Record that message {message_id} was viewed in the feed.
        slots:
          message_id: path.message_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/{message_id}/seen'].delete
  update:
    x-apievangelist-phrasing:
      intent: Mark a message unseen
      effect: destructive
      questions:
      - How do I reverse the seen state on a single message?
      - Can I make one notification count as new again in the badge?
      instructions:
      - text: Mark message {message_id} as unseen.
        slots:
          message_id: path.message_id
      - text: Remove the seen status from message {message_id}.
        slots:
          message_id: path.message_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/{message_id}/events'].get
  update:
    x-apievangelist-phrasing:
      intent: List a message's events
      effect: read
      questions:
      - What status events has a message gone through?
      - Can I see when a message was sent, delivered and read?
      instructions:
      - text: List events for message {message_id}.
        slots:
          message_id: path.message_id
      - text: Show the event history of message {message_id}.
        slots:
          message_id: path.message_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/batch/seen'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark several messages seen
      effect: write
      questions:
      - How do I mark a whole batch of notifications as seen?
      - Can I clear the unseen badge for many messages at once?
      instructions:
      - text: Mark messages {message_ids} as seen.
        slots:
          message_ids: requestBody.message_ids
      - text: 'Record these messages as viewed: {message_ids}.'
        slots:
          message_ids: requestBody.message_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/batch/unseen'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark several messages unseen
      effect: write
      questions:
      - How do I reset many messages back to unseen in one call?
      - Can I undo seen on a batch of notifications?
      instructions:
      - text: Mark messages {message_ids} as unseen.
        slots:
          message_ids: requestBody.message_ids
      - text: 'Reset these messages to unseen: {message_ids}.'
        slots:
          message_ids: requestBody.message_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/{message_id}/read'].put
  update:
    x-apievangelist-phrasing:
      intent: Mark a message read
      effect: write
      questions:
      - How do I record that a user actually read a notification's content?
      - Can I mark a single message read when it's opened?
      instructions:
      - text: Mark message {message_id} as read.
        slots:
          message_id: path.message_id
      - text: Record that message {message_id} has been read.
        slots:
          message_id: path.message_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/{message_id}/read'].delete
  update:
    x-apievangelist-phrasing:
      intent: Mark a message unread
      effect: destructive
      questions:
      - How do I reverse the read state on a single message?
      - Can a user mark one notification as unread again?
      instructions:
      - text: Mark message {message_id} as unread.
        slots:
          message_id: path.message_id
      - text: Remove the read status from message {message_id}.
        slots:
          message_id: path.message_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/batch/content'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the content of several messages
      effect: read
      questions:
      - How do I fetch the rendered content for many messages at once?
      - Can I load several messages' bodies in one request?
      instructions:
      - text: Get the contents of messages {message_ids}.
        slots:
          message_ids: query.message_ids[]
      - text: 'Fetch rendered bodies for these messages in one call: {message_ids}.'
        slots:
          message_ids: query.message_ids[]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/{message_id}/content'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a message's rendered content
      effect: read
      questions:
      - What exactly did a sent message say, as rendered for its channel?
      - Can I see the final email or SMS body of one message?
      instructions:
      - text: Get the rendered content of message {message_id}.
        slots:
          message_id: path.message_id
      - text: Show me what message {message_id} looked like when sent.
        slots:
          message_id: path.message_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/{message_id}/activities'].get
  update:
    x-apievangelist-phrasing:
      intent: List a message's activities
      effect: read
      questions:
      - Which batched activities make up a message?
      - Can I filter a message's activities by trigger data?
      instructions:
      - text: List activities for message {message_id}.
        slots:
          message_id: path.message_id
      - text: Show message {message_id} activities matching trigger data {trigger_data}.
        slots:
          message_id: path.message_id
          trigger_data: query.trigger_data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/batch/unread'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark several messages unread
      effect: write
      questions:
      - How do I set many notifications back to unread at once?
      - Can I undo read on a batch of messages?
      instructions:
      - text: Mark messages {message_ids} as unread.
        slots:
          message_ids: requestBody.message_ids
      - text: 'Reset these messages to unread: {message_ids}.'
        slots:
          message_ids: requestBody.message_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/{message_id}/archived'].put
  update:
    x-apievangelist-phrasing:
      intent: Archive a message
      effect: write
      questions:
      - How do I hide one notification from a user's default feed?
      - Can an archived message be restored later?
      instructions:
      - text: Archive message {message_id}.
        slots:
          message_id: path.message_id
      - text: Hide message {message_id} from the default feed.
        slots:
          message_id: path.message_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/{message_id}/archived'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unarchive a message (archived route)
      effect: destructive
      questions:
      - Can I unarchive a single message by removing its archived status?
      - Is there a delete-the-archived-flag way to restore one message?
      instructions:
      - text: Remove the archived status from message {message_id}.
        slots:
          message_id: path.message_id
      - text: Delete the archived flag on message {message_id}.
        slots:
          message_id: path.message_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/batch/archived'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive several messages
      effect: write
      questions:
      - How do I archive a batch of notifications in one request?
      - Can I clear many messages out of the feed at once?
      instructions:
      - text: Archive messages {message_ids}.
        slots:
          message_ids: requestBody.message_ids
      - text: 'Hide these messages from the feed: {message_ids}.'
        slots:
          message_ids: requestBody.message_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/{message_id}/interacted'].put
  update:
    x-apievangelist-phrasing:
      intent: Record an interaction on a message
      effect: write
      questions:
      - How do I record that a user clicked a button in a notification?
      - How many metadata fields can I attach to a message interaction?
      instructions:
      - text: Mark message {message_id} as interacted.
        slots:
          message_id: path.message_id
      - text: Record an interaction on message {message_id} with metadata {metadata}.
        slots:
          message_id: path.message_id
          metadata: requestBody.metadata
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/{message_id}/unarchived'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unarchive a message (unarchived route)
      effect: destructive
      questions:
      - Is there a dedicated unarchived endpoint to restore one message to the feed?
      - Can I call an /unarchived route on a single message?
      instructions:
      - text: Call the unarchived endpoint for message {message_id}.
        slots:
          message_id: path.message_id
      - text: Restore message {message_id} using the /unarchived route.
        slots:
          message_id: path.message_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/batch/read'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark several messages read
      effect: write
      questions:
      - How do I implement a mark-all-as-read for a set of messages?
      - Can I mark many notifications read in one call?
      instructions:
      - text: Mark messages {message_ids} as read.
        slots:
          message_ids: requestBody.message_ids
      - text: 'Record these messages as read: {message_ids}.'
        slots:
          message_ids: requestBody.message_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/{message_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a message by ID
      effect: read
      questions:
      - How do I look up a single message's status and recipient?
      - Can I retrieve one notification by its message ID?
      instructions:
      - text: Get message {message_id}.
        slots:
          message_id: path.message_id
      - text: Show the status and details of message {message_id}.
        slots:
          message_id: path.message_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/messages/batch/interacted'].post
  update:
    x-apievangelist-phrasing:
      intent: Record interactions on several messages
      effect: write
      questions:
      - How do I log interactions on a batch of messages at once?
      - Can I attach the same metadata to many message interactions?
      instructions:
      - text: Mark messages {message_ids} as interacted.
        slots:
          message_ids: requestBody.message_ids
      - text: Record interactions on {message_ids} with metadata {metadata}.
        slots:
          message_ids: requestBody.message_ids
          metadata: requestBody.metadata
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/{id}/messages'].get
  update:
    x-apievangelist-phrasing:
      intent: List messages sent to an object
      effect: read
      questions:
      - Which notifications were sent to an object like a project or team?
      - Can I filter an object's messages by engagement status?
      instructions:
      - text: List messages for object {id} in {collection}.
        slots:
          id: path.id
          collection: path.collection
      - text: Show {collection}/{id} messages with engagement status {engagement_status}.
        slots:
          collection: path.collection
          id: path.id
          engagement_status: query.engagement_status[]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/messages'].get
  update:
    x-apievangelist-phrasing:
      intent: List messages sent to a user
      effect: read
      questions:
      - What notifications has a particular user received?
      - Why are a user's older messages missing from the list?
      instructions:
      - text: List messages for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Show user {user_id}'s messages on channel {channel_id}.
        slots:
          user_id: path.user_id
          channel_id: query.channel_id
      method: generated
      generated: '2026-10-01'