MessageBird’s SMS API allows you to send and receive SMS messages to and from any country in the world through a REST API. Each message is identified by a unique random ID so that users can always check the status of a message using the given endpoint. The SMS API uses HTTP verbs and a RESTful endpoint structure with an access key that is used as the API Authorization. Request and response payloads are formatted as JSON using UTF-8 encoding and URL encoded values.
openapi: 3.0.0
info:
title: Bird FAQ SMS Messaging API
description: 'The MessageBird FAQ API enables answering questions from an FAQ dataset. Datasets can be created and managed using the dataset section of the MessageBird Dashboard. FAQ datasets are created by giving multiple variations of questions that correspond to an answer. The API applies machine learning to generalize from the questions and answers so that unseen questions are automatically mapped to the right answer.
'
version: 1.0.0
contact:
name: Bird Support
url: https://bird.com/en-us/contact
servers:
- url: https://faq.messagebird.com
security:
- AccessKey: []
tags:
- name: SMS Messaging
description: 'MessageBird’s SMS API allows you to send and receive SMS messages to and from any country in the world through a REST API. Each message is identified by a unique random ID so that users can always check the status of a message using the given endpoint.
The SMS API uses HTTP verbs and a RESTful endpoint structure with an access key that is used as the API Authorization. Request and response payloads are formatted as JSON using UTF-8 encoding and URL encoded values.'
paths:
/messages:
post:
tags:
- SMS Messaging
summary: Send message
description: 'MessageBird''s Programmable SMS API enables you to programmatically send SMS messages from your web application.
First, you need to create a new message object. MessageBird returns the created message object with each request. A maximum of 50 recipients can be entered per request.'
requestBody:
content:
application/json:
schema:
type: object
required:
- originator
- body
- recipients
properties:
originator:
type: string
example: MessageBird
description: The sender of the message. This can be a telephone number (including country code) or an alphanumeric string. In case of an alphanumeric string, the maximum length is 11 characters.
body:
type: string
example: '+380999999999'
description: The body of the SMS message.
recipients:
type: array
items:
type: string
example: '["380999999999", "380999999999"]'
description: An array of recipients msisdns.
groupIds:
type: array
items:
type: string
description: An array of group id's. If provided recipients can be omitted.
type:
type: string
enum:
- sms
- binary
- flash
description: 'The type of message. Values can be: sms, binary, or flash.'
reference:
type: string
description: A client reference. Is required for a status report callback to be sent.
reportUrl:
type: string
example: https://example.ua/report-here
description: The status report URL to be used on a per-message basis. This value overrides the standard status report url configured on the customer account.
validity:
type: integer
example: 60
description: The amount of seconds that the message is valid. If a message is not delivered within this time, the message will be discarded.
gateway:
type: integer
example: 11
description: The SMS route that is used to send the message.
typeDetails:
type: object
example: '{"udh":"050003340201"}'
description: A hashmap with extra information.
datacoding:
type: string
example: unicode
description: The datacoding used, defaults to plain (GSM 03.38 characters only), or it can be set to unicode (contains non-GSM 03.38 characters) or set to auto and we will set unicode or plain depending on the body content.
mclass:
type: integer
example: 1
description: Indicated the message type. 1 is a normal message, 0 is a flash message. (0-3 are valid values).
shortenUrls:
type: boolean
example: false
description: \*beta\* Shorten all the URLs present in the message body.
scheduledDatetime:
type: integer
example: '2022-05-20T12:50:28Z'
description: The scheduled date and time of the message in RFC3339 format (Y-m-d\TH:i:sP), when you want to schedule a message in the future. Don't set this value when message needs to be send directly.
example:
recipients: '+380999999999'
originator: MessageBird
body: Lorem ipsum dolor sit amet.
type: binary
reference: test
reportUrl: https://example.com/callback
validity: 30
gateway: 11
typeDetails:
udh: '050003340201'
datacoding: unicode
mclass: 1
shortenUrls: true
scheduledDatetime: null
parameters:
- name: Content-Type
required: true
in: header
schema:
type: string
example: application/json
- name: Authorization
required: true
in: header
schema:
type: string
example: AccessKey wNmtVQTcLO4uf22uJxjvzwJ223
responses:
'201':
description: SMS successfully created
headers:
Date:
schema:
type: string
example: Fri, 01 Jul 2022 16:16:51 GMT
Content-Type:
schema:
type: string
example: application/json; charset=UTF-8
Content-Length:
schema:
type: integer
example: '602'
Access-Control-Allow-Headers:
schema:
type: string
example: Authorization, Content-Type
Access-Control-Allow-Origin:
schema:
type: string
example: '*'
Access-Control-Allow-Methods:
schema:
type: string
example: GET, POST, PUT, PATCH, DELETE
Access-Control-Allow-Credentials:
schema:
type: boolean
example: 'true'
Pragma:
schema:
type: string
example: no-cache
Expires:
schema:
type: integer
example: '0'
Cache-Control:
schema:
type: string
example: must-revalidate, post-check=0, pre-check=0
content:
application/json:
schema:
type: object
examples:
example-0:
summary: 201 Created
value:
id: f28bbe526fc14974b3e7e663a6139b53
href: https://rest.messagebird.com/messages/f28bbe526fc14974b3e7e663a6139b53
direction: mt
type: sms
originator: MessageBird
body: Lorem ipsum dolor sit amet.
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-07-01T16:16:51+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 0
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
status: sent
statusDatetime: '2022-07-01T16:16:51+00:00'
messagePartCount: 1
example-1:
summary: 201 Created (binary)
value:
id: 1217667de49b4847a7bfeca00ae9ffe3
href: https://rest.messagebird.com/messages/1217667de49b4847a7bfeca00ae9ffe3
direction: mt
type: binary
originator: MessageBird
body: Lorem ipsum dolor sit amet.
reference: test
validity: 30
gateway: 10
typeDetails:
udh: '050003340201'
datacoding: unicode
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-07-01T16:29:24+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 0
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
status: sent
statusDatetime: '2022-07-01T16:29:24+00:00'
messagePartCount: 1
'401':
description: Unauthorized
headers:
Date:
schema:
type: string
example: Fri, 01 Jul 2022 15:50:06 GMT
Content-Type:
schema:
type: string
example: application/json; charset=UTF-8
Content-Length:
schema:
type: integer
example: '107'
Access-Control-Allow-Headers:
schema:
type: string
example: Authorization, Content-Type
Access-Control-Allow-Origin:
schema:
type: string
example: '*'
Access-Control-Allow-Methods:
schema:
type: string
example: GET, POST, PUT, PATCH, DELETE
Access-Control-Allow-Credentials:
schema:
type: boolean
example: 'true'
Www-Authenticate:
schema:
type: string
example: Basic realm="REST API authentication"
Pragma:
schema:
type: string
example: no-cache
Expires:
schema:
type: integer
example: '0'
Cache-Control:
schema:
type: string
example: must-revalidate, post-check=0, pre-check=0
content:
application/json:
schema:
type: object
example:
errors:
- code: 2
description: Request not allowed (incorrect access_key)
parameter: access_key
'422':
description: Unprocessable Entity
headers:
Date:
schema:
type: string
example: Fri, 01 Jul 2022 16:15:29 GMT
Content-Type:
schema:
type: string
example: application/json; charset=UTF-8
Content-Length:
schema:
type: integer
example: '187'
Access-Control-Allow-Headers:
schema:
type: string
example: Authorization, Content-Type
Access-Control-Allow-Origin:
schema:
type: string
example: '*'
Access-Control-Allow-Methods:
schema:
type: string
example: GET, POST, PUT, PATCH, DELETE
Access-Control-Allow-Credentials:
schema:
type: boolean
example: 'true'
Pragma:
schema:
type: string
example: no-cache
Expires:
schema:
type: integer
example: '0'
Cache-Control:
schema:
type: string
example: must-revalidate, post-check=0, pre-check=0
content:
application/json:
schema:
type: object
example:
errors:
- code: 9
description: 'no (correct) recipients found. Note: during your test period you can only send messages to your own number (+380999999999).'
parameter: recipient
get:
tags:
- SMS Messaging
summary: List messages
parameters:
- name: originator
in: query
schema:
type: string
description: Display messages by the specified originator.
example: ValTesting
- name: recipient
in: query
schema:
type: integer
description: Display messages for the specified recipient.
example: '380999999999'
- name: direction
in: query
schema:
type: string
description: Display either mt (sent) or mo (received) messages.
example: mt
- name: limit
in: query
schema:
type: integer
description: Limit the amount of messages listed.
example: '50'
- name: offset
in: query
schema:
type: integer
description: Skip first n results.
example: '0'
- name: searchterm
in: query
schema:
type: string
description: Display messages including the specified searchterm in recipient and originator
example: val
- name: type
in: query
schema:
type: string
description: Display messages of type sms, binary, or flash
example: sms
- name: contact_id
in: query
schema:
type: string
description: Display messages by contact_id. See Contacts API for more info.
example: 61afc0531573b08ddbe36e1c85602827
- name: status
in: query
schema:
type: string
description: Display messages with status scheduled, sent, buffered, delivered, expired, or delivery_failed.
example: buffered
- name: from
in: query
schema:
type: string
description: Display messages starting from the specified date in RFC3339 format (Y-m-d\TH:i:sP).
example: '2022-05-20T12:50:28Z'
- name: until
in: query
schema:
type: string
description: Display messages until the specified date in RFC3339 format (Y-m-d\TH:i:sP).
example: '2022-06-29T12:50:28Z'
responses:
'200':
description: OK
headers:
Date:
schema:
type: string
example: Fri, 01 Jul 2022 16:30:02 GMT
Content-Type:
schema:
type: string
example: application/json; charset=UTF-8
Vary:
schema:
type: string
example: Accept-Encoding
Access-Control-Allow-Headers:
schema:
type: string
example: Authorization, Content-Type
Access-Control-Allow-Origin:
schema:
type: string
example: '*'
Access-Control-Allow-Methods:
schema:
type: string
example: GET, POST, PUT, PATCH, DELETE
Access-Control-Allow-Credentials:
schema:
type: boolean
example: 'true'
Pragma:
schema:
type: string
example: no-cache
Expires:
schema:
type: integer
example: '0'
Cache-Control:
schema:
type: string
example: must-revalidate, post-check=0, pre-check=0
Content-Encoding:
schema:
type: string
example: gzip
Transfer-Encoding:
schema:
type: string
example: chunked
content:
application/json:
schema:
type: object
examples:
example-0:
summary: 200 OK
value:
offset: 0
limit: 20
count: 9
totalCount: 9
links:
first: https://rest.messagebird.com/messages/?offset=0
previous: null
next: null
last: https://rest.messagebird.com/messages/?offset=0
items:
- id: cea5a8d4a82f4b7bb4a053296d5a9ba1
href: https://rest.messagebird.com/messages/cea5a8d4a82f4b7bb4a053296d5a9ba1
direction: mt
type: sms
originator: ValTesting
body: 'Current time: 2022-06-23 12:41:23.828134 +0300 EEST m=+0.001717501'
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-06-23T09:41:24+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 1
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
originator: null
status: delivered
statusDatetime: '2022-06-23T09:41:31+00:00'
recipientCountry: Ukraine
recipientCountryPrefix: 380
recipientOperator: life:)
messageLength: 66
statusErrorCode: null
statusReason: successfully delivered
price:
amount: 1
currency: TRC
mccmnc: '25506'
mcc: '255'
mnc: '06'
messagePartCount: 1
- id: 281f98b1732b4ee29f68f930b80b2f60
href: https://rest.messagebird.com/messages/281f98b1732b4ee29f68f930b80b2f60
direction: mt
type: sms
originator: ValTesting
body: Hi! This is not your first message
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-06-23T06:54:41+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 1
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
originator: null
status: delivered
statusDatetime: '2022-06-23T06:54:47+00:00'
recipientCountry: Ukraine
recipientCountryPrefix: 380
recipientOperator: life:)
messageLength: 34
statusErrorCode: null
statusReason: successfully delivered
price:
amount: 1
currency: TRC
mccmnc: '25506'
mcc: '255'
mnc: '06'
messagePartCount: 1
- id: 78065add7b144d7cb6909576cbfc5b5e
href: https://rest.messagebird.com/messages/78065add7b144d7cb6909576cbfc5b5e
direction: mt
type: sms
originator: ValTesting
body: qwerty3
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-06-22T22:29:58+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 1
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
originator: null
status: delivered
statusDatetime: '2022-06-22T22:30:05+00:00'
recipientCountry: Ukraine
recipientCountryPrefix: 380
recipientOperator: life:)
messageLength: 7
statusErrorCode: null
statusReason: successfully delivered
price:
amount: 1
currency: TRC
mccmnc: '25506'
mcc: '255'
mnc: '06'
messagePartCount: 1
- id: c81801d34d0b4c29bcf304de906feae1
href: https://rest.messagebird.com/messages/c81801d34d0b4c29bcf304de906feae1
direction: mt
type: sms
originator: ValTesting
body: Hi! This is not your first message
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-06-22T14:04:22+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 1
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
originator: null
status: delivered
statusDatetime: '2022-06-22T14:04:29+00:00'
recipientCountry: Ukraine
recipientCountryPrefix: 380
recipientOperator: life:)
messageLength: 34
statusErrorCode: null
statusReason: successfully delivered
price:
amount: 1
currency: TRC
mccmnc: '25506'
mcc: '255'
mnc: '06'
messagePartCount: 1
- id: e876126d16af4fdfb368c538f7a4d660
href: https://rest.messagebird.com/messages/e876126d16af4fdfb368c538f7a4d660
direction: mt
type: sms
originator: ValTesting
body: Hi! This is not your first message
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-06-22T14:03:56+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 1
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
originator: null
status: delivered
statusDatetime: '2022-06-22T14:04:04+00:00'
recipientCountry: Ukraine
recipientCountryPrefix: 380
recipientOperator: life:)
messageLength: 34
statusErrorCode: null
statusReason: successfully delivered
price:
amount: 1
currency: TRC
mccmnc: '25506'
mcc: '255'
mnc: '06'
messagePartCount: 1
- id: cfe8234a793f4f90833fe6d01731e6fa
href: https://rest.messagebird.com/messages/cfe8234a793f4f90833fe6d01731e6fa
direction: mt
type: sms
originator: ValTesting
body: qwerty2
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-06-22T01:29:58+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 1
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
originator: null
status: delivered
statusDatetime: '2022-06-22T01:30:14+00:00'
recipientCountry: Ukraine
recipientCountryPrefix: 380
recipientOperator: life:)
messageLength: 7
statusErrorCode: null
statusReason: successfully delivered
price:
amount: 1
currency: TRC
mccmnc: '25506'
mcc: '255'
mnc: '06'
messagePartCount: 1
- id: 0f484ecbf51942b5b7f4df62891ea247
href: https://rest.messagebird.com/messages/0f484ecbf51942b5b7f4df62891ea247
direction: mt
type: sms
originator: ValTesting
body: qwerty2
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-06-22T01:29:58+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 1
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
originator: null
status: delivered
statusDatetime: '2022-06-22T01:30:04+00:00'
recipientCountry: Ukraine
recipientCountryPrefix: 380
recipientOperator: life:)
messageLength: 7
statusErrorCode: null
statusReason: successfully delivered
price:
amount: 1
currency: TRC
mccmnc: '25506'
mcc: '255'
mnc: '06'
messagePartCount: 1
- id: 0aa1c53c34d34bda84cc4bc454d95028
href: https://rest.messagebird.com/messages/0aa1c53c34d34bda84cc4bc454d95028
direction: mt
type: sms
originator: ValTesting
body: Hi! This is not your first message
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-06-21T16:03:00+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 1
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
originator: null
status: delivered
statusDatetime: '2022-06-21T16:03:07+00:00'
recipientCountry: Ukraine
recipientCountryPrefix: 380
recipientOperator: life:)
messageLength: 34
statusErrorCode: null
statusReason: successfully delivered
price:
amount: 1
currency: TRC
mccmnc: '25506'
mcc: '255'
mnc: '06'
messagePartCount: 1
- id: cb96c6336c92482797554428a899a225
href: https://rest.messagebird.com/messages/cb96c6336c92482797554428a899a225
direction: mt
type: sms
originator: Test
body: This is a test message
reference: null
validity: null
gateway: 10
typeDetails: {}
datacoding: plain
mclass: 1
scheduledDatetime: null
createdDatetime: '2022-06-21T15:28:58+00:00'
recipients:
totalCount: 1
totalSentCount: 1
totalDeliveredCount: 1
totalDeliveryFailedCount: 0
items:
- recipient: 380999999999
originator: null
status: delivered
statusDatetime: '2022-06-21T15:29:05+00:00'
recipientCountry: Ukraine
recipientCountryPrefix: 380
recipientOperator: life:)
messageLength: 22
statusErrorCode: null
statusReason: successfully delivered
price:
amount: 1
currency: TRC
mccmnc: '255
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bird/refs/heads/main/openapi/bird-sms-messaging-api-openapi.yml