openapi: 3.2.0
info:
  title: wazo-confd Ivr API
  description: "Confd exposes an API for managing core resources on a Wazo server such as users, extensions, devices, voicemails, queues, etc. Resources can be associated together to provide additional functionality. For example: By associating a voicemail with a user, calls will automatically fallback on to the voicemail when the user cannot answer.\n\nImplementation notes\n====================\n\nErrors\n------\n\nResponses containing errors will have a status code in the 400 or 500 class. A list of error messages will be returned in the body of the response as a JSON-encoded array:\n\n~~~\n[\n    \"Input error - User not found\",\n    \"Resource error - User not associated to a line\"\n]\n~~~\n\n\nUpdating resources via PUT\n--------------------------\n\nWhen updating a resource, all fields become optional. In other words, only values that have been changed need to be sent to the server. Please note that this behavior may change in future versions of the API."
  version: '1.1'
  license:
    name: GPL v3
    url: http://www.gnu.org/licenses/gpl.txt
  contact:
    name: Wazo Dev Team
    url: https://wazo-platform.org/
    email: dev@wazo.community
  x-logo:
    url: https://wazo-platform.org/images/logo-black.svg
    backgroundColor: '#FAFAFA'
    altText: Wazo Logo
servers:
- url: /1.1
security:
- wazo_auth_token: []
tags:
- name: ivr
paths:
  /ivr:
    get:
      operationId: list_ivr
      summary: List IVR
      description: '**Required ACL:** `confd.ivr.read`'
      tags:
      - ivr
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/recurse'
      - $ref: '#/components/parameters/order'
      - $ref: '#/components/parameters/direction'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/search'
      responses:
        '200':
          description: IVR list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IvrItems'
    post:
      operationId: create_ivr
      summary: Create IVR
      description: '**Required ACL:** `confd.ivr.create`'
      tags:
      - ivr
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      responses:
        '201':
          description: IVR created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ivr'
        '400':
          $ref: '#/components/responses/CreateError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Ivr'
        description: IVR to create
        required: true
  /ivr/{ivr_id}:
    get:
      operationId: get_ivr
      summary: Get IVR
      description: '**Required ACL:** `confd.ivr.{ivr_id}.read`'
      tags:
      - ivr
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/ivrid'
      responses:
        '200':
          description: IVR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ivr'
        '404':
          $ref: '#/components/responses/NotFoundError'
    put:
      operationId: update_ivr
      summary: Update IVR
      description: '**Required ACL:** `confd.ivr.{ivr_id}.update`'
      tags:
      - ivr
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/ivrid'
      responses:
        '204':
          $ref: '#/components/responses/ResourceUpdated'
        '400':
          $ref: '#/components/responses/UpdateError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Ivr'
        required: true
    delete:
      operationId: delete_ivr
      summary: Delete IVR
      description: '**Required ACL:** `confd.ivr.{ivr_id}.delete`'
      tags:
      - ivr
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/ivrid'
      responses:
        '204':
          $ref: '#/components/responses/ResourceDeleted'
        '400':
          $ref: '#/components/responses/DeleteError'
        '404':
          $ref: '#/components/responses/NotFoundError'
