# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Phone Devices API
  version: 1.0.0
extends: openapi/zoom-phone-phone-devices-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: 11
- target: $.paths['/phone/devices'].get
  update:
    x-apievangelist-phrasing:
      intent: List desk phone devices
      effect: read
      questions:
      - Which desk phones on our account are still unassigned?
      - Can I filter desk phones by site, assignee type or whether their location is known?
      instructions:
      - text: List {type} desk phone devices.
        slots:
          type: query.type
      - text: List {type} desk phones at site {site_id} matching {keyword}.
        slots:
          type: query.type
          site_id: query.site_id
          keyword: query.keyword
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/devices'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a desk phone
      effect: write
      questions:
      - How do I register a new desk phone by its MAC address?
      - Can I add a desk phone and assign it to a user or common area in one step?
      instructions:
      - text: Add desk phone {display_name} with MAC address {mac_address} of type {type}.
        slots:
          display_name: requestBody.display_name
          mac_address: requestBody.mac_address
          type: requestBody.type
      - text: Add {type} phone {mac_address} named {display_name} and assign it to {assigned_to}.
        slots:
          type: requestBody.type
          mac_address: requestBody.mac_address
          display_name: requestBody.display_name
          assigned_to: requestBody.assigned_to
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/devices/sync'].post
  update:
    x-apievangelist-phrasing:
      intent: Resync zero-touch desk phones
      effect: write
      questions:
      - How do I push a resync to all our zero-touch provisioned desk phones?
      - How often am I allowed to resync desk phones for a site?
      instructions:
      - text: Resync all online desk phones at the {level} level.
        slots:
          level: requestBody.level
      - text: Resync desk phones at the {level} level for site {site_id}.
        slots:
          level: requestBody.level
          site_id: requestBody.site_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/devices/{deviceId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a desk phone's details
      effect: read
      questions:
      - What model, status and assignee does a specific desk phone have?
      - Can I check which provision template a desk phone uses?
      instructions:
      - text: Show desk phone {deviceId}.
        slots:
          deviceId: path.deviceId
      - text: Get the details of device {deviceId}.
        slots:
          deviceId: path.deviceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/devices/{deviceId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a desk phone or ATA
      effect: destructive
      questions:
      - How do I remove a desk phone or analog adapter from Zoom Phone?
      - What happens to a retired desk phone when I delete it from system management?
      instructions:
      - text: Delete desk phone {deviceId}.
        slots:
          deviceId: path.deviceId
      - text: Remove ATA device {deviceId} from Zoom Phone.
        slots:
          deviceId: path.deviceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/devices/{deviceId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a desk phone
      effect: write
      questions:
      - How do I rename a desk phone?
      - Can I reassign a desk phone or change its provision template in a general update?
      instructions:
      - text: Rename desk phone {deviceId} to {display_name}.
        slots:
          deviceId: path.deviceId
          display_name: requestBody.display_name
      - text: Update desk phone {deviceId} so it is assigned to {assigned_to}.
        slots:
          deviceId: path.deviceId
          assigned_to: requestBody.assigned_to
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/devices/{deviceId}/extensions'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign users or common areas to a desk phone
      effect: write
      questions:
      - How do I share one desk phone between several extensions?
      - Can I add a user's extension to a desk phone that's already set up?
      instructions:
      - text: Assign extensions {assignee_extension_ids} to desk phone {deviceId}.
        slots:
          deviceId: path.deviceId
          assignee_extension_ids: requestBody.assignee_extension_ids
      - text: Add extension {assignee_extension_ids} as an assignee of device {deviceId}.
        slots:
          deviceId: path.deviceId
          assignee_extension_ids: requestBody.assignee_extension_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/devices/{deviceId}/extensions/{extensionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unassign an extension from a desk phone
      effect: destructive
      questions:
      - How do I take one user off a shared desk phone?
      - Can I unassign a single assignee from a device and leave the rest?
      instructions:
      - text: Unassign extension {extensionId} from desk phone {deviceId}.
        slots:
          deviceId: path.deviceId
          extensionId: path.extensionId
      - text: Remove assignee {extensionId} from device {deviceId}.
        slots:
          deviceId: path.deviceId
          extensionId: path.extensionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/devices/{deviceId}/provision_templates'].put
  update:
    x-apievangelist-phrasing:
      intent: Set or clear a desk phone's provision template
      effect: write
      questions:
      - How do I apply a provision template to a desk phone?
      - Can I remove the provision template from a device?
      instructions:
      - text: Apply provision template {provision_template_id} to desk phone {deviceId}.
        slots:
          deviceId: path.deviceId
          provision_template_id: requestBody.provision_template_id
      - text: Clear the provision template on device {deviceId}.
        slots:
          deviceId: path.deviceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/devices/{deviceId}/reboot'].post
  update:
    x-apievangelist-phrasing:
      intent: Reboot a desk phone
      effect: write
      questions:
      - How do I remotely restart a frozen desk phone?
      - Can I reboot only zero-touch or assisted-provisioning phones remotely?
      instructions:
      - text: Reboot desk phone {deviceId}.
        slots:
          deviceId: path.deviceId
      - text: Restart device {deviceId} remotely.
        slots:
          deviceId: path.deviceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/smartphones'].get
  update:
    x-apievangelist-phrasing:
      intent: List smartphones configured with Zoom Phone
      effect: read
      questions:
      - Which smartphones are configured with Zoom Phone on our account?
      - Can I search smartphones by site or keyword?
      instructions:
      - text: List all smartphones configured with Zoom Phone.
      - text: List Zoom Phone smartphones at site {site_id} matching {keyword}.
        slots:
          site_id: query.site_id
          keyword: query.keyword
      method: generated
      generated: '2026-10-01'