The MessageBird Voice Messaging API enables developers to transform text messages into voice messages delivered to any country. It supports 26 languages with configurable attributes such as male or female voice, speaking rate, repeat options, and scheduling. The API is useful for sending voice notifications, alerts, and one-time passwords to users who may not have access to SMS.
openapi: 3.1.0
info:
title: MessageBird Voice Messaging API
description: >-
The MessageBird Voice Messaging API enables developers to transform text
messages into voice messages delivered to any country. It supports 26
languages with configurable attributes such as male or female voice,
speaking rate, repeat options, and scheduling. The API is useful for
sending voice notifications, alerts, and one-time passwords to users
who may not have access to SMS.
version: '1.0'
contact:
name: MessageBird Support
url: https://support.messagebird.com
termsOfService: https://www.messagebird.com/en/terms
externalDocs:
description: Voice Messaging API Documentation
url: https://developers.messagebird.com/api/voice-messaging/
servers:
- url: https://rest.messagebird.com
description: Production Server
tags:
- name: Voice Messages
description: >-
Operations for sending and managing text-to-speech voice messages.
security:
- accessKey: []
paths:
/voicemessages:
get:
operationId: listVoiceMessages
summary: List voice messages
description: >-
Retrieves a list of voice messages that have been sent. Messages
are returned in reverse chronological order.
tags:
- Voice Messages
parameters:
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/limitParam'
responses:
'200':
description: A list of voice messages
content:
application/json:
schema:
$ref: '#/components/schemas/VoiceMessageList'
'401':
description: Unauthorized
post:
operationId: createVoiceMessage
summary: Send a voice message
description: >-
Creates a new voice message and delivers it to the specified
recipients using text-to-speech. A maximum of 50 recipients can
be specified per request.
tags:
- Voice Messages
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VoiceMessageCreate'
responses:
'201':
description: Voice message created
content:
application/json:
schema:
$ref: '#/components/schemas/VoiceMessage'
'400':
description: Bad request
'401':
description: Unauthorized
'422':
description: Unprocessable entity
/voicemessages/{id}:
get:
operationId: viewVoiceMessage
summary: View a voice message
description: >-
Retrieves the details of an existing voice message by its unique
identifier.
tags:
- Voice Messages
parameters:
- $ref: '#/components/parameters/voiceMessageIdParam'
responses:
'200':
description: Voice message details
content:
application/json:
schema:
$ref: '#/components/schemas/VoiceMessage'
'401':
description: Unauthorized
'404':
description: Voice message not found
delete:
operationId: deleteVoiceMessage
summary: Delete a voice message
description: >-
Deletes an existing voice message by its unique identifier.
tags:
- Voice Messages
parameters:
- $ref: '#/components/parameters/voiceMessageIdParam'
responses:
'204':
description: Voice message deleted
'401':
description: Unauthorized
'404':
description: Voice message not found
components:
securitySchemes:
accessKey:
type: apiKey
in: header
name: Authorization
description: >-
Access key authentication in the form of 'AccessKey {accessKey}'.
parameters:
voiceMessageIdParam:
name: id
in: path
required: true
description: >-
The unique identifier of the voice message.
schema:
type: string
offsetParam:
name: offset
in: query
required: false
description: >-
The number of items to skip before starting to collect the result set.
schema:
type: integer
default: 0
limitParam:
name: limit
in: query
required: false
description: >-
The maximum number of items to return.
schema:
type: integer
default: 20
schemas:
VoiceMessageCreate:
type: object
required:
- recipients
- body
properties:
recipients:
type: array
description: >-
The phone numbers that will receive the voice message in
international format. A maximum of 50 recipients per request.
items:
type: string
minItems: 1
maxItems: 50
body:
type: string
description: >-
The text content to be converted to speech and delivered as a
voice message.
originator:
type: string
description: >-
The caller ID to display to the recipient.
reference:
type: string
description: >-
A client reference for tracking purposes.
reportUrl:
type: string
format: uri
description: >-
The URL for delivery report callbacks.
language:
type: string
description: >-
The language of the text-to-speech voice. Supports 26 languages.
enum:
- cy-gb
- da-dk
- de-de
- el-gr
- en-au
- en-gb
- en-gb-wls
- en-in
- en-us
- es-es
- es-mx
- es-us
- fr-ca
- fr-fr
- id-id
- is-is
- it-it
- ja-jp
- ko-kr
- ms-my
- nb-no
- nl-nl
- pl-pl
- pt-br
- pt-pt
- ro-ro
- ru-ru
- sv-se
- ta-in
- th-th
- tr-tr
- vi-vn
- zh-cn
- zh-hk
default: en-gb
voice:
type: string
description: >-
The voice gender for text-to-speech.
enum:
- male
- female
default: female
repeat:
type: integer
description: >-
The number of times the message should be repeated.
minimum: 1
maximum: 10
default: 1
ifMachine:
type: string
description: >-
What to do when an answering machine is detected.
enum:
- continue
- delay
- hangup
default: continue
machineTimeout:
type: integer
description: >-
The timeout in milliseconds for answering machine detection.
scheduledDatetime:
type: string
format: date-time
description: >-
The scheduled date and time for the voice message in RFC 3339
format.
VoiceMessage:
type: object
properties:
id:
type: string
description: >-
The unique identifier of the voice message.
href:
type: string
format: uri
description: >-
The URL of the voice message resource.
body:
type: string
description: >-
The text content of the voice message.
originator:
type: string
description: >-
The caller ID displayed to the recipient.
reference:
type: string
description: >-
The client reference for the voice message.
language:
type: string
description: >-
The language used for text-to-speech.
voice:
type: string
description: >-
The voice gender used for text-to-speech.
repeat:
type: integer
description: >-
The number of times the message is repeated.
ifMachine:
type: string
description: >-
The behavior when an answering machine is detected.
scheduledDatetime:
type: string
format: date-time
description: >-
The scheduled date and time for the message.
createdDatetime:
type: string
format: date-time
description: >-
The date and time when the voice message was created.
recipients:
type: object
properties:
totalCount:
type: integer
description: >-
The total number of recipients.
totalSentCount:
type: integer
description: >-
The number of messages sent.
totalDeliveredCount:
type: integer
description: >-
The number of messages delivered.
totalDeliveryFailedCount:
type: integer
description: >-
The number of messages that failed delivery.
items:
type: array
items:
type: object
properties:
recipient:
type: integer
format: int64
description: >-
The recipient phone number.
status:
type: string
description: >-
The delivery status.
statusDatetime:
type: string
format: date-time
description: >-
The date and time of the last status update.
VoiceMessageList:
type: object
properties:
offset:
type: integer
description: >-
The offset of the result set.
limit:
type: integer
description: >-
The limit applied to the result set.
count:
type: integer
description: >-
The number of items returned.
totalCount:
type: integer
description: >-
The total number of items available.
links:
type: object
properties:
first:
type: string
format: uri
description: >-
Link to the first page.
previous:
type: string
format: uri
description: >-
Link to the previous page.
next:
type: string
format: uri
description: >-
Link to the next page.
last:
type: string
format: uri
description: >-
Link to the last page.
items:
type: array
items:
$ref: '#/components/schemas/VoiceMessage'