# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Optimizely Messages API
  version: 1.0.0
extends: openapi/optimizely-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: 17
- target: $.paths['/api/v1/admin/Messages'].get
  update:
    x-apievangelist-phrasing:
      intent: List site messages in the admin console
      effect: read
      questions:
      - Which admin-managed site messages are currently set up in Optimizely Commerce?
      - Can I filter the admin message list to ones with a given subject?
      instructions:
      - text: List all admin site messages.
      - text: Show admin messages matching {filter}, sorted by {orderby}.
        slots:
          filter: query.$filter
          orderby: query.$orderby
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Messages'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a site message as an admin
      effect: write
      questions:
      - How do I publish a new site message with a subject and body from the admin API?
      - Can I schedule when an admin message starts and stops displaying?
      instructions:
      - text: Create an admin message titled {subject} with body {body}.
        slots:
          subject: requestBody.subject
          body: requestBody.body
      - text: Post admin message {subject} with body {body}, shown from {dateToDisplay} until {dateToHide}.
        slots:
          subject: requestBody.subject
          body: requestBody.body
          dateToDisplay: requestBody.dateToDisplay
          dateToHide: requestBody.dateToHide
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Messages({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one admin site message
      effect: read
      questions:
      - What does a single admin site message record contain?
      - Can I pull up one admin message by its id?
      instructions:
      - text: Fetch admin message {id}.
        slots:
          id: path.id
      - text: Show the subject and body of admin message {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Messages({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace an admin site message
      effect: write
      questions:
      - Can I overwrite an entire admin message record in one call?
      - Does replacing an admin message require resending both subject and body?
      instructions:
      - text: Replace admin message {id} with subject {subject} and body {body}.
        slots:
          id: path.id
          subject: requestBody.subject
          body: requestBody.body
      - text: Overwrite the full record of admin message {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Messages({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one admin site message
      effect: destructive
      questions:
      - How do I remove a single admin site message?
      - Can I make deleting an admin message conditional on its ETag?
      instructions:
      - text: Delete admin message {id}.
        slots:
          id: path.id
      - text: Delete admin message {id} only if its ETag is {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Messages({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit part of an admin site message
      effect: write
      questions:
      - Can I push back the hide date on an existing admin message?
      - Is it possible to change only the language of an admin message?
      instructions:
      - text: Set the hide date of admin message {id} to {dateToHide}.
        slots:
          id: path.id
          dateToHide: requestBody.dateToHide
      - text: Change the subject of admin message {id} to {subject}.
        slots:
          id: path.id
          subject: requestBody.subject
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Messages/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get default values for a new site message
      effect: read
      questions:
      - What defaults does a blank admin message start with?
      - Is there an empty site message template I can fill in?
      instructions:
      - text: Get the default field values for a new admin message.
      - text: Show the blank site message template.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/messages/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete admin site messages
      effect: destructive
      questions:
      - Can I remove several admin site messages in one request?
      - Is there a batch delete for site messages by id list?
      instructions:
      - text: Bulk delete admin messages {ids}.
        slots:
          ids: query.ids
      - text: Permanently delete every site message in {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/messages({key})/customerorderchanges({customerorderchangeKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order change linked to a message
      effect: read
      questions:
      - Which customer order change is tied to a particular site message?
      - Can I read one order change record through the message it belongs to?
      instructions:
      - text: Get order change {customerorderchangeKey} on message {key}.
        slots:
          key: path.key
          customerorderchangeKey: path.customerorderchangeKey
      - text: Show customer order change {customerorderchangeKey} attached to message {key}.
        slots:
          key: path.key
          customerorderchangeKey: path.customerorderchangeKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/messages({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a site message
      effect: read
      questions:
      - How can I read a custom property stored on a site message?
      - Can I fetch one custom field value from a message record?
      instructions:
      - text: Get custom property {custompropertyKey} of message {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      - text: Show the {custompropertyKey} custom property on message {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/messages({key})/messageaudits({messageauditKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an audit entry for a site message
      effect: read
      questions:
      - Where can I see an audit trail entry recorded for a message?
      - Can I look up one message audit record by its key?
      instructions:
      - text: Get audit entry {messageauditKey} of message {key}.
        slots:
          key: path.key
          messageauditKey: path.messageauditKey
      - text: Show message audit {messageauditKey} for message {key}.
        slots:
          key: path.key
          messageauditKey: path.messageauditKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/messages({key})/messagestatuses({messagestatusKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a delivery status of a site message
      effect: read
      questions:
      - What status record does a message have for a given recipient?
      - Can I check one message status entry, like whether it was read?
      instructions:
      - text: Get status {messagestatusKey} of message {key}.
        slots:
          key: path.key
          messagestatusKey: path.messagestatusKey
      - text: Show message status record {messagestatusKey} under message {key}.
        slots:
          key: path.key
          messagestatusKey: path.messagestatusKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/messages({key})/messagetargets({messagetargetKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a target audience entry of a message
      effect: read
      questions:
      - Who is a site message targeted at?
      - Can I read one message target entry to see which audience it addresses?
      instructions:
      - text: Get target {messagetargetKey} of message {key}.
        slots:
          key: path.key
          messagetargetKey: path.messagetargetKey
      - text: Show message target {messagetargetKey} defined on message {key}.
        slots:
          key: path.key
          messagetargetKey: path.messagetargetKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/messages'].get
  update:
    x-apievangelist-phrasing:
      intent: List the signed-in user's inbox messages
      effect: read
      questions:
      - How do I show a storefront user the messages in their inbox?
      - What messages has the current shopper received?
      instructions:
      - text: List my storefront inbox messages.
      - text: Show the messages the current user has received.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/messages'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a message about an order to a user
      effect: write
      questions:
      - Can a shopper send a message about one of their orders from the storefront?
      - Is it possible to address a storefront message to a specific user profile?
      instructions:
      - text: Send a message about order {customerOrderId} with subject {subject} saying {message}.
        slots:
          customerOrderId: requestBody.customerOrderId
          subject: requestBody.subject
          message: requestBody.message
      - text: Send user {toUserProfileId} the message {message} under subject {subject}.
        slots:
          toUserProfileId: requestBody.toUserProfileId
          message: requestBody.message
          subject: requestBody.subject
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/messages/{messageId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Open one message from the user's inbox
      effect: read
      questions:
      - How does a storefront user open a single message from their inbox?
      - Can I fetch one received message with its full body for display?
      instructions:
      - text: Open inbox message {messageId}.
        slots:
          messageId: path.messageId
      - text: Show the full storefront message {messageId}.
        slots:
          messageId: path.messageId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/messages/{messageId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Mark an inbox message as read or unread
      effect: write
      questions:
      - Can a shopper mark one of their storefront messages as read?
      - Is there a way to flag an inbox message back to unread?
      instructions:
      - text: Mark inbox message {messageId} as read.
        slots:
          messageId: path.messageId
      - text: Set the read flag of storefront message {messageId} to {isRead}.
        slots:
          messageId: path.messageId
          isRead: requestBody.isRead
      method: generated
      generated: '2026-09-26'