CM.com Dtmf API

openapi: 3.2.0
info:
  title: Voice Dtmf API
  version: v2
servers:
- url: https://api.cm.com
security:
- X-CM-PRODUCTTOKEN: []
tags:
- name: Dtmf
paths:
  /voiceapi/v2/dtmf:
    post:
      tags:
      - Dtmf
      summary: DTMF
      description: Send out a call that requests DTMF input from the callee. For more information, see the Voice DTMF documentation.
      requestBody:
        description: Details of the DTMF instruction.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestDtmfInstruction'
          text/json:
            schema:
              $ref: '#/components/schemas/RequestDtmfInstruction'
          application/*+json:
            schema:
              $ref: '#/components/schemas/RequestDtmfInstruction'
      responses:
        '200':
          description: Call is queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallQueuedEvent'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionEvent'
        '401':
          description: Unauthorized
      operationId: postVoiceapiV2Dtmf
      x-operation-id-source: derived
components:
  schemas:
    Voice:
      title: Voice
      required:
      - gender
      - language
      - number
      type: object
      properties:
        language:
          maxLength: 6
          minLength: 5
          pattern: ^[a-zA-Z]{2,3}-[a-zA-Z]{2,3}$
          type: string
          description: 'The language (5 character locale) of the voice to use. Examples: en-US, en-GB, nl-NL. Defaults to en-GB'
          example: en-GB
        gender:
          $ref: '#/components/schemas/Gender'
        number:
          maximum: 2147483647
          minimum: 1
          type: integer
          description: 'Usually `1`, but if the selected language and gender support multiple voices, you can use this to make

            a selection between the different ones. To see the available voices, please see the

            <a href="/voice/tts/supported-languages">TTS voices documentation</a>.'
          format: int32
          example: 1
        volume:
          maximum: 4
          minimum: -4
          type: integer
          description: The volume level of the voice. Must be a value between -4 and 4. Defaults to 0.
          format: int32
          example: 2
        premium:
          type: boolean
          description: 'Whether to use a premium text-to-speech voice. Please be aware that additional costs will be charged for the

            use of premium voices. Defaults to `false`.'
          example: true
      additionalProperties: false
      description: The properties in this class are used to select the required TTS voice.
    ExceptionEvent:
      title: Exception Event
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: The Type of event.
          readOnly: true
        call-id:
          type: string
          description: The ID of the call this event belongs to.
          format: uuid
        instruction-id:
          type:
          - string
          - 'null'
          description: The ID of the instruction the event is a result of.
        queue-id:
          type:
          - string
          - 'null'
          description: The ID of the queue.
        code:
          $ref: '#/components/schemas/ExceptionEventCode'
        title:
          type:
          - string
          - 'null'
          description: The title of the exception.
          readOnly: true
        message:
          type:
          - string
          - 'null'
          description: Some explanatory text on the exception.
      additionalProperties: false
      description: And event containing an exception.
    Gender:
      title: Gender
      enum:
      - Male
      - Female
      type: string
      description: Genders supported by TTS.
    VoicemailResponse:
      title: Voicemail Response
      enum:
      - Ignore
      - Restart
      - Stop
      - Disconnect
      type: string
      description: The type that determines the flow of Voicemail detection.
    CallQueuedEvent:
      title: Call Queued Event
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: The Type of event.
          readOnly: true
        call-id:
          type: string
          description: The ID of the call this event belongs to.
          format: uuid
        instruction-id:
          type:
          - string
          - 'null'
          description: The ID of the instruction the event is a result of.
        queue-id:
          type:
          - string
          - 'null'
          description: The ID of the queue.
        caller:
          type:
          - string
          - 'null'
          description: The id (e.g. number) of the caller.
        callee:
          type:
          - string
          - 'null'
          description: The id (e.g. number) of the callee.
        success:
          type: boolean
          description: True if the PlaceCallInstruction was accepted.
        error:
          type:
          - string
          - 'null'
          description: True if the PlaceCallInstruction was accepted.
      additionalProperties: false
      description: 'Event that is a result (basically a direct response) to the PlaceCallInstruction.

        This one is generally used in the async versions of the calls.'
    PromptType:
      title: Prompt Type
      enum:
      - File
      - TTS
      - TTS_SSML
      type: string
      description: The type of the prompt, to distinguish between a filename and a string that needs to be tts-ed.
    ExceptionEventCode:
      title: Exception Event Code
      enum:
      - InvalidJson
      - SignatureError
      - FileNotFound
      - InvalidInstruction
      - InvalidParameter
      - InsufficientBalance
      - PremiumNotAllowed
      - CallLimitReached
      - TooManyNumbers
      type: string
      description: Enum of the different codes of exceptions.
    RequestDtmfInstruction:
      title: Request Dtmf Instruction
      required:
      - caller
      - prompt
      - valid-prompt
      type: object
      properties:
        instruction-id:
          maxLength: 64
          type:
          - string
          - 'null'
          description: 'Optional string that allows you to uniquely identify the placed outbound call. Its value is also included

            in the callback and Call Detail Records (CDRs).'
          example: mycustomid
        callee:
          maxLength: 24
          pattern: ^(\+|00)?[1-9]\d{6,14}$
          type:
          - string
          - 'null'
          description: 'The number to dial. When the number is invalid, the request will be rejected. Must be in valid international

            E.164 format.'
          example: '+31612345678'
        callees:
          pattern: ^(\+|00)?[1-9]\d{6,14}$
          maxItems: 100
          type:
          - array
          - 'null'
          items:
            type: string
          description: 'List of multiple numbers to dial. When the list contains one or more invalid numbers, the request will be

            rejected. Must be in valid international E.164 format.'
          example:
          - '+31612345678'
          - '+31612345679'
        caller:
          maxLength: 24
          minLength: 1
          pattern: ^(\+|00)?[1-9]\d{6,14}$
          type: string
          description: The caller ID to display on the recipient's phone. Must be in valid international E.164 format.
          example: '+31612345678'
        anonymous:
          type: boolean
          description: Indicates whether the caller ID should be hidden. Defaults to `false`.
          example: false
        callback-url:
          type:
          - string
          - 'null'
          description: 'URL that will be called when the call is finished. The body of this POST request will contain details about

            the call or calls.'
          format: uri
        max-ringing-timeout:
          maximum: 60
          minimum: 10
          type:
          - integer
          - 'null'
          description: 'Determines how long the Voice API will wait for the callee to answer the call. Cancels the ringing call

            after the timeout period exceeded. Defaults to `60`.'
          format: int32
          example: 60
        prompt:
          maxLength: 1000
          minLength: 1
          type: string
          description: 'The prompt to play which describes what DTMF input is requested from the callee. This can be either TTS or

            SSML, or the path to an audio file in your Voice Audio Manager.'
          example: Please enter some digits.
        prompt-type:
          $ref: '#/components/schemas/PromptType'
        valid-prompt:
          maxLength: 1000
          minLength: 1
          type: string
          description: The prompt to play when the . This can be either TTS or SSML, or the path to an audio file in your Voice Audio Manager.
          example: Thank you for your answer, the call will now be ended.
        valid-prompt-type:
          $ref: '#/components/schemas/PromptType'
        invalid-prompt:
          type:
          - string
          - 'null'
          description: The prompt, which is either the path and name of the file to play, or the string that needs to be tts-ed.
          example: This is not a valid input, please try again.
        invalid-prompt-type:
          $ref: '#/components/schemas/PromptType'
        min-digits:
          maximum: 64
          minimum: 1
          type:
          - integer
          - 'null'
          description: The minimum number of digits for the dtmf input.
          format: int32
          example: 3
        max-digits:
          maximum: 64
          minimum: 1
          type:
          - integer
          - 'null'
          description: The maximum number of digits for the dtmf input.
          format: int32
          example: 15
        max-attempts:
          maximum: 10
          minimum: 1
          type:
          - integer
          - 'null'
          description: The maximum number of attempts to input valid dtmf.
          format: int32
          example: 3
        timeout:
          maximum: 10000
          minimum: 1000
          type:
          - integer
          - 'null'
          description: 'The max. time in ms between the end of the prompt audio and the first digit, or between digits. If no digit

            is received before this timeout, it is counted as an attempt and the prompt is restarted. Value must be

            between 1000 and 10000 ms. Defaults to `5000`.'
          format: int32
          example: 5000
        terminators:
          type:
          - string
          - 'null'
          description: The keys that will end dtmf input. Usually `#` or `*`. Defaults to `#`.
          example: '#'
        regex:
          type:
          - string
          - 'null'
          description: 'The regex to match the input against. An attempt will fail if the input does not match this regular

            expression. Defaults to `[0-9]*`.'
          example: '[0-9]*'
        voice:
          $ref: '#/components/schemas/Voice'
        voicemail-response:
          $ref: '#/components/schemas/VoicemailResponse'
      additionalProperties: false
      description: Instruction to place a call and request DTMF from the callee.
  securitySchemes:
    X-CM-PRODUCTTOKEN:
      type: apiKey
      description: Your producttoken
      name: X-CM-PRODUCTTOKEN
      in: header
x-readme:
  explorer-enabled: true
  proxy-enabled: true