openapi: 3.1.0
info:
  title: MessageBird Voice Calling API
  description: >-
    The MessageBird Voice Calling API enables developers to make, receive,
    and control phone calls programmatically. It supports call flows for
    building interactive voice response systems, call recording, call
    transfers, and real-time webhooks for call events. The API provides
    global coverage and can be used to build contact center solutions,
    automated calling systems, and voice-enabled applications.
  version: '1.0'
  contact:
    name: MessageBird Support
    url: https://support.messagebird.com
  termsOfService: https://www.messagebird.com/en/terms
externalDocs:
  description: Voice Calling API Documentation
  url: https://developers.messagebird.com/api/voice-calling/
servers:
  - url: https://voice.messagebird.com
    description: Production Server
tags:
  - name: Call Flows
    description: >-
      Operations for managing call flows that define interactive voice
      response sequences.
  - name: Calls
    description: >-
      Operations for creating, listing, and managing voice calls.
  - name: Legs
    description: >-
      Operations for viewing and managing call legs. A leg represents a
      single voice connection within a call.
  - name: Recordings
    description: >-
      Operations for managing call recordings.
  - name: Transcriptions
    description: >-
      Operations for creating and viewing transcriptions of call recordings.
  - name: Webhooks
    description: >-
      Operations for managing account-wide voice webhooks.
security:
  - accessKey: []
