API Evangelist conversational phrasing for Mirakl Messages API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Mirakl Messages API
  version: 1.0.0
extends: openapi/mirakl-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: 10
- target: $.paths['/api/messages'].get
  update:
    x-apievangelist-phrasing:
      intent: List order and offer messages (deprecated)
      effect: read
      questions:
      - Can I still list messages on orders and offers with the old messages endpoint?
      - Which customer messages did my shop receive on a given order, via the legacy API?
      instructions:
      - text: List legacy messages for order {order_id}.
        slots:
          order_id: query.order_id
      - text: Show legacy messages on offer {offer_id} since {start_date}.
        slots:
          offer_id: query.offer_id
          start_date: query.start_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/inbox/threads/{thread_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an inbox thread
      effect: read
      questions:
      - How do I read every message in a conversation thread?
      - Can I fetch a single inbox thread by its ID?
      instructions:
      - text: Get thread {thread_id}.
        slots:
          thread_id: path.thread_id
      - text: Show the messages in thread {thread_id}.
        slots:
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/inbox/threads'].get
  update:
    x-apievangelist-phrasing:
      intent: List inbox threads
      effect: read
      questions:
      - Which message threads have been updated since yesterday?
      - Can I list threads linked to a specific order?
      instructions:
      - text: List threads updated since {updated_since}.
        slots:
          updated_since: query.updated_since
      - text: Show threads on {entity_type} {entity_id}.
        slots:
          entity_type: query.entity_type
          entity_id: query.entity_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/inbox/threads'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a thread with the operator
      effect: write
      questions:
      - How can a seller open a conversation with the marketplace operator?
      - Can I attach files to my first message to the operator?
      instructions:
      - text: Create an operator thread with {thread_input}.
        slots:
          thread_input: requestBody.thread_input
      - text: Message the operator from shop {shop_id} with {thread_input}.
        slots:
          shop_id: query.shop_id
          thread_input: requestBody.thread_input
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/inbox/threads/{thread_id}/message'].post
  update:
    x-apievangelist-phrasing:
      intent: Reply to a thread
      effect: write
      questions:
      - How do I reply in an existing message thread?
      - Is there a cap on the number of messages in a thread?
      instructions:
      - text: Reply to thread {thread_id} with {message_input}.
        slots:
          thread_id: path.thread_id
          message_input: requestBody.message_input
      - text: Send {message_input} with attachments {files} in thread {thread_id}.
        slots:
          message_input: requestBody.message_input
          files: requestBody.files
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/inbox/threads/{attachment_id}/download'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a thread attachment
      effect: read
      questions:
      - How do I download a file someone attached in a message thread?
      - Can I retrieve an inbox attachment by its ID?
      instructions:
      - text: Download attachment {attachment_id}.
        slots:
          attachment_id: path.attachment_id
      - text: Get the file for thread attachment {attachment_id}.
        slots:
          attachment_id: path.attachment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/{order_id}/messages'].post
  update:
    x-apievangelist-phrasing:
      intent: Post a message on an order (deprecated)
      effect: write
      questions:
      - Can I still post a message on an order with the old order-messages endpoint?
      - Does the legacy order message call create the customer if they don't exist?
      instructions:
      - text: Post legacy message {body} with subject {subject} on order {order_id}.
        slots:
          body: requestBody.body
          subject: requestBody.subject
          order_id: path.order_id
      - text: Send {body} to the shop on order {order_id} via the deprecated endpoint, as customer {customer_id}.
        slots:
          body: requestBody.body
          order_id: path.order_id
          customer_id: requestBody.customer_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/orders/{order_id}/threads'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a thread on a product order
      effect: write
      questions:
      - How do I open a conversation about a product order?
      - What's the size limit for attachments on an order message?
      instructions:
      - text: Create a thread on order {order_id} with {thread_input}.
        slots:
          order_id: path.order_id
          thread_input: requestBody.thread_input
      - text: 'Message the customer about order {order_id}: {thread_input}.'
        slots:
          order_id: path.order_id
          thread_input: requestBody.thread_input
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/mms/services/{service_code}/threads'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a thread on a service
      effect: write
      questions:
      - How can I open a conversation about a service listing?
      - Can a shop message the operator about one of its services?
      instructions:
      - text: Create a thread on service {service_code} with {thread_input}.
        slots:
          service_code: path.service_code
          thread_input: requestBody.thread_input
      - text: 'Open a message thread about service {service_code} for shop {shop_id}: {thread_input}.'
        slots:
          service_code: path.service_code
          shop_id: query.shop_id
          thread_input: requestBody.thread_input
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/mms/orders/{order_id}/threads'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a thread on a service order
      effect: write
      questions:
      - How do I message a customer about a booked service order?
      - Can I attach files when starting a thread on a service order?
      instructions:
      - text: Start a service-booking thread on service order {order_id} with {thread_input}.
        slots:
          order_id: path.order_id
          thread_input: requestBody.thread_input
      - text: 'Open a conversation about service order {order_id}: {thread_input}.'
        slots:
          order_id: path.order_id
          thread_input: requestBody.thread_input
      method: generated
      generated: '2026-09-26'