API Evangelist conversational phrasing for Dialogflow ES API (v2) Conversations API

# 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) Conversations API
  version: 1.0.0
extends: openapi/google-dialogflow-conversations-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: 9
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/conversations/{conversationsId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a regional conversation
      effect: read
      questions:
      - Can I look up the state of one Agent Assist conversation stored in a specific region?
      - Where do I check which conversation profile a regional conversation uses?
      instructions:
      - text: Get conversation {conversation} in project {project}, location {location}.
        slots:
          conversation: path.conversationsId
          project: path.projectsId
          location: path.locationsId
      - text: Show the lifecycle state of regional conversation {conversation} in {location}, project {project}.
        slots:
          conversation: path.conversationsId
          location: path.locationsId
          project: path.projectsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/conversations/{conversationsId}:complete'].post
  update:
    x-apievangelist-phrasing:
      intent: Complete a regional conversation
      effect: destructive
      questions:
      - How do I end an Agent Assist conversation in a specific location?
      - Can a regional conversation be reopened once I mark it complete?
      instructions:
      - text: Complete conversation {conversation} in project {project}, location {location}.
        slots:
          conversation: path.conversationsId
          project: path.projectsId
          location: path.locationsId
      - text: Close out regional conversation {conversation} in {location} for project {project}.
        slots:
          conversation: path.conversationsId
          location: path.locationsId
          project: path.projectsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/conversations'].get
  update:
    x-apievangelist-phrasing:
      intent: List conversations in a region
      effect: read
      questions:
      - Which conversations exist in one region of my project?
      - Can I filter regional conversations to only those still in progress?
      instructions:
      - text: List conversations in project {project}, location {location}.
        slots:
          project: path.projectsId
          location: path.locationsId
      - text: Show regional conversations in {location} for project {project} matching {filter}.
        slots:
          location: path.locationsId
          project: path.projectsId
          filter: query.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/conversations'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a conversation in a region
      effect: write
      questions:
      - How do I start a new Agent Assist conversation in a particular location?
      - Can I choose my own ID for a regional conversation?
      instructions:
      - text: Create a conversation in project {project}, location {location}, using conversation profile {profile}.
        slots:
          project: path.projectsId
          location: path.locationsId
          profile: requestBody.conversationProfile
      - text: Start regional conversation {conversation_id} in {location} for project {project}.
        slots:
          conversation_id: query.conversationId
          location: path.locationsId
          project: path.projectsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/conversations/{conversationsId}:ingestContextReferences'].post
  update:
    x-apievangelist-phrasing:
      intent: Add context references to a conversation
      effect: write
      questions:
      - Can I attach extra context documents to a conversation for generators to use?
      - What kind of context references can be ingested into an existing conversation?
      instructions:
      - text: Ingest context references {references} into conversation {conversation}, project {project}, location {location}.
        slots:
          references: requestBody.contextReferences
          conversation: path.conversationsId
          project: path.projectsId
          location: path.locationsId
      - text: Attach the context {references} to regional conversation {conversation}.
        slots:
          references: requestBody.contextReferences
          conversation: path.conversationsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/conversations/{conversationsId}:complete'].post
  update:
    x-apievangelist-phrasing:
      intent: Complete a conversation
      effect: destructive
      questions:
      - Can I mark a conversation on the global endpoint as finished?
      - What happens to a default-location conversation after it is completed?
      instructions:
      - text: Complete global conversation {conversation} in project {project}.
        slots:
          conversation: path.conversationsId
          project: path.projectsId
      - text: End default-location conversation {conversation} for project {project}.
        slots:
          conversation: path.conversationsId
          project: path.projectsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/conversations'].get
  update:
    x-apievangelist-phrasing:
      intent: List conversations in a project
      effect: read
      questions:
      - Which conversations does my project have at the global location?
      - Can I filter default-location conversations by lifecycle state?
      instructions:
      - text: List the global conversations in project {project}.
        slots:
          project: path.projectsId
      - text: Show project {project}'s default-location conversations filtered by {filter}.
        slots:
          project: path.projectsId
          filter: query.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/conversations'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a conversation in a project
      effect: write
      questions:
      - How can I open a new conversation on the global endpoint?
      - Which conversation profile does a default-location conversation need?
      instructions:
      - text: Create a global conversation in project {project} with profile {profile}.
        slots:
          project: path.projectsId
          profile: requestBody.conversationProfile
      - text: Start default-location conversation {conversation_id} in project {project}.
        slots:
          conversation_id: query.conversationId
          project: path.projectsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/conversations/{conversationsId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a conversation
      effect: read
      questions:
      - Can I fetch one conversation from the global endpoint by ID?
      - Is a default-location conversation still active or already completed?
      instructions:
      - text: Get global conversation {conversation} in project {project}.
        slots:
          conversation: path.conversationsId
          project: path.projectsId
      - text: Check the state of default-location conversation {conversation} for project {project}.
        slots:
          conversation: path.conversationsId
          project: path.projectsId
      method: generated
      generated: '2026-10-01'