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.
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.