components:
  responses:
    NotFoundError:
      description: The resource requested was not found on the server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ResourceDeleted:
      description: Resource was deleted successfully
    ResourceUpdated:
      description: Resource was updated successfully
    CreateError:
      description: An error occurred when creating the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UpdateError:
      description: An error occurred when updating the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    DeleteError:
      description: An error occurred when deleting the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    DestinationApplicationDISA:
      title: DestinationApplicationDISA
      allOf:
      - $ref: '#/components/schemas/DestinationApplication'
      - properties:
          application:
            type: string
            description: MUST be 'disa'
          context:
            type: integer
            description: The context of the application
          pin:
            type: string
            description: the pin of the application
        required:
        - application
        - context
    DestinationApplicationDirectory:
      title: DestinationApplicationDirectory
      allOf:
      - $ref: '#/components/schemas/DestinationApplication'
      - properties:
          application:
            type: string
            description: MUST be 'directory'
          context:
            type: integer
            description: The context of the application
        required:
        - application
        - context
    IvrRelationIncall:
      allOf:
      - $ref: '#/components/schemas/IncallRelationBase'
      - $ref: '#/components/schemas/IncallRelationExtensions'
    DestinationUser:
      title: DestinationUser
      properties:
        type:
          type: string
          description: MUST be 'user'
        user_id:
          type: integer
          description: The id of the user
        ring_time:
          type: number
          format: float
        moh_uuid:
          type: string
          description: The UUID of the music on hold to use instead of a ringback tone.
      required:
      - type
      - user_id
    DestinationOutcall:
      title: DestinationOutcall
      properties:
        type:
          type: string
          description: MUST be 'outcall'
        exten:
          type: string
        outcall_id:
          type: integer
          description: The id of the outcall
      required:
      - type
      - exten
      - outcall_id
    DestinationHangup:
      title: DestinationHangup
      properties:
        type:
          type: string
          description: MUST be 'hangup'
      required:
      - type
    DestinationQueue:
      title: DestinationQueue
      properties:
        type:
          type: string
          description: MUST be 'queue'
        queue_id:
          type: integer
          description: The id of the queue
        ring_time:
          type: number
          format: float
        skill_rule_id:
          type: integer
          description: The id of the skill rule
        skill_rule_variables:
          type: object
          description: key-value where key represents the variable of the skill rule and value represents a value
      required:
      - type
      - queue_id
    DestinationConference:
      title: DestinationConference
      properties:
        type:
          type: string
          description: MUST be 'conference'
        conference_id:
          type: integer
          description: The id of the conference
      required:
      - type
      - conference_id
    DestinationGroup:
      title: DestinationGroup
      properties:
        type:
          type: string
          description: MUST be 'group'
        group_id:
          type: integer
          description: The id of the group
        ring_time:
          type: number
          format: float
      required:
      - type
      - group_id
    DestinationHangupNormal:
      title: DestinationHangupNormal
      allOf:
      - $ref: '#/components/schemas/DestinationHangup'
      - properties:
          cause:
            type: string
            description: MUST be 'normal'
      required:
      - cause
    DestinationApplicationVoicemail:
      title: DestinationApplicationVoicemail
      allOf:
      - $ref: '#/components/schemas/DestinationApplication'
      - properties:
          application:
            type: string
            description: MUST be 'voicemail'
          context:
            type: integer
            description: The context of the application
        required:
        - application
        - context
    IvrItems:
      title: IvrItems
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Ivr'
        total:
          type: integer
      required:
      - total
    Ivr:
      title: IVR
      allOf:
      - properties:
          id:
            type: integer
            readOnly: true
            description: The id of the IVR
          tenant_uuid:
            type: string
            description: The UUID of the tenant
            readOnly: true
          name:
            type: string
            description: The name of the IVR
          description:
            type: string
            description: Additional information about the IVR
          greeting_sound:
            type: string
            description: The sound played to greet the caller
          menu_sound:
            type: string
            description: The sound played to prompt the caller for input
          invalid_sound:
            type: string
            description: The sound played when the caller choose an invalid option. Not used if an invalid destination is set
          abort_sound:
            type: string
            description: The sound played when the caller reach the maximum number of tries. Not used if an abort destination is set
          timeout:
            type: integer
            default: 5
            description: Number of seconds to wait after the menu sound is played before either replaying the menu, redirecting the call to the timeout destination (if set) or aborting the call (if the maximum number of tries has been reached)
          max_tries:
            type: integer
            default: 3
            description: The maximum number of tries before aborting the call. Both a timeout and an invalid choice counts toward the number of tries
          invalid_destination:
            description: The destination to redirect the caller to when he choose an invalid option. If not set, the menu will be replayed
            $ref: '#/components/schemas/DestinationType'
          timeout_destination:
            description: The destination to redirect the caller to on timeout. If not set, the menu will be replayed
            $ref: '#/components/schemas/DestinationType'
          abort_destination:
            description: The destination to redirect the caller to when the maximum number of tries is reached. If not set, the call will be hanged up after playing the abort sound (if set)
            $ref: '#/components/schemas/DestinationType'
          choices:
            type: array
            description: The menu's choices
            items:
              $ref: '#/components/schemas/IvrChoice'
      - $ref: '#/components/schemas/IvrRelationIncalls'
      - required:
        - name
        - menu_sound
      example:
        name: ivr1
        description: My IVR
        greeting_sound: /var/lib/wazo/sounds/playback/ivr1-greeting
        menu_sound: /var/lib/wazo/sounds/playback/ivr1-menu
        abort_destination:
          type: group
          group_id: 1
        choices:
        - exten: '1'
          destination:
            type: user
            user_id: 2
        - exten: '0'
          destination:
            type: group
            group_id: 1
    DestinationHangupBusy:
      title: DestinationHangupBusy
      allOf:
      - $ref: '#/components/schemas/DestinationHangup'
      - properties:
          cause:
            type: string
            description: MUST be 'busy'
          timeout:
            type: integer
            description: The timeout of the hangup
      required:
      - cause
    DestinationHangupCause:
      title: DestinationHangupCause
      properties:
        busy:
          $ref: '#/components/schemas/DestinationHangupBusy'
        congestion:
          $ref: '#/components/schemas/DestinationHangupCongestion'
        normal:
          $ref: '#/components/schemas/DestinationHangupNormal'
    DestinationApplication:
      title: DestinationApplication
      properties:
        type:
          type: string
          description: MUST be 'application'
      required:
      - type
    IvrChoice:
      title: IvrChoice
      properties:
        destination:
          description: The destination to redirect the caller to when this choice is selected
          $ref: '#/components/schemas/DestinationType'
        exten:
          type: string
          description: 'The extension the caller has to dial to select this choice. Can be an asterisk extension pattern, digits (0-9), * or #'
          pattern: ^_[*#0-9_XxZzNn\[\].!-]{1,39}$|[*#0-9]{1,40}$
      required:
      - destination
      - exten
    DestinationType:
      title: DestinationType
      properties:
        application:
          $ref: '#/components/schemas/DestinationApplicationApplication'
        conference:
          $ref: '#/components/schemas/DestinationConference'
        custom:
          $ref: '#/components/schemas/DestinationCustom'
        extension:
          $ref: '#/components/schemas/DestinationExtension'
        group:
          $ref: '#/components/schemas/DestinationGroup'
        hangup:
          $ref: '#/components/schemas/DestinationHangupCause'
        ivr:
          $ref: '#/components/schemas/DestinationIVR'
        none:
          $ref: '#/components/schemas/DestinationNone'
        outcall:
          $ref: '#/components/schemas/DestinationOutcall'
        queue:
          $ref: '#/components/schemas/DestinationQueue'
        sound:
          $ref: '#/components/schemas/DestinationSound'
        switchboard:
          $ref: '#/components/schemas/DestinationSwitchboard'
        user:
          $ref: '#/components/schemas/DestinationUser'
        voicemail:
          $ref: '#/components/schemas/DestinationVoicemail'
    IncallRelationExtensions:
      properties:
        extensions:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/ExtensionRelationBase'
    DestinationCustom:
      title: DestinationCustom
      properties:
        type:
          type: string
          description: MUST be 'custom'
        command:
          type: string
          description: The command to execute
      required:
      - type
      - command
    DestinationIVR:
      title: DestinationIVR
      properties:
        type:
          type: string
          description: MUST be 'ivr'
        ivr_id:
          type: integer
          description: The id of the IVR
      required:
      - type
      - ivr_id
    DestinationSound:
      title: DestinationSound
      properties:
        type:
          type: string
          description: MUST be 'sound'
        filename:
          type: string
          description: The filename of the sound. The file MUST be imported by to webi in the playback directory. The extension of file SHOULD be not present.
        skip:
          type: boolean
          description: Do not play this sound if the call is not answered
        no_answer:
          type: boolean
          description: Play this sound without answering the call
      required:
      - type
      - filename
    ExtensionRelationBase:
      properties:
        id:
          type: integer
          description: Extension ID
          readOnly: true
        context:
          type: string
        exten:
          type: string
    DestinationHangupCongestion:
      title: DestinationHangupCongestion
      allOf:
      - $ref: '#/components/schemas/DestinationHangup'
      - properties:
          cause:
            type: string
            description: MUST be 'congestion'
          timeout:
            type: integer
            description: The timeout of the hangup
      required:
      - cause
    DestinationApplicationCustom:
      title: DestinationApplicationCustom
      allOf:
      - $ref: '#/components/schemas/DestinationApplication'
      - properties:
          application:
            type: string
            description: MUST be 'custom'
          application_uuid:
            type: string
            description: The UUID of the application.
      required:
      - application
      - application_uuid
    IvrRelationIncalls:
      properties:
        incalls:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/IvrRelationIncall'
    DestinationVoicemail:
      title: DestinationVoicemail
      properties:
        type:
          type: string
          description: MUST be 'voicemail'
        voicemail_id:
          type: integer
          description: The id of the voicemail
        skip_instructions:
          type: boolean
          description: Skip the playback of instructions for leaving a message
        greeting:
          type: string
          enum:
          - busy
          - unavailable
          description: Play the specified greeting
      required:
      - type
      - voicemail_id
    DestinationApplicationApplication:
      title: DestinationApplicationApplication
      properties:
        callback_disa:
          $ref: '#/components/schemas/DestinationApplicationCallbackDISA'
        custom:
          $ref: '#/components/schemas/DestinationApplicationCustom'
        directory:
          $ref: '#/components/schemas/DestinationApplicationDirectory'
        disa:
          $ref: '#/components/schemas/DestinationApplicationDISA'
        fax_to_mail:
          $ref: '#/components/schemas/DestinationApplicationFaxToMail'
        voicemail:
          $ref: '#/components/schemas/DestinationApplicationVoicemail'
    DestinationSwitchboard:
      title: DestinationSwitchboard
      properties:
        type:
          type: string
          description: MUST be 'switchboard'
        switchboard_uuid:
          type: string
          description: The UUID of the switchboard.
      required:
      - type
      - switchboard_uuid
    DestinationApplicationCallbackDISA:
      title: DestinationApplicationCallbackDISA
      allOf:
      - $ref: '#/components/schemas/DestinationApplication'
      - properties:
          application:
            type: string
            description: MUST be 'callback_disa'
          context:
            type: integer
            description: The context of the application
          pin:
            type: string
            description: the pin of the application
        required:
        - application
        - context
    DestinationApplicationFaxToMail:
      title: DestinationApplicationFaxToMail
      allOf:
      - $ref: '#/components/schemas/DestinationApplication'
      - properties:
          application:
            type: string
            description: MUST be 'fax_to_mail'
          email:
            type: string
            description: The email of the application
      required:
      - application
      - email
    Error:
      type: array
      items:
        type: string
    IncallRelationBase:
      title: IncallRelation
      properties:
        id:
          type: integer
          readOnly: true
          description: The id of the incoming call
    DestinationNone:
      title: DestinationNone
      properties:
        type:
          type: string
          description: MUST be 'none'
      required:
      - type
    DestinationExtension:
      title: DestinationExtension
      properties:
        type:
          type: string
          description: MUST be 'extension'
        exten:
          type: string
        context:
          type: string
          description: Context of the extension
      required:
      - type
      - exten
      - context
  parameters:
    tenantuuid:
      name: Wazo-Tenant
      in: header
      description: The tenant's UUID, defining the ownership of a given resource.
      required: false
      schema:
        type: string
    ivrid:
      required: true
      name: ivr_id
      in: path
      description: IVR's ID
      schema:
        type: integer
    offset:
      required: false
      name: offset
      in: query
      description: Number of items to skip over in the list. Useful for pagination.
      schema:
        type: integer
    order:
      required: false
      name: order
      in: query
      description: Name of the field to use for sorting the list of items returned.
      schema:
        type: string
    direction:
      required: false
      name: direction
      in: query
      description: Sort list of items in 'asc' (ascending) or 'desc' (descending) order
      schema:
        type: string
        enum:
        - asc
        - desc
    recurse:
      name: recurse
      in: query
      description: Should the query include sub-tenants
      required: false
      schema:
        type: boolean
        default: false
    search:
      required: false
      name: search
      in: query
      description: Search term for filtering a list of items. Only items with a field containing the search term will be returned.
      schema:
        type: string
    limit:
      required: false
      name: limit
      in: query
      description: Maximum number of items to return in the list
      schema:
        type: integer
  securitySchemes:
    wazo_auth_token:
      type: apiKey
      name: X-Auth-Token
      in: header
x-xivo-port: 9486
x-xivo-name: confd
x-apievangelist-source:
  harvested_from: https://github.com/wazo-platform/wazo-confd
  assembly: base plugin api.yml deep-merged with all plugin api.yml fragments, reproducing what the running service serves at /api/confd/1.1/api/api.yml (see wazo_confd/plugins/api/http.py — xivo.chain_map.ChainMap)
  spec_version: Swagger 2.0 (as published by Wazo)
  harvested: '2026-08-17'