paths:
  /calls:
    get:
      operationId: listCalls
      summary: List all calls
      description: >-
        Retrieves a paginated list of all calls made or received on the
        account.
      tags:
        - Calls
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam'
      responses:
        '200':
          description: A list of calls
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallList'
        '401':
          description: Unauthorized
    post:
      operationId: createCall
      summary: Create a call
      description: >-
        Creates a new outbound call. The call will be placed from the
        specified source to the destination number, and the call flow
        will be executed.
      tags:
        - Calls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallCreate'
      responses:
        '201':
          description: Call created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /calls/{callId}:
    get:
      operationId: viewCall
      summary: View a call
      description: >-
        Retrieves the details of an existing call by its unique identifier.
      tags:
        - Calls
      parameters:
        - $ref: '#/components/parameters/callIdParam'
      responses:
        '200':
          description: Call details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallResponse'
        '401':
          description: Unauthorized
        '404':
          description: Call not found
    delete:
      operationId: deleteCall
      summary: Delete a call
      description: >-
        Deletes an existing call by hanging up all active legs and
        removing the call resource.
      tags:
        - Calls
      parameters:
        - $ref: '#/components/parameters/callIdParam'
      responses:
        '204':
          description: Call deleted
        '401':
          description: Unauthorized
        '404':
          description: Call not found
  /calls/{callId}/legs:
    get:
      operationId: listLegs
      summary: List legs for a call
      description: >-
        Retrieves a list of all legs associated with a specific call.
        Each leg represents a voice connection within the call.
      tags:
        - Legs
      parameters:
        - $ref: '#/components/parameters/callIdParam'
      responses:
        '200':
          description: A list of legs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegList'
        '401':
          description: Unauthorized
        '404':
          description: Call not found
  /calls/{callId}/legs/{legId}/recordings:
    get:
      operationId: listRecordings
      summary: List recordings for a leg
      description: >-
        Retrieves a list of all recordings associated with a specific
        call leg.
      tags:
        - Recordings
      parameters:
        - $ref: '#/components/parameters/callIdParam'
        - $ref: '#/components/parameters/legIdParam'
      responses:
        '200':
          description: A list of recordings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordingList'
        '401':
          description: Unauthorized
        '404':
          description: Resource not found
  /recordings/{recordingId}:
    get:
      operationId: viewRecording
      summary: View a recording
      description: >-
        Retrieves the details of a specific recording by its unique
        identifier.
      tags:
        - Recordings
      parameters:
        - $ref: '#/components/parameters/recordingIdParam'
      responses:
        '200':
          description: Recording details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordingResponse'
        '401':
          description: Unauthorized
        '404':
          description: Recording not found
    delete:
      operationId: deleteRecording
      summary: Delete a recording
      description: >-
        Deletes an existing recording by its unique identifier.
      tags:
        - Recordings
      parameters:
        - $ref: '#/components/parameters/recordingIdParam'
      responses:
        '204':
          description: Recording deleted
        '401':
          description: Unauthorized
        '404':
          description: Recording not found
  /recordings/{recordingId}/transcriptions:
    get:
      operationId: listTranscriptions
      summary: List transcriptions for a recording
      description: >-
        Retrieves all transcriptions associated with a specific recording.
      tags:
        - Transcriptions
      parameters:
        - $ref: '#/components/parameters/recordingIdParam'
      responses:
        '200':
          description: A list of transcriptions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranscriptionList'
        '401':
          description: Unauthorized
        '404':
          description: Recording not found
    post:
      operationId: createTranscription
      summary: Create a transcription
      description: >-
        Creates a new transcription request for a recording. Transcriptions
        are generated asynchronously.
      tags:
        - Transcriptions
      parameters:
        - $ref: '#/components/parameters/recordingIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranscriptionCreate'
      responses:
        '201':
          description: Transcription request created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranscriptionResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Recording not found
  /call-flows:
    get:
      operationId: listCallFlows
      summary: List all call flows
      description: >-
        Retrieves a paginated list of all call flows configured on the
        account.
      tags:
        - Call Flows
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam'
      responses:
        '200':
          description: A list of call flows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallFlowList'
        '401':
          description: Unauthorized
    post:
      operationId: createCallFlow
      summary: Create a call flow
      description: >-
        Creates a new call flow with a sequence of steps that define
        the interactive voice response behavior.
      tags:
        - Call Flows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallFlowCreate'
      responses:
        '201':
          description: Call flow created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallFlowResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /call-flows/{callFlowId}:
    get:
      operationId: viewCallFlow
      summary: View a call flow
      description: >-
        Retrieves the details of a specific call flow by its unique
        identifier.
      tags:
        - Call Flows
      parameters:
        - $ref: '#/components/parameters/callFlowIdParam'
      responses:
        '200':
          description: Call flow details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallFlowResponse'
        '401':
          description: Unauthorized
        '404':
          description: Call flow not found
    put:
      operationId: updateCallFlow
      summary: Update a call flow
      description: >-
        Updates an existing call flow with new step definitions.
      tags:
        - Call Flows
      parameters:
        - $ref: '#/components/parameters/callFlowIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallFlowCreate'
      responses:
        '200':
          description: Call flow updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallFlowResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Call flow not found
    delete:
      operationId: deleteCallFlow
      summary: Delete a call flow
      description: >-
        Deletes an existing call flow by its unique identifier.
      tags:
        - Call Flows
      parameters:
        - $ref: '#/components/parameters/callFlowIdParam'
      responses:
        '204':
          description: Call flow deleted
        '401':
          description: Unauthorized
        '404':
          description: Call flow not found
  /webhooks:
    get:
      operationId: listVoiceWebhooks
      summary: List all voice webhooks
      description: >-
        Retrieves a list of all account-wide voice webhooks. Up to 5
        generic webhooks can be created per account.
      tags:
        - Webhooks
      responses:
        '200':
          description: A list of webhooks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceWebhookList'
        '401':
          description: Unauthorized
    post:
      operationId: createVoiceWebhook
      summary: Create a voice webhook
      description: >-
        Creates a new account-wide voice webhook to receive events from
        all calls, both inbound and outbound.
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoiceWebhookCreate'
      responses:
        '201':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceWebhookResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /webhooks/{webhookId}:
    get:
      operationId: viewVoiceWebhook
      summary: View a voice webhook
      description: >-
        Retrieves the details of a specific voice webhook.
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/webhookIdParam'
      responses:
        '200':
          description: Webhook details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceWebhookResponse'
        '401':
          description: Unauthorized
        '404':
          description: Webhook not found
    put:
      operationId: updateVoiceWebhook
      summary: Update a voice webhook
      description: >-
        Updates an existing voice webhook configuration.
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/webhookIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoiceWebhookCreate'
      responses:
        '200':
          description: Webhook updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceWebhookResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Webhook not found
    delete:
      operationId: deleteVoiceWebhook
      summary: Delete a voice webhook
      description: >-
        Deletes an existing voice webhook.
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/webhookIdParam'
      responses:
        '204':
          description: Webhook deleted
        '401':
          description: Unauthorized
        '404':
          description: Webhook not found
components:
  securitySchemes:
    accessKey:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Access key authentication in the form of 'AccessKey {accessKey}'.
  parameters:
    callIdParam:
      name: callId
      in: path
      required: true
      description: >-
        The unique identifier of the call.
      schema:
        type: string
    legIdParam:
      name: legId
      in: path
      required: true
      description: >-
        The unique identifier of the leg.
      schema:
        type: string
    recordingIdParam:
      name: recordingId
      in: path
      required: true
      description: >-
        The unique identifier of the recording.
      schema:
        type: string
    callFlowIdParam:
      name: callFlowId
      in: path
      required: true
      description: >-
        The unique identifier of the call flow.
      schema:
        type: string
    webhookIdParam:
      name: webhookId
      in: path
      required: true
      description: >-
        The unique identifier of the webhook.
      schema:
        type: string
    pageParam:
      name: page
      in: query
      required: false
      description: >-
        The page number for pagination.
      schema:
        type: integer
        default: 1
    perPageParam:
      name: perPage
      in: query
      required: false
      description: >-
        The number of items per page.
      schema:
        type: integer
        default: 10
  schemas:
    CallCreate:
      type: object
      required:
        - source
        - destination
        - callFlow
      properties:
        source:
          type: string
          description: >-
            The caller ID to display, must be a purchased MessageBird number.
        destination:
          type: string
          description: >-
            The phone number or SIP URI to call.
        callFlow:
          $ref: '#/components/schemas/CallFlowCreate'
        webhook:
          $ref: '#/components/schemas/VoiceWebhookCreate'
    Call:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the call.
        status:
          type: string
          description: >-
            The status of the call.
          enum:
            - queued
            - starting
            - ongoing
            - ended
        source:
          type: string
          description: >-
            The caller ID number.
        destination:
          type: string
          description: >-
            The destination number or SIP URI.
        createdAt:
          type: string
          format: date-time
          description: >-
            The date and time when the call was created.
        updatedAt:
          type: string
          format: date-time
          description: >-
            The date and time when the call was last updated.
        endedAt:
          type: string
          format: date-time
          description: >-
            The date and time when the call ended.
    CallResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Call'
    CallList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Call'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Leg:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the leg.
        callId:
          type: string
          description: >-
            The unique identifier of the parent call.
        source:
          type: string
          description: >-
            The source number or SIP URI.
        destination:
          type: string
          description: >-
            The destination number or SIP URI.
        status:
          type: string
          description: >-
            The status of the leg.
          enum:
            - starting
            - ringing
            - ongoing
            - busy
            - no_answer
            - failed
            - hangup
        direction:
          type: string
          description: >-
            The direction of the leg.
          enum:
            - incoming
            - outgoing
        duration:
          type: integer
          description: >-
            The duration of the leg in seconds.
        createdAt:
          type: string
          format: date-time
          description: >-
            The date and time when the leg was created.
        updatedAt:
          type: string
          format: date-time
          description: >-
            The date and time when the leg was last updated.
        answeredAt:
          type: string
          format: date-time
          description: >-
            The date and time when the leg was answered.
        endedAt:
          type: string
          format: date-time
          description: >-
            The date and time when the leg ended.
    LegList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Leg'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Recording:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the recording.
        format:
          type: string
          description: >-
            The format of the recording file.
          enum:
            - wav
        legId:
          type: string
          description: >-
            The unique identifier of the leg this recording belongs to.
        status:
          type: string
          description: >-
            The status of the recording.
          enum:
            - initialised
            - recording
            - done
            - failed
        duration:
          type: integer
          description: >-
            The duration of the recording in seconds.
        createdAt:
          type: string
          format: date-time
          description: >-
            The date and time when the recording was created.
        updatedAt:
          type: string
          format: date-time
          description: >-
            The date and time when the recording was last updated.
    RecordingResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Recording'
    RecordingList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Recording'
        pagination:
          $ref: '#/components/schemas/Pagination'
    TranscriptionCreate:
      type: object
      properties:
        language:
          type: string
          description: >-
            The language of the recording for transcription.
    Transcription:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the transcription.
        recordingId:
          type: string
          description: >-
            The unique identifier of the recording.
        status:
          type: string
          description: >-
            The status of the transcription.
          enum:
            - created
            - transcribing
            - done
            - failed
        createdAt:
          type: string
          format: date-time
          description: >-
            The date and time when the transcription was created.
        updatedAt:
          type: string
          format: date-time
          description: >-
            The date and time when the transcription was last updated.
    TranscriptionResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Transcription'
    TranscriptionList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Transcription'
        pagination:
          $ref: '#/components/schemas/Pagination'
    CallFlowCreate:
      type: object
      required:
        - steps
      properties:
        title:
          type: string
          description: >-
            A human-readable title for the call flow.
        record:
          type: boolean
          description: >-
            Whether to record the entire call.
        steps:
          type: array
          description: >-
            A sequence of steps that define the call flow behavior.
          items:
            $ref: '#/components/schemas/CallFlowStep'
    CallFlowStep:
      type: object
      required:
        - action
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the step.
        action:
          type: string
          description: >-
            The action to perform in this step.
          enum:
            - say
            - play
            - pause
            - record
            - fetchCallFlow
            - hangup
            - transfer
        options:
          type: object
          description: >-
            Action-specific options for the step.
    CallFlowResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CallFlow'
    CallFlow:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the call flow.
        title:
          type: string
          description: >-
            The title of the call flow.
        record:
          type: boolean
          description: >-
            Whether recording is enabled for the call flow.
        steps:
          type: array
          description: >-
            The steps that define the call flow.
          items:
            $ref: '#/components/schemas/CallFlowStep'
        createdAt:
          type: string
          format: date-time
          description: >-
            The date and time when the call flow was created.
        updatedAt:
          type: string
          format: date-time
          description: >-
            The date and time when the call flow was last updated.
    CallFlowList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CallFlow'
        pagination:
          $ref: '#/components/schemas/Pagination'
    VoiceWebhookCreate:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: >-
            The URL to receive webhook callbacks.
        token:
          type: string
          description: >-
            A token for webhook signature validation.
    VoiceWebhookResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/VoiceWebhook'
    VoiceWebhook:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the webhook.
        url:
          type: string
          format: uri
          description: >-
            The URL that receives webhook callbacks.
        token:
          type: string
          description: >-
            The token used for signature validation.
        createdAt:
          type: string
          format: date-time
          description: >-
            The date and time when the webhook was created.
        updatedAt:
          type: string
          format: date-time
          description: >-
            The date and time when the webhook was last updated.
    VoiceWebhookList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/VoiceWebhook'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Pagination:
      type: object
      properties:
        totalCount:
          type: integer
          description: >-
            The total number of items available.
        pageCount:
          type: integer
          description: >-
            The total number of pages.
        currentPage:
          type: integer
          description: >-
            The current page number.
        perPage:
          type: integer
          description: >-
            The number of items per page.