# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Khoros Ai Messages API
  version: 1.0.0
extends: openapi/khoros-ai-messages-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-02'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 14
- target: $.paths['/{integrationUuid}/messages/validation'].post
  update:
    x-apievangelist-phrasing:
      intent: Validate an inbound messages payload
      effect: read
      questions:
      - How can I test whether my inbound message JSON is valid before sending it to Care?
      - Can I dry-run a Listening API messages payload for a social integration?
      instructions:
      - text: Validate this inbound messages payload {payload} for integration {integration}.
        slots:
          payload: requestBody.RAW_BODY
          integration: path.integrationUuid
      - text: Check the inbound message JSON for integration {integration} without creating anything.
        slots:
          integration: path.integrationUuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{integrationUuid}/messages'].post
  update:
    x-apievangelist-phrasing:
      intent: Ingest inbound messages from a custom integration
      effect: write
      questions:
      - How do I push messages from my own channel into Khoros Care?
      - Can a custom social integration create inbound messages in bulk?
      instructions:
      - text: Create inbound messages {payload} for integration {integration}.
        slots:
          payload: requestBody.RAW_BODY
          integration: path.integrationUuid
      - text: Send new inbound customer messages into Care through integration {integration}.
        slots:
          integration: path.integrationUuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{integrationUuid}/messages'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete inbound messages from an integration
      effect: destructive
      questions:
      - Can I remove messages that a custom integration previously sent into Care?
      - How do I delete ingested messages for a social integration?
      instructions:
      - text: Delete the inbound messages {payload} from integration {integration}.
        slots:
          payload: requestBody.RAW_BODY
          integration: path.integrationUuid
      - text: Remove previously ingested messages for integration {integration}.
        slots:
          integration: path.integrationUuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/messages'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate a new Flow thread ID
      effect: write
      questions:
      - How do I get a thread ID to start a Flow conversation over REST?
      - Where does a new threadId for the Flow REST API come from?
      instructions:
      - text: Generate a new thread ID.
      - text: Create a Flow thread ID I can use for messaging.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/messages/{threadId}'].get
  update:
    x-apievangelist-phrasing:
      intent: List the messages in a Flow thread
      effect: read
      questions:
      - How do I read back the messages in a Flow bot thread?
      - Can I include the history of triggered events when listing a thread's messages?
      instructions:
      - text: List the messages in thread {thread}.
        slots:
          thread: path.threadId
      - text: Show page {page} of messages in thread {thread} including triggered events.
        slots:
          page: query.page
          thread: path.threadId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/messages/{threadId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a text message to a Flow thread
      effect: write
      questions:
      - How do I send a user's text message into a Flow bot thread?
      - Can a text message be processed synchronously so I get the bot reply right away?
      instructions:
      - text: Send the text {payload} to thread {thread}.
        slots:
          payload: requestBody.payload
          thread: path.threadId
      - text: Post a text message to thread {thread} in sync mode.
        slots:
          thread: path.threadId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/{environment}/v1/company/{companyId}/initiative/{initiativeId}/message'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish a message through the company-scoped v1 API
      effect: write
      questions:
      - How do I publish a social message through the v1 company and environment endpoint?
      - Can I schedule a v1 message to a social network for an initiative?
      instructions:
      - text: Publish a message titled {title} to {network} for company {company} initiative {initiative} in {env}.
        slots:
          env: path.environment
          company: path.companyId
          initiative: path.initiativeId
          title: requestBody.title
          network: requestBody.service
      - text: Schedule a v1 message for {date} in initiative {initiative} of company {company} on {env}.
        slots:
          env: path.environment
          company: path.companyId
          initiative: path.initiativeId
          date: requestBody.scheduledPublishDate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{environment}/v1/company/{companyId}/initiative/{initiativeId}/message/{messageId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a message through the company-scoped v1 API
      effect: read
      questions:
      - How do I fetch one message using the v1 company-scoped path?
      - What status does a v1 message show after publishing?
      instructions:
      - text: Get v1 message {message} in initiative {initiative} for company {company} on {env}.
        slots:
          env: path.environment
          company: path.companyId
          initiative: path.initiativeId
          message: path.messageId
      - text: Show the publication status of message {message} under company {company}, initiative {initiative}, environment {env}.
        slots:
          env: path.environment
          company: path.companyId
          initiative: path.initiativeId
          message: path.messageId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{environment}/v1/company/{companyId}/initiative/{initiativeId}/message/{messageId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a message through the company-scoped v1 API
      effect: write
      questions:
      - Can I change a message's title or labels through the v1 company endpoint?
      - How do I reschedule a message with the v1 API?
      instructions:
      - text: Retitle v1 message {message} to {title} in initiative {initiative} of company {company} on {env}.
        slots:
          env: path.environment
          company: path.companyId
          initiative: path.initiativeId
          message: path.messageId
          title: requestBody.title
      - text: Reschedule message {message} to {date} for company {company}, initiative {initiative}, environment {env}.
        slots:
          env: path.environment
          company: path.companyId
          initiative: path.initiativeId
          message: path.messageId
          date: requestBody.scheduledPublishDate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{environment}/v1/company/{companyId}/initiative/{initiativeId}/message/{messageId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a message through the company-scoped v1 API
      effect: destructive
      questions:
      - Can I delete a message using the v1 company-scoped endpoint?
      - How do I remove a scheduled message with the v1 API?
      instructions:
      - text: Delete v1 message {message} in initiative {initiative} for company {company} on {env}.
        slots:
          env: path.environment
          company: path.companyId
          initiative: path.initiativeId
          message: path.messageId
      - text: Remove message {message} from company {company}, initiative {initiative}, environment {env}.
        slots:
          env: path.environment
          company: path.companyId
          initiative: path.initiativeId
          message: path.messageId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{environment}/v1/company/{companyId}/initiative/{initiativeId}/message?multipart'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish a v1 message with one uploaded image
      effect: write
      questions:
      - How do I publish a v1 message and upload its image in the same request?
      - Is an image file required when publishing a multipart v1 message?
      instructions:
      - text: Publish multipart message {message} with image {image} to initiative {initiative} of company {company} on {env}.
        slots:
          env: path.environment
          company: path.companyId
          initiative: path.initiativeId
          message: requestBody.message
          image: requestBody.image
      - text: Upload image {image} and post it as a v1 message in initiative {initiative}, company {company}, {env}.
        slots:
          env: path.environment
          company: path.companyId
          initiative: path.initiativeId
          image: requestBody.image
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{environment}/v1/company/{companyId}/initiative/{initiativeId}/message?imageset'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish a v1 message with several images
      effect: write
      questions:
      - How do I publish one v1 post carrying multiple uploaded images?
      - Does the number of images in an image-set message have to match the files uploaded?
      instructions:
      - text: Publish image-set message {message} with images {image} to initiative {initiative} of company {company} on {env}.
        slots:
          env: path.environment
          company: path.companyId
          initiative: path.initiativeId
          message: requestBody.message
          image: requestBody.image
      - text: Post an image set to initiative {initiative} for company {company} in {env}.
        slots:
          env: path.environment
          company: path.companyId
          initiative: path.initiativeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{environment}/v1/company/{companyId}/initiative/{initiativeId}/message?video'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish a v1 video message
      effect: write
      questions:
      - How do I publish a video post through the v1 messages API?
      - Can I upload a video as part of publishing a v1 message?
      instructions:
      - text: Publish video message {message} to initiative {initiative} of company {company} on {env}.
        slots:
          env: path.environment
          company: path.companyId
          initiative: path.initiativeId
          message: requestBody.message
      - text: Post a video to initiative {initiative} for company {company} in {env}.
        slots:
          env: path.environment
          company: path.companyId
          initiative: path.initiativeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{environment}/v1/company/{companyId}/initiative/{initiativeId}/message/{messageId}?multipart'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a v1 multipart message and its image
      effect: write
      questions:
      - Can I swap the image on a v1 multi-part message I already created?
      - How do I update a v1 message that was published with an uploaded file?
      instructions:
      - text: Update multipart message {message_id} with {message} and new image {image} in initiative {initiative}, company {company}, {env}.
        slots:
          env: path.environment
          company: path.companyId
          initiative: path.initiativeId
          message_id: path.messageId
          message: requestBody.message
          image: requestBody.image
      - text: Replace the image on v1 multipart message {message_id} for company {company}, initiative {initiative}, {env} using {message}.
        slots:
          env: path.environment
          company: path.companyId
          initiative: path.initiativeId
          message_id: path.messageId
          message: requestBody.message
      method: generated
      generated: '2026-10-01'