Encapsulates multiple APIs to interact with our various channels such as WhatsApp Business, SMS, MMS, Viber, Facebook Messenger, etc. The API normalises information across all channels to abstracted to, from and content. This API is for outbound messages.
openapi: "3.0.0"
info:
version: "v1.1.1"
title: Messages - Vonage
description: >-
Encapsulates multiple APIs to interact with our various channels such as WhatsApp Business, SMS, MMS, Viber, Facebook Messenger, etc. The API normalises information across all channels to abstracted to, from and content.
This API is for outbound messages.
## [Source view](https://app.swaggerhub.com/apis/kpn/messages-nexmo/)<br/>
[Documentation view](https://app.swaggerhub.com/apis-docs/kpn/messages-nexmo/)
---
## [KPN Developer](https://developer.kpn.com/)<br/>
[Getting Started](https://developer.kpn.com/getting-started)
---
contact:
name: API Support
email: api_developer@kpn.com
url: 'https://developer.kpn.com/support'
termsOfService: 'https://developer.kpn.com/legal'
servers:
-
url: 'https://api-prd.kpn.com/communication/nexmo'
description: API Store Application
externalDocs:
description: HTTP response headers
url: https://developer.kpn.com/documentation-response-headers
tags:
-
name: applications
description: Application related resource management
-
name: messages
description: Message related resource management
paths:
"/applications/v2":
parameters:
- $ref: '#/components/parameters/api_version_header'
post:
security:
- oauth2: []
summary: Creates new application
description: >
Creates a new application.
The basic body needs to include:
- `name` with the name of the application.
- `type` should be `messages`.
- `status_url` Vonage sends Submitted, Delivered, Read and Rejected statuses for every message to this URL.
- `inbound_url`to receive Inbound Messages.
Creates a call and returns a JSON object with the call identifier (uuid), status of the call, conversation_uuid the call is attached to and the direction of the call.
tags:
- applications
operationId: createApplication
requestBody:
description: Application Details
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/new_application'
responses:
'201':
$ref: '#/components/responses/app_created'
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'429':
$ref: '#/components/responses/too_many'
'500':
$ref: '#/components/responses/server_error'
'503':
$ref: '#/components/responses/service_unavailable'
get:
security:
- oauth2: []
summary: Retrieves details of your applications.
description: >-
Retrieves details of your applications.
> **Note:** This endpoint is not available for sandbox environments. To use it please apply for production.
tags:
- applications
operationId: getApplications
parameters:
- name: page_size
in: query
description: Set the number of items returned on each call to this endpoint
schema:
type: integer
default: 10
required: false
- name: page_index
in: query
description: Set the offset from the first page
schema:
type: integer
default: 0
required: false
responses:
'200':
$ref: '#/components/responses/app_list'
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'429':
$ref: '#/components/responses/too_many'
'500':
$ref: '#/components/responses/server_error'
'503':
$ref: '#/components/responses/service_unavailable'
"/applications/v2/{uuid}":
parameters:
- $ref: '#/components/parameters/api_version_header'
- $ref: '#/components/parameters/application_uuid'
get:
security:
- oauth2: []
summary: Retrieves details of a specific application.
description: >-
Retrieves detailed information of a specific application.
tags:
- applications
operationId: getApplication
responses:
'200':
$ref: '#/components/responses/app_detail_ok'
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'429':
$ref: '#/components/responses/too_many'
'500':
$ref: '#/components/responses/server_error'
'503':
$ref: '#/components/responses/service_unavailable'
delete:
security:
- oauth2: []
summary: Deletes application.
description: >-
Deletes the existing application.
tags:
- applications
operationId: deleteApplication
responses:
'204':
description: No Content
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'429':
$ref: '#/components/responses/too_many'
'500':
$ref: '#/components/responses/server_error'
'503':
$ref: '#/components/responses/service_unavailable'
/messages:
parameters:
- $ref: '#/components/parameters/message_application_id_header'
post:
security:
- JWTAuth: []
summary: Sends a message.
operationId: NewMessage
tags: [messages]
requestBody:
description: Send a Message.
required: true
x-show-example-request: true
content:
application/json:
schema:
oneOf:
- title: SMS
x-tab-id: SMS
example:
message_type: text
text: This is a test message from Message API
to: '567546745'
from: '56745674567'
channel: sms
oneOf:
- allOf:
- $ref: "#/components/schemas/Text"
- properties:
text:
description: >
The text of message to send; limited to 1000
characters. Unless unless `text` or `unicode`
has
been explicitly set as the value for `sms.encoding_type`, the Messages API automatically
detects whether unicode characters are present in `text` and sends the message as appropriate
as either a text or unicode SMS. For more information on concatenation and encoding
please visit: [developer.nexmo.com/messaging/sms/guides/concatenation-and-encoding](https://developer.vonage.com/messaging/sms/guides/concatenation-and-encoding).
- $ref: "#/components/schemas/channelOptionsSms"
- $ref: "#/components/schemas/outboundMessageCommon"
- title: MMS
x-tab-id: MMS
example:
message_type: image
image:
url: https://example.com/image.jpg
to: '447700900000'
from: '447700900001'
channel: mms
oneOf:
- allOf:
- $ref: "#/components/schemas/Image"
- properties:
image:
required:
- url
properties:
url:
type: string
description: |
The URL of the image attachment.
Supports `.jpg`, `.jpeg`, `.png` and `.gif`.
example: https://example.com/image.jpg
caption:
type: string
description: Additional text to accompany the image.
minLength: 1
maxLength: 2000
example: Additional text to accompany the image.
- $ref: "#/components/schemas/channelOptionsMms"
- $ref: "#/components/schemas/outboundMessageCommon"
- allOf:
- $ref: "#/components/schemas/vCard"
- properties:
vcard:
required:
- url
properties:
url:
type: string
description: |
The URL of the vCard attachment.
Supports `.vcf` only.
example: https://example.com/contact.vcf
caption:
type: string
description: Additional text to accompany the vCard.
minLength: 1
maxLength: 2000
example: Additional text to accompany the vCard.
- $ref: "#/components/schemas/channelOptionsMms"
- $ref: "#/components/schemas/outboundMessageCommon"
- allOf:
- $ref: "#/components/schemas/Audio"
- properties:
message_type:
type: string
enum:
- audio
example: audio
description: >
The type of message to send. You must provide
`audio` in this field.
For best device and network support .mp3 is recommended. Not supported for US short codes.
audio:
required:
- url
properties:
url:
type: string
description: |
The URL of the audio attachment.
example: https://example.com/audio.mp3
caption:
type: string
description: Additional text to accompany the audio file.
minLength: 1
maxLength: 2000
example: Additional text to accompany the audio file.
- $ref: "#/components/schemas/channelOptionsMms"
- $ref: "#/components/schemas/outboundMessageCommon"
- allOf:
- $ref: "#/components/schemas/Video"
- properties:
message_type:
type: string
enum:
- video
example: video
description: >
The type of message to send. You must provide
`video` in this field.
For best device and network support .mp4 is recommended. Not supported for US short codes.
video:
required:
- url
properties:
url:
type: string
description: |
The URL of the video attachment.
example: https://example.com/video.mp4
caption:
type: string
description: Additional text to accompany the video file.
minLength: 1
maxLength: 2000
example: Additional text to accompany the video file.
- $ref: "#/components/schemas/channelOptionsMms"
- $ref: "#/components/schemas/outboundMessageCommon"
- title: WhatsApp
x-tab-id: WhatsApp
example:
message_type: text
text: 'Nexmo Verification code: 12345.<br />Valid for 10 minutes.'
to: '447700900000'
from: '447700900001'
channel: whatsapp
oneOf:
- allOf:
- $ref: "#/components/schemas/Text"
- properties:
text:
description: >
The text of message to send; limited to 4096
characters, including unicode.
- $ref: "#/components/schemas/channelOptionsWhatsapp"
- $ref: "#/components/schemas/outboundMessageCommon"
- allOf:
- $ref: "#/components/schemas/Image"
- properties:
image:
required:
- url
properties:
url:
type: string
description: |
The URL of the image attachment.
Supports `.jpg`, `.jpeg`, and `.png`.
example: https://example.com/image.jpg
caption:
type: string
description: Additional text to accompany the image.
minLength: 1
maxLength: 3000
example: Additional text to accompany the image.
- $ref: "#/components/schemas/channelOptionsWhatsapp"
- $ref: "#/components/schemas/outboundMessageCommon"
- allOf:
- $ref: "#/components/schemas/Audio"
- properties:
audio:
required:
- url
properties:
url:
description: >
The URL of the audio attachment.
Supports `.aac`, `.m4a`, `.amr`, `.mp3` and `.opus`.
minLength: 10
maxLength: 2000
- $ref: "#/components/schemas/channelOptionsWhatsapp"
- $ref: "#/components/schemas/outboundMessageCommon"
- allOf:
- $ref: "#/components/schemas/Video"
- properties:
video:
required:
- url
properties:
url:
description: >
The URL of the video attachment.
Supports `.mp4` and `.3gpp`. Note, only `H.264` video codec and `AAC` audio codec is supported.
caption:
type: string
description: Additional text to accompany the file.
example: Additional text.
- $ref: "#/components/schemas/channelOptionsWhatsapp"
- $ref: "#/components/schemas/outboundMessageCommon"
- allOf:
- $ref: "#/components/schemas/File"
- properties:
file:
required:
- url
properties:
url:
description: >
The URL of the file attachment.
Supports supports a wide range of attachments including `.zip`, `.csv` and `.pdf`.
caption:
type: string
description: Additional text to accompany the file.
example: Additional text.
name:
type: string
description: >
Optional parameter that specifies the name
of the file being sent. If not included, the
value for `caption`
will be used as the file name. If neither `name` or `caption` are included, the file name will be parsed
from the `url`.
example: file.pdf
- $ref: "#/components/schemas/channelOptionsWhatsapp"
- $ref: "#/components/schemas/outboundMessageCommon"
- allOf:
- required:
- message_type
- whatsapp
- $ref: "#/components/schemas/Template"
- $ref: "#/components/schemas/channelOptionsWhatsapp"
- $ref: "#/components/schemas/outboundMessageCommon"
- properties:
whatsapp:
type: object
required:
- locale
properties:
policy:
type: string
example: deterministic
enum:
- deterministic
description: Policy for resolving what language template to use. As of right now
the only valid choice is `deterministic`.
locale:
type: string
example: en_US
description: The [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag)
language of the template. See [the WhatsApp
documentation](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages-)
for supported languages.
- allOf:
- $ref: "#/components/schemas/Sticker"
- $ref: "#/components/schemas/channelOptionsWhatsapp"
- $ref: "#/components/schemas/outboundMessageCommon"
- allOf:
- required:
- message_type
- $ref: "#/components/schemas/Custom"
- $ref: "#/components/schemas/channelOptionsWhatsapp"
- $ref: "#/components/schemas/outboundMessageCommon"
- title: Messenger
x-tab-id: Messenger
example:
message_type: text
text: 'Nexmo Verification code: 12345.<br />Valid for 10 minutes.'
to: '0123456789'
from: '9876543210'
channel: messenger
oneOf:
- allOf:
- $ref: "#/components/schemas/Text"
- properties:
text:
description: >
The text of message to send; limited to 640
characters, including unicode.
- $ref: "#/components/schemas/channelOptionsMessenger"
- $ref: "#/components/schemas/outboundMessageCommon"
- allOf:
- $ref: "#/components/schemas/Image"
- properties:
image:
properties:
url:
type: string
description: |
The URL of the image attachment.
Supports `.jpg`, `.jpeg`, `.png` and `.gif`.
example: https://example.com/image.jpg
- $ref: "#/components/schemas/channelOptionsMessenger"
- $ref: "#/components/schemas/outboundMessageCommon"
- allOf:
- $ref: "#/components/schemas/Audio"
- properties:
audio:
properties:
url:
description: |
The URL of the audio attachment.
Only supports `.mp3` files
minLength: 10
maxLength: 2000
- $ref: "#/components/schemas/channelOptionsMessenger"
- $ref: "#/components/schemas/outboundMessageCommon"
- allOf:
- $ref: "#/components/schemas/Video"
- properties:
video:
properties:
url:
description: >
The URL of the video attachment.
Supports `.mp4` files. Note, only `H.264` video codec and `AAC` audio codec is supported.
- $ref: "#/components/schemas/channelOptionsMessenger"
- $ref: "#/components/schemas/outboundMessageCommon"
- allOf:
- $ref: "#/components/schemas/File"
- properties:
file:
properties:
url:
description: >
The URL of the file attachment.
Supports a wide range of attachments including `.zip`, `.csv` and `.pdf`.
- $ref: "#/components/schemas/channelOptionsMessenger"
- $ref: "#/components/schemas/outboundMessageCommon"
- title: Viber
x-tab-id: Viber
example:
message_type: text
text: 'Nexmo Verification code: 12345.<br />Valid for 10 minutes.'
to: '447700900000'
from: '9876543210'
channel: viber_service
oneOf:
- allOf:
- $ref: "#/components/schemas/Text"
- properties:
text:
description: >
The text of message to send; limited to 1000
characters, including unicode.
- $ref: "#/components/schemas/channelOptionsViberWithButton"
- $ref: "#/components/schemas/outboundMessageCommon"
- allOf:
- $ref: "#/components/schemas/Image"
- properties:
image:
properties:
url:
type: string
description: |
The URL of the image attachment.
Supports `.jpg`, `.jpeg`, and `.png`.
example: https://example.com/image.jpg
caption:
type: string
description: A caption to accompany the image. Required if the message includes
an action button.
example: Check out this new promotion
- $ref: "#/components/schemas/channelOptionsViberWithButton"
- $ref: "#/components/schemas/outboundMessageCommon"
- allOf:
- $ref: "#/components/schemas/Video"
- properties:
video:
properties:
url:
type: string
description: The URL of the video attachment.
example: https://example.com/image.jpg
caption:
type: string
description: Text caption to accompany message.
example: Check out this new video
thumb_url:
type: string
maxLength: 1000
description: URL to an image file for a thumbnail preview of the video.
example: https://example.com/file1.jpg
required:
- url
- duration
- file_size
- thumb_url
- $ref: "#/components/schemas/channelOptionsViberVideo"
- $ref: "#/components/schemas/outboundMessageCommon"
- allOf:
- $ref: "#/components/schemas/File"
- properties:
file:
description: "An object containing details of the file to be sent. Note: allowed
file types are `.doc,` `.docx`, `.rtf`, `.dot`,
`.dotx`, `.odt`, `.odf`, `.fodt`, `.txt`,
`.info`, `.pdf`, `.xps`, `.pdax`, `.eps`,
`.xls`, `.xlsx`, `.ods`, `.fods`, `.csv`,
`.xlsm`, `.xltx`. Maximum file size is 200MB"
properties:
url:
type: string
description: The URL for the file attachment *or* the path for the location of
the file attachement. If `name` is included,
can just be the path. If `name` is not
included, must include the filename and
extension.
example: https://example.com/files/
name:
type: string
maxLength: 25
description: The name and extension of the file.
example: example.pdf
- $ref: "#/components/schemas/channelOptionsViber"
- $ref: "#/components/schemas/outboundMessageCommon"
responses:
'202':
description: Accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/Response'
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'429':
$ref: '#/components/responses/too_many'
'500':
$ref: '#/components/responses/server_error'
'503':
$ref: '#/components/responses/service_unavailable'
callbacks:
message-status:
'{$request.body#/callback}':
post:
summary: Message Status
operationId: message-status
x-example-path: /webhooks/message-status
description: Webhooks provide information about events happening to the message
such as whether it has been sent, delivered or rejected by the
provider.
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/messageStatusSMS"
- $ref: "#/components/schemas/messageStatusMMS"
- $ref: "#/components/schemas/messageStatusWhatsApp"
- $ref: "#/components/schemas/messageStatusMessenger"
- $ref: "#/components/schemas/messageStatusViber"
responses:
'200':
description: Your server returns this code if it accepts the callback.
x-webhooks:
inbound-message:
"{$request.body#/callback}":
post:
summary: Inbound Message
operationId: inbound-message
x-example-path: /webhooks/inbound-message
description: An inbound message from a customer to you.
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/inboundMessageSMS"
- title: MMS
x-tab-id: MMS
oneOf:
- allOf:
- $ref: "#/components/schemas/inboundMessageMMS"
- $ref: "#/components/schemas/Text"
- properties:
text:
type: string
description: The text in the inbound message.
maxLength: 640
example: This is sample text.
- allOf:
- $ref: "#/components/schemas/inboundMessageMMS"
- $ref: "#/components/schemas/Image"
- properties:
image:
required:
- url
properties:
# --- truncated at 32 KB (111 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kpn/refs/heads/main/openapi/vonage-messages-openapi.yml