# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Dialogflow ES API (v2) Suggestions API
  version: 1.0.0
extends: openapi/google-dialogflow-suggestions-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: 18
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/suggestions:searchKnowledge'].post
  update:
    x-apievangelist-phrasing:
      intent: Search the knowledge base for a regional profile
      effect: read
      questions:
      - Can I query my agent-assist knowledge sources directly in a specific region without a conversation?
      - Is there a regional knowledge search that only takes a conversation profile and a question?
      instructions:
      - text: Search knowledge for {query} in project {project}, location {location}, using conversation profile {profile}.
        slots:
          query: requestBody.query
          project: path.projectsId
          location: path.locationsId
          profile: requestBody.conversationProfile
      - text: Run an exact-match regional knowledge search in {location} for project {project} on {query}.
        slots:
          location: path.locationsId
          project: path.projectsId
          query: requestBody.query
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/suggestions:generateStatelessSummary'].post
  update:
    x-apievangelist-phrasing:
      intent: Summarize a transcript in a region without storing it
      effect: read
      questions:
      - Can I get a summary of a conversation transcript I send inline, without creating a regional conversation?
      - Is there a way to cap how many messages a stateless summary considers in one location?
      instructions:
      - text: Generate a stateless summary in project {project}, location {location}, for the conversation {transcript}.
        slots:
          project: path.projectsId
          location: path.locationsId
          transcript: requestBody.statelessConversation
      - text: Summarize this inline transcript in {location} for project {project}, using at most {max_context} messages.
        slots:
          location: path.locationsId
          project: path.projectsId
          max_context: requestBody.maxContextSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/conversations/{conversationsId}/participants/{participantsId}/suggestions:suggestFaqAnswers'].post
  update:
    x-apievangelist-phrasing:
      intent: Suggest FAQ answers for a regional participant
      effect: write
      questions:
      - Can the assistant propose FAQ answers to an agent during a live conversation in a region?
      - Which recent messages are used when FAQ answers are suggested for a participant in one location?
      instructions:
      - text: Suggest FAQ answers for participant {participant} in conversation {conversation}, project {project}, location {location}.
        slots:
          participant: path.participantsId
          conversation: path.conversationsId
          project: path.projectsId
          location: path.locationsId
      - text: Propose FAQ replies to regional participant {participant} in conversation {conversation} based on the last {context_size} messages.
        slots:
          participant: path.participantsId
          conversation: path.conversationsId
          context_size: requestBody.contextSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/conversations/{conversationsId}/participants/{participantsId}/suggestions:suggestKnowledgeAssist'].post
  update:
    x-apievangelist-phrasing:
      intent: Get Knowledge Assist for a regional participant
      effect: write
      questions:
      - Can Knowledge Assist suggest a query and answer for a participant in a regional conversation?
      - Does regional Knowledge Assist avoid repeating the query it suggested last time?
      instructions:
      - text: Run Knowledge Assist for participant {participant} in conversation {conversation}, project {project}, location {location}.
        slots:
          participant: path.participantsId
          conversation: path.conversationsId
          project: path.projectsId
          location: path.locationsId
      - text: Get regional Knowledge Assist for participant {participant} in conversation {conversation}, skipping previous query {previous}.
        slots:
          participant: path.participantsId
          conversation: path.conversationsId
          previous: requestBody.previousSuggestedQuery
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/conversations/{conversationsId}/participants/{participantsId}/suggestions:suggestSmartReplies'].post
  update:
    x-apievangelist-phrasing:
      intent: Suggest smart replies for a regional participant
      effect: write
      questions:
      - Can I get smart reply suggestions while an agent is typing in a regional conversation?
      - Will smart replies in a specific location take the agent's half-typed text into account?
      instructions:
      - text: Suggest smart replies for participant {participant} in conversation {conversation}, project {project}, location {location}.
        slots:
          participant: path.participantsId
          conversation: path.conversationsId
          project: path.projectsId
          location: path.locationsId
      - text: Offer regional smart replies to participant {participant} in conversation {conversation} given the draft text {current_text}.
        slots:
          participant: path.participantsId
          conversation: path.conversationsId
          current_text: requestBody.currentTextInput
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/conversations/{conversationsId}/participants/{participantsId}/suggestions:suggestArticles'].post
  update:
    x-apievangelist-phrasing:
      intent: Suggest articles for a regional participant
      effect: write
      questions:
      - Can I surface knowledge articles to a human agent during a regional conversation?
      - How many messages of context are used to pick suggested articles in one location?
      instructions:
      - text: Suggest articles for participant {participant} in conversation {conversation}, project {project}, location {location}.
        slots:
          participant: path.participantsId
          conversation: path.conversationsId
          project: path.projectsId
          location: path.locationsId
      - text: Recommend regional help articles to participant {participant} in conversation {conversation} from the last {context_size} messages.
        slots:
          participant: path.participantsId
          conversation: path.conversationsId
          context_size: requestBody.contextSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/conversations/{conversationsId}/suggestions:suggestConversationSummary'].post
  update:
    x-apievangelist-phrasing:
      intent: Summarize a regional conversation
      effect: write
      questions:
      - Can I get an AI summary of an ongoing conversation stored in a specific region?
      - Which messages are included when summarizing a regional conversation?
      instructions:
      - text: Suggest a summary for conversation {conversation} in project {project}, location {location}.
        slots:
          conversation: path.conversationsId
          project: path.projectsId
          location: path.locationsId
      - text: Summarize regional conversation {conversation} up to message {latest_message}.
        slots:
          conversation: path.conversationsId
          latest_message: requestBody.latestMessage
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/conversations/{conversationsId}/suggestions:searchKnowledge'].post
  update:
    x-apievangelist-phrasing:
      intent: Search knowledge within a regional conversation
      effect: read
      questions:
      - Can a human agent search the knowledge base from inside a regional conversation?
      - Does a knowledge search scoped to a regional conversation use its message history?
      instructions:
      - text: Search knowledge for {query} within conversation {conversation}, project {project}, location {location}.
        slots:
          query: requestBody.query
          conversation: path.conversationsId
          project: path.projectsId
          location: path.locationsId
      - text: Look up {query} in the knowledge base for regional conversation {conversation}.
        slots:
          query: requestBody.query
          conversation: path.conversationsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/conversations/{conversationsId}/suggestions:generate'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate suggestions for a regional conversation
      effect: write
      questions:
      - Can I trigger every configured generator on a regional conversation at once?
      - Which trigger events can I pass when generating suggestions for a conversation in one location?
      instructions:
      - text: Generate suggestions for conversation {conversation} in project {project}, location {location}.
        slots:
          conversation: path.conversationsId
          project: path.projectsId
          location: path.locationsId
      - text: Run regional generators on conversation {conversation} for trigger events {trigger_events}.
        slots:
          conversation: path.conversationsId
          trigger_events: requestBody.triggerEvents
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/conversations/{conversationsId}/participants/{participantsId}/suggestions:suggestSmartReplies'].post
  update:
    x-apievangelist-phrasing:
      intent: Suggest smart replies for a participant
      effect: write
      questions:
      - Can my agents get smart reply suggestions in a conversation on the global endpoint?
      - Do default-location smart replies consider what the agent has already typed?
      instructions:
      - text: Suggest smart replies for participant {participant} in global conversation {conversation}, project {project}.
        slots:
          participant: path.participantsId
          conversation: path.conversationsId
          project: path.projectsId
      - text: Give participant {participant} default-location smart replies in conversation {conversation} for typed text {current_text}.
        slots:
          participant: path.participantsId
          conversation: path.conversationsId
          current_text: requestBody.currentTextInput
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/conversations/{conversationsId}/participants/{participantsId}/suggestions:suggestArticles'].post
  update:
    x-apievangelist-phrasing:
      intent: Suggest articles for a participant
      effect: write
      questions:
      - What knowledge articles can be suggested to a participant in a global conversation?
      - Can I limit how much history is used for default-location article suggestions?
      instructions:
      - text: Suggest articles for participant {participant} in global conversation {conversation}, project {project}.
        slots:
          participant: path.participantsId
          conversation: path.conversationsId
          project: path.projectsId
      - text: Recommend default-location articles to participant {participant} in conversation {conversation} using {context_size} messages.
        slots:
          participant: path.participantsId
          conversation: path.conversationsId
          context_size: requestBody.contextSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/conversations/{conversationsId}/participants/{participantsId}/suggestions:suggestKnowledgeAssist'].post
  update:
    x-apievangelist-phrasing:
      intent: Get Knowledge Assist for a participant
      effect: write
      questions:
      - Does Knowledge Assist work for participants on the global conversation endpoint?
      - Can default-location Knowledge Assist skip a query it already suggested?
      instructions:
      - text: Run Knowledge Assist for participant {participant} in global conversation {conversation}, project {project}.
        slots:
          participant: path.participantsId
          conversation: path.conversationsId
          project: path.projectsId
      - text: Get default-location Knowledge Assist for participant {participant} in conversation {conversation} excluding query {previous}.
        slots:
          participant: path.participantsId
          conversation: path.conversationsId
          previous: requestBody.previousSuggestedQuery
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/conversations/{conversationsId}/participants/{participantsId}/suggestions:suggestFaqAnswers'].post
  update:
    x-apievangelist-phrasing:
      intent: Suggest FAQ answers for a participant
      effect: write
      questions:
      - Can FAQ answers be suggested to a participant in a conversation on the global endpoint?
      - What context window applies to default-location FAQ answer suggestions?
      instructions:
      - text: Suggest FAQ answers for participant {participant} in global conversation {conversation}, project {project}.
        slots:
          participant: path.participantsId
          conversation: path.conversationsId
          project: path.projectsId
      - text: Propose default-location FAQ answers to participant {participant} in conversation {conversation} from {context_size} messages.
        slots:
          participant: path.participantsId
          conversation: path.conversationsId
          context_size: requestBody.contextSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/conversations/{conversationsId}/suggestions:generate'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate suggestions for a conversation
      effect: write
      questions:
      - Can I run all generators against a conversation on the global endpoint?
      - What trigger events can start suggestion generation for a default-location conversation?
      instructions:
      - text: Generate suggestions for global conversation {conversation} in project {project}.
        slots:
          conversation: path.conversationsId
          project: path.projectsId
      - text: Run default-location generators on conversation {conversation} for {trigger_events}.
        slots:
          conversation: path.conversationsId
          trigger_events: requestBody.triggerEvents
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/conversations/{conversationsId}/suggestions:searchKnowledge'].post
  update:
    x-apievangelist-phrasing:
      intent: Search knowledge within a conversation
      effect: read
      questions:
      - Can I search knowledge sources from within a conversation on the global endpoint?
      - Is a knowledge search tied to a default-location conversation's context?
      instructions:
      - text: Search knowledge for {query} inside global conversation {conversation}, project {project}.
        slots:
          query: requestBody.query
          conversation: path.conversationsId
          project: path.projectsId
      - text: Find answers to {query} for default-location conversation {conversation}.
        slots:
          query: requestBody.query
          conversation: path.conversationsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/conversations/{conversationsId}/suggestions:suggestConversationSummary'].post
  update:
    x-apievangelist-phrasing:
      intent: Summarize a conversation
      effect: write
      questions:
      - How do I get a summary of a conversation on the global endpoint?
      - Can I limit the default-location conversation summary to recent messages?
      instructions:
      - text: Suggest a summary for global conversation {conversation} in project {project}.
        slots:
          conversation: path.conversationsId
          project: path.projectsId
      - text: Summarize default-location conversation {conversation} using the last {context_size} messages.
        slots:
          conversation: path.conversationsId
          context_size: requestBody.contextSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/suggestions:generateStatelessSummary'].post
  update:
    x-apievangelist-phrasing:
      intent: Summarize a transcript without storing it
      effect: read
      questions:
      - Can I summarize a transcript I pass in directly, on the global endpoint, without a stored conversation?
      - Which conversation profile settings apply to a default-location stateless summary?
      instructions:
      - text: Generate a stateless summary for project {project} of the conversation {transcript}.
        slots:
          project: path.projectsId
          transcript: requestBody.statelessConversation
      - text: Summarize this inline transcript at the default location for project {project} with profile {profile}.
        slots:
          project: path.projectsId
          profile: requestBody.conversationProfile
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/suggestions:searchKnowledge'].post
  update:
    x-apievangelist-phrasing:
      intent: Search the knowledge base for a project
      effect: read
      questions:
      - Can I search my knowledge sources on the global endpoint without opening a conversation?
      - Does a project-wide default-location knowledge search support exact matching?
      instructions:
      - text: Search knowledge for {query} in project {project} at the global location.
        slots:
          query: requestBody.query
          project: path.projectsId
      - text: Run a default-location knowledge search on {query} for project {project} with profile {profile}.
        slots:
          query: requestBody.query
          project: path.projectsId
          profile: requestBody.conversationProfile
      method: generated
      generated: '2026-10-01'