# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Phone Common Areas API
  version: 1.0.0
extends: openapi/zoom-phone-common-areas-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: 19
- target: $.paths['/phone/common_areas'].get
  update:
    x-apievangelist-phrasing:
      intent: List common area phones
      effect: read
      questions:
      - Which common area phones are set up across our account?
      - Can I filter common areas by site or by device type?
      instructions:
      - text: List all common areas on the account.
      - text: List the common areas at site {site_id}.
        slots:
          site_id: query.site_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/common_areas'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a common area
      effect: write
      questions:
      - How do I set up a shared lobby phone as a common area?
      - Can I apply a template and calling plan when adding a common area?
      instructions:
      - text: Add a common area named {display_name}.
        slots:
          display_name: requestBody.display_name
      - text: Add common area {display_name} at site {site_id} with extension {extension_number}.
        slots:
          display_name: requestBody.display_name
          site_id: requestBody.site_id
          extension_number: requestBody.extension_number
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/common_areas/activation_code'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate activation codes for common areas
      effect: write
      questions:
      - How do I get activation codes so shared phones can sign in as common areas?
      - What is the most common areas I can generate activation codes for at once?
      instructions:
      - text: Generate activation codes for common areas {common_area_ids}.
        slots:
          common_area_ids: requestBody.common_area_ids
      - text: Create fresh activation codes for the shared phones {common_area_ids}.
        slots:
          common_area_ids: requestBody.common_area_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/common_areas/activation_codes'].get
  update:
    x-apievangelist-phrasing:
      intent: List common area activation codes
      effect: read
      questions:
      - Where can I see the activation codes already issued to our common areas?
      - Is there a list of every common area activation code on the account?
      instructions:
      - text: List the activation codes for our common areas.
      - text: Show {page_size} common area activation codes per page.
        slots:
          page_size: query.page_size
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/common_areas/template_id/{templateId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Apply a setting template to common areas
      effect: write
      questions:
      - Can I push one setting template to many common areas in bulk?
      - How many common areas can a template be applied to in a single request?
      instructions:
      - text: Apply template {templateId} to common areas {common_area_ids}.
        slots:
          templateId: path.templateId
          common_area_ids: requestBody.common_area_ids
      - text: Roll setting template {templateId} out to the common area phones.
        slots:
          templateId: path.templateId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/common_areas/{commonAreaId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a common area's details
      effect: read
      questions:
      - What extension and numbers does a particular common area phone have?
      - Where do I look up one common area's configuration?
      instructions:
      - text: Show details for common area {commonAreaId}.
        slots:
          commonAreaId: path.commonAreaId
      - text: Look up the extension and site of common area {commonAreaId}.
        slots:
          commonAreaId: path.commonAreaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/common_areas/{commonAreaId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a common area
      effect: destructive
      questions:
      - Can I remove a common area phone we no longer need?
      - What happens to a common area when it is deleted?
      instructions:
      - text: Delete common area {commonAreaId}.
        slots:
          commonAreaId: path.commonAreaId
      - text: Remove common area {commonAreaId} from the account.
        slots:
          commonAreaId: path.commonAreaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/common_areas/{commonAreaId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a common area's profile
      effect: write
      questions:
      - How do I change a common area's display name or extension?
      - Can I set a common area's outbound caller ID or emergency address?
      instructions:
      - text: Rename common area {commonAreaId} to {display_name}.
        slots:
          commonAreaId: path.commonAreaId
          display_name: requestBody.display_name
      - text: Set the outbound caller ID of common area {commonAreaId} to {outbound_caller_id}.
        slots:
          commonAreaId: path.commonAreaId
          outbound_caller_id: requestBody.outbound_caller_id
      - text: Move common area {commonAreaId} to site {site_id}.
        slots:
          commonAreaId: path.commonAreaId
          site_id: requestBody.site_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/common_areas/{commonAreaId}/call_handling/settings'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a common area's call handling for an hour type
      effect: read
      questions:
      - What happens to calls to a lobby phone after business hours?
      - Can I see a common area's call handling for a holiday?
      instructions:
      - text: Show the call handling setting of common area {commonAreaId}.
        slots:
          commonAreaId: path.commonAreaId
      - text: Show common area {commonAreaId}'s call handling during {hour_type} hours.
        slots:
          commonAreaId: path.commonAreaId
          hour_type: query.hour_type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/common_areas/{commonAreaId}/call_handling/settings/{hourType}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a common area's call handling for an hour type
      effect: write
      questions:
      - How do I forward a common area phone's calls during closed hours?
      - Can I change call distribution on a shared phone for business hours?
      instructions:
      - text: Update common area {commonAreaId}'s call handling for {hourType} hours.
        slots:
          commonAreaId: path.commonAreaId
          hourType: path.hourType
      - text: Set common area {commonAreaId} {hourType}-hours call handling to {call_handling_setting}.
        slots:
          commonAreaId: path.commonAreaId
          hourType: path.hourType
          call_handling_setting: requestBody.call_handling_setting
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/common_areas/{commonAreaId}/calling_plans'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign calling plans to a common area
      effect: write
      questions:
      - How do I give a common area phone a calling plan so it can dial out?
      - Can more than one calling plan be assigned to a shared phone?
      instructions:
      - text: Assign calling plans {calling_plans} to common area {commonAreaId}.
        slots:
          calling_plans: requestBody.calling_plans
          commonAreaId: path.commonAreaId
      - text: Give common area {commonAreaId} the calling plan {calling_plans}.
        slots:
          calling_plans: requestBody.calling_plans
          commonAreaId: path.commonAreaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/common_areas/{commonAreaId}/calling_plans/{type}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a calling plan from a common area
      effect: destructive
      questions:
      - Can I take a calling plan away from a common area phone?
      - Which billing account does unassigning a common area plan apply to?
      instructions:
      - text: Unassign calling plan type {type} from common area {commonAreaId}.
        slots:
          type: path.type
          commonAreaId: path.commonAreaId
      - text: Remove plan {type} from common area {commonAreaId} under billing account {billing_account_id}.
        slots:
          type: path.type
          commonAreaId: path.commonAreaId
          billing_account_id: query.billing_account_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/common_areas/{commonAreaId}/phone_numbers'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign phone numbers to a common area
      effect: write
      questions:
      - How do I give a lobby phone its own direct phone number?
      - Can several numbers be assigned to one common area?
      instructions:
      - text: Assign phone numbers {phone_numbers} to common area {commonAreaId}.
        slots:
          phone_numbers: requestBody.phone_numbers
          commonAreaId: path.commonAreaId
      - text: Give common area {commonAreaId} the direct number {phone_numbers}.
        slots:
          phone_numbers: requestBody.phone_numbers
          commonAreaId: path.commonAreaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/common_areas/{commonAreaId}/phone_numbers/{phoneNumberId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unassign a phone number from a common area
      effect: destructive
      questions:
      - Can I take a direct number back from a common area phone?
      - What frees up a number currently assigned to a shared phone?
      instructions:
      - text: Unassign phone number {phoneNumberId} from common area {commonAreaId}.
        slots:
          phoneNumberId: path.phoneNumberId
          commonAreaId: path.commonAreaId
      - text: Free number {phoneNumberId} from shared phone {commonAreaId}.
        slots:
          phoneNumberId: path.phoneNumberId
          commonAreaId: path.commonAreaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/common_areas/{commonAreaId}/pin_code'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a common area's PIN code
      effect: write
      questions:
      - How do I reset the PIN on a common area phone?
      - Can an admin change a shared phone's PIN when PIN viewing is restricted?
      instructions:
      - text: Set the PIN code of common area {commonAreaId} to {pin_code}.
        slots:
          commonAreaId: path.commonAreaId
          pin_code: requestBody.pin_code
      - text: Reset common area {commonAreaId}'s PIN to {pin_code}.
        slots:
          commonAreaId: path.commonAreaId
          pin_code: requestBody.pin_code
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/common_areas/{commonAreaId}/settings'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a common area's settings
      effect: read
      questions:
      - What settings, like desk phone configuration, does a common area have?
      - Can I read only one setting type for a shared phone?
      instructions:
      - text: Show the settings of common area {commonAreaId}.
        slots:
          commonAreaId: path.commonAreaId
      - text: Show common area {commonAreaId}'s {setting_type} settings.
        slots:
          commonAreaId: path.commonAreaId
          setting_type: query.setting_type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/common_areas/{commonAreaId}/settings/{settingType}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a setting to a common area by type
      effect: write
      questions:
      - Can I add a new setting entry of a given type to a common area?
      - How is a typed setting added to a shared phone for the first time?
      instructions:
      - text: Add a {settingType} setting to common area {commonAreaId}.
        slots:
          settingType: path.settingType
          commonAreaId: path.commonAreaId
      - text: Create a new {settingType} entry on shared phone {commonAreaId}.
        slots:
          settingType: path.settingType
          commonAreaId: path.commonAreaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/common_areas/{commonAreaId}/settings/{settingType}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a common area setting from desk phones
      effect: destructive
      questions:
      - How do I remove a common area subsetting from a desk phone?
      - Can I delete a holiday entry from a common area's settings?
      instructions:
      - text: Delete the {settingType} setting from common area {commonAreaId}.
        slots:
          settingType: path.settingType
          commonAreaId: path.commonAreaId
      - text: Remove common area {commonAreaId}'s {settingType} setting from device {device_id}.
        slots:
          settingType: path.settingType
          commonAreaId: path.commonAreaId
          device_id: query.device_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/common_areas/{commonAreaId}/settings/{settingType}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a common area setting by type
      effect: write
      questions:
      - Can I edit an existing typed setting on a common area?
      - How do I modify a shared phone setting that is already in place?
      instructions:
      - text: Update the {settingType} setting on common area {commonAreaId}.
        slots:
          settingType: path.settingType
          commonAreaId: path.commonAreaId
      - text: Modify the existing {settingType} entry for shared phone {commonAreaId}.
        slots:
          settingType: path.settingType
          commonAreaId: path.commonAreaId
      method: generated
      generated: '2026-10-01'