openapi: 3.0.4
info:
  title: Voice API
  description: |-
    Welcome to the Voxtelesys Voice REST API. This API offers an easy, secure solution to create and control voice calls. If you have questions or would like more information, please reach out to support.
  version: v0
servers:
  - url: https://voiceapi.voxtelesys.net/api/v0
paths:
  /calls:
    post:
      tags:
        - Calls
      security:
        - OAuth2: ['voiceapi:call:manage']
      summary: Create a call
      description: Endpoint for creating a new outgoing call. The created call will execute the provided VoXML upon answer.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendCall"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/responseSchemas/Call"
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://authapi.voxtelesys.net/api/v1/oauth/token
          scopes:
            voiceapi:call:manage: Create, update, and delete calls
  schemas:
    Call:
      type: object
      properties:
          to:
            type: string
            example: "+15556667777"
            description: The number to dial in E.164 format.
            required: true
          from:
            type: string
            example: "+15556668888"
            description: The number to originate the call from in E.164 format.
            required: true
          voice_trunk_group_id:
            type: number
            example: 90001
            description: The outbound trunk group to use for the outgoing call.
            required: true
          voxxml:
            type: string
            example: <Response><Say voice='Joanna' language='en-US'>Hello!</Say></Response>
            description: VoXML to execute after connecting. If both `voxxml` and `url` are present, then `voxxml` will not be used.
          flow_guid:
            type: string
            example: 4185fb1e-d696-40d4-9485-c71154af2d53
            description: The GUID of the Flow to be executed. Execution of the Flow will begin at the "Outbound Call" action on the start widget of the Flow.
          timeout:
            type: integer
            minimum: 0
            maximum: 600
            example: 120
            description: The integer number of seconds to allow before ending the call due to no answer. Defaults to 60 seconds.
          url:
            type: string
            format: uri
            example: https://example.com
            description: URL to download VoXML from. If `url` is present, it will be used instead of `voxxml`.
          method:
            type: string
            enum: ["GET", "POST"]
            example: GET
            description: Method to use when fetching XML via the provided URL. Defaults to `POST`.
          tag:
            type: string
            example: 	261f6924-6982-11ea-bc55-0242ac130003
            description: String which will be included in callback events (max 256 chars). Typically used to store an identifier for the call.
          bulk_tag:
            type: string
            example: 	4de1d075-2a7e-404e-abac-3f80560db42f
            description: String which will be included in callback events (max 256 chars). Typically used to store an identifier for a batch of calls.
          status_callback:
            type: object
            description: Information for receiving HTTP callbacks when the status of the call changes.
            properties:
              url:
                type: string
                format: uri
                example: http://example.com
                description: The absolute URL to send callbacks to when the status of the call is updated.
              method:
                type: string
                enum: ["GET", "POST"]
                example: POST
                description: The HTTP method to use for status callbacks. Defaults to `POST`.
              events:
                type: array
                items:
                  type: string
                  enum: ["completed", "failed", "busy", "no-answer"]
                description: The call statuses for which callbacks should be sent. Defaults to `completed`.
            required:
              - url
          record:
            type: boolean
            example: true
            description: If true, the entire call will be recorded. Defaults to `false`.
          recording_track:
            type: string
            enum: ["inbound", "outbound", "both"]
            example: inbound
            description: Sets which side of the call to record. Defaults to `both`. `outbound` records only the audio generated by the VoXML, and `inbound` records only the callee's voice.
          recording_channel:
            type: string
            enum: ["mono", "dual"]
            example: dual
            description: Sets the number of channels in the audio recording file. Defaults to `mono`.
          recording_status_callback:
            type: string
            format: uri
            example: http://example.com
            description: The absolute URL to send callbacks to when the status of the recording is updated.
          recording_status_callback_method:
            type: string
            enum: ["GET", "POST"]
            example: GET
            description: The HTTP method to use for recording status callbacks.
          recording_status_callback_event:
            type: string
            enum: ["in-progress", "completed", "failed"]
            examples:
            - in-progress completed failed
            - in-progress,completed,failed
            description: The recording statuses for which callbacks should be sent. Defaults to `completed`.
          machine_detection:
            type: string
            enum: ["enable", "detect_message_end"]
            example: enable
            description: |
              `machine_detection` enables answering machine detection on the call. The result of answering machine detection will be provided by the `AnsweredBy` field in the body of the HTTP request to fetch VoXML.
              When `enable` is specified, the result will be returned as soon as a human or machine is detected on the call.
              When `detect_message_end` is specified, the result will be returned immediately when a human is detected or once a machine has finished its message.
          machine_detection_timeout:
            type: integer
            minimum: 3
            maximum: 59
            example: 30
            description: The number of seconds to perform answering machine detection before timing out. If `machine_detection_timeout` is reached, then `unknown` will be returned.
          machine_detection_human_residence_speech_threshold:
            type: integer
            minimum: 1000
            maximum: 6000
            example: 2000
            description: The maximum number of milliseconds of speech that can be classified as a human in residence.
          machine_detection_human_business_speech_threshold:
            type: integer
            minimum: 1000
            maximum: 6000
            example: 3200
            description: The maximum number of milliseconds of speech that can be classified as a human in business.
          machine_detection_machine_speech_end_threshold:
            type: integer
            minimum: 500
            maximum: 5000
            example: 1000
            description: The number of milliseconds of silence to allow after speech before the speech is considered complete.
          machine_detection_silence_timeout:
            type: integer
            minimum: 2000
            maximum: 10000
            example: 5000
            description: The maximum number of milliseconds of silence to allow before returning an `unknown` result.
    SendCall:
      allOf:
        - $ref: "#/components/schemas/Call"
        - required:
          - to
          - from
          - voice_trunk_group_id
  responseSchemas:
    Call:
      type: object
      properties:
        string:
          type: string
          example: queued
