Sinch Callouts API

openapi: 3.2.0
info:
  title: Sinch Voice Callouts API
  description: The Sinch Voice API is a programmable voice platform that allows developers to make, receive, and manage voice calls over PSTN, SIP, and in-app channels. It supports text-to-speech in over 115 languages, interactive voice response (IVR) menus, call recording, transcription, number masking, and conferencing. The API enables outbound and inbound calling with real-time call control through callbacks and SVAML instructions.
  version: '1.0'
  contact:
    name: Sinch Support
    url: https://www.sinch.com/contact-us/
  termsOfService: https://www.sinch.com/terms-of-service/
servers:
- url: https://calling.api.sinch.com
  description: Global Production Server
security:
- basicAuth: []
tags:
- name: Callouts
  description: Callouts are calls made to a phone number or app using the API. Supported types include conference callouts, text-to-speech callouts, and custom callouts.
paths:
  /calling/v1/callouts:
    post:
      operationId: createCallout
      summary: Make a Callout
      description: Makes a call to a phone number or app. The callout type determines the behavior of the call, including conference callouts, text-to-speech callouts, and custom callouts with SVAML control.
      tags:
      - Callouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalloutRequest'
      responses:
        '200':
          description: Callout initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalloutResponse'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
components:
  schemas:
    CalloutRequest:
      type: object
      required:
      - method
      properties:
        method:
          type: string
          enum:
          - conferenceCallout
          - ttsCallout
          - customCallout
          description: The callout method type
        conferenceCallout:
          $ref: '#/components/schemas/ConferenceCallout'
        ttsCallout:
          $ref: '#/components/schemas/TtsCallout'
        customCallout:
          $ref: '#/components/schemas/CustomCallout'
    Destination:
      type: object
      required:
      - type
      - endpoint
      properties:
        type:
          type: string
          enum:
          - number
          - username
          - sip
          - did
          description: The destination type
        endpoint:
          type: string
          description: The destination endpoint identifier
    ConferenceCallout:
      type: object
      required:
      - cli
      - destination
      - conferenceId
      properties:
        cli:
          type: string
          description: The caller ID to display
        destination:
          $ref: '#/components/schemas/Destination'
        conferenceId:
          type: string
          description: The conference identifier to connect to
        dtmf:
          type: string
          description: DTMF tones to play when the call is answered
        maxDuration:
          type: integer
          description: Maximum duration of the call in seconds
        enableAce:
          type: boolean
          description: Enable Answered Call Event callback
        enableDice:
          type: boolean
          description: Enable Disconnected Call Event callback
        enablePie:
          type: boolean
          description: Enable Prompt Input Event callback
        locale:
          type: string
          description: Locale for text-to-speech
        greeting:
          type: string
          description: Text-to-speech greeting when joining conference
        mohClass:
          type: string
          description: Music on hold class
    CustomCallout:
      type: object
      required:
      - cli
      - destination
      - ice
      properties:
        cli:
          type: string
          description: The caller ID to display
        destination:
          $ref: '#/components/schemas/Destination'
        ice:
          type: string
          description: SVAML ICE response in JSON format
        ace:
          type: string
          description: SVAML ACE response in JSON format
        pie:
          type: string
          description: SVAML PIE response in JSON format
    TtsCallout:
      type: object
      required:
      - cli
      - destination
      - text
      properties:
        cli:
          type: string
          description: The caller ID to display
        destination:
          $ref: '#/components/schemas/Destination'
        text:
          type: string
          description: The text to convert to speech
        locale:
          type: string
          description: The locale for text-to-speech
        enableAce:
          type: boolean
          description: Enable Answered Call Event callback
        enableDice:
          type: boolean
          description: Enable Disconnected Call Event callback
    CalloutResponse:
      type: object
      properties:
        callId:
          type: string
          description: The unique call identifier for the initiated call
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Application key and secret used for HTTP basic authentication. Application-signed requests are also supported.
externalDocs:
  description: Sinch Voice API Documentation
  url: https://developers.sinch.com/docs/voice