openapi: 3.2.0
info:
  title: MessageBird Voice Calling Calls 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
servers:
- url: https://voice.messagebird.com
  description: Production Server
security:
- accessKey: []
tags:
- name: Calls
  description: Operations for creating, listing, and managing voice calls.
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
components:
  schemas:
    CallResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Call'
    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'
    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.
    CallList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Call'
        pagination:
          $ref: '#/components/schemas/Pagination'
    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.
    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'
    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.
    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.
  parameters:
    callIdParam:
      name: callId
      in: path
      required: true
      description: The unique identifier of the call.
      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
  securitySchemes:
    accessKey:
      type: apiKey
      in: header
      name: Authorization
      description: Access key authentication in the form of 'AccessKey {accessKey}'.
externalDocs:
  description: Voice Calling API Documentation
  url: https://developers.messagebird.com/api/voice-calling/