Vonage's SMS API allows you to send and receive text messages to users around the globe through simple RESTful APIs. * Programmatically send and receive high volume of SMS anywhere in the world. * Build apps that scale with the web technologies that you are already using. * Send SMS with low latency and high delivery rates. * Receive SMS for free using SMS-enabled local numbers in countries around the world. * Only pay for what you use, nothing more.
swagger: '2.0'
info:
title: SMS-Vonage
version: "v1.1.1"
termsOfService: 'https://developer.kpn.com/legal'
contact:
name: API Support
email: api_developer@kpn.com
url: 'https://developer.kpn.com/support'
description: >-
Vonage's SMS API allows you to send and receive text messages to users around the globe through simple RESTful APIs.
* Programmatically send and receive high volume of SMS anywhere in the world.
* Build apps that scale with the web technologies that you are already using.
* Send SMS with low latency and high delivery rates.
* Receive SMS for free using SMS-enabled local numbers in countries around the world.
* Only pay for what you use, nothing more.
## [Source view](https://app.swaggerhub.com/apis/kpn/sms-nexmo/)<br/>
[Documentation view](https://app.swaggerhub.com/apis-docs/kpn/sms-nexmo/)
---
## [KPN Developer](https://developer.kpn.com/)<br/>
[Getting Started](https://developer.kpn.com/getting-started)
---
host: api-prd.kpn.com
basePath: /communication/nexmo/sms
externalDocs:
description: HTTP response headers
url: https://developer.kpn.com/documentation-response-headers
schemes:
- https
paths:
'/send':
post:
summary: Send SMS
tags:
- Send SMS
description: Send an outbound SMS
consumes:
- application/x-www-form-urlencoded
produces:
- application/json
parameters:
- in: formData
name: from
type: string
required: true
description: >-
The name or number the message should be sent from. Alphanumeric
senderID's are not supported in all countries, see Global Messaging
for more details. If alphanumeric, spaces will be ignored. Numbers
are specified in E.164 format. You can use any alphanumeric string up to 11 characters (or up to 15 numeric characters). It is recommended to send at least "3" characters (in case of alphanumeric), as it might show differently on different mobile devices. Moreover, alphanumeric cannot contain spaces as well.
example: `AcmeInc`.Note: If the value in your from parameter does not obey these rules it might be modified in transit or not delivered at all.
- in: formData
name: to
type: string
required: true
description: >-
The number that the message should be sent to. Numbers are specified
in E.164 format.
minLength: 7
maxLength: 15
pattern: '\d{7,15}'
example: 447700900000
- in: formData
name: text
type: string
required: false
description: >-
The body of the message being sent. If your message contains
characters that can be encoded according to the GSM Standard and
Extended tables then you can set the `type` to `text`. If your
message contains characters outside this range, then you will need
to set the `type` to `unicode`.
example: Hello World!
- in: formData
name: ttl
type: integer
required: false
description: >-
**Advanced**: The duration in milliseconds the delivery of an SMS
will be attempted.§§ By default Vonage attempt delivery for 72 hours,
however the maximum effective value depends on the operator and is
typically 24 - 48 hours. We recommend this value should be kept at
its default or at least 30 minutes.
minimum: 20000
maximum: 604800000
example: 900000
#default: 259200000
- in: formData
name: status-report-req
type: boolean
required: false
default: false
description: >-
**Advanced**: Boolean indicating if you like to receive a [Delivery
Receipt](/messaging/sms/building-blocks/receive-a-delivery-receipt).'
- in: formData
name: callback
type: string
required: false
# default: 'https://example.com/sms-dlr'
description: >-
**Advanced**: The webhook endpoint the delivery receipt for this
sms is sent to. This parameter overrides the webhook endpoint you
set in Dashboard.
- in: formData
name: message-class
type: integer
required: false
enum: [0,1,2,3]
description: >-
**Advanced**: The Data Coding Scheme value of the message
- in: formData
name: type
type: string
required: false
enum: ['text','binary','wappush','unicode','vcal','vcard']
description: >-
**Advanced**: The format of the message body'' example: text
#default: 'text'
- in: formData
name: vcard
type: string
required: false
description: >-
**Advanced**: A business card in [vCard
format](https://en.wikipedia.org/wiki/VCard). Depends on `type`
parameter having the value `vcard`.
format: vcard
- in: formData
name: vcal
type: string
required: false
description: >-
**Advanced**: A calendar event in [vCal
format](https://en.wikipedia.org/wiki/VCal). Depends on `type`
parameter having the value `vcal`.
format: vcal
- in: formData
name: body
type: string
required: false
# default: 0011223344556677
description: >-
**Advanced**: Hex encoded binary data. Depends on `type` parameter
having the value `binary`.
- in: formData
name: udh
type: string
required: false
# default: 06050415811581
description: >-
**Advanced**: Your custom Hex encoded [User Data
Header](https://en.wikipedia.org/wiki/User_Data_Header). Depends on
`type` parameter having the value `binary`.
- in: formData
name: protocol-id
type: integer
required: false
# default: 127
description: >-
**Advanced**: The value of the [protocol
identifier](https://en.wikipedia.org/wiki/GSM_03.40#Protocol_Identifier)
to use. Ensure that the value is aligned with `udh`.
- in: formData
name: title
type: string
required: false
# default: Welcome
description: >-
**Advanced**: The title for a wappush SMS. Depends on `type`
parameter having the value `wappush`.
- in: formData
name: url
type: string
required: false
# default: https://example.com
description: >-
**Advanced**: The URL of your website. Depends on `type` parameter
having the value `wappush`.
- in: formData
name: validity
type: string
required: false
description: >-
**Advanced**: The availability for an SMS in milliseconds. Depends
on `type` parameter having the value `wappush`.
- in: formData
name: client-ref
type: string
required: false
description: >-
**Advanced**: You can optionally include your own reference of up
to 40 characters.
responses:
'200':
description: OK
schema:
$ref: '#/definitions/SendSMSResponse'
'400':
description: Bad Request
schema:
$ref: '#/definitions/ErrorResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ErrorResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/ErrorResponse'
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/ErrorResponse'
'500':
description: Server Error
schema:
$ref: '#/definitions/ErrorResponse'
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/ErrorResponse'
security:
- OAuth2: []
/register:
post:
summary: Register callback URL to webhook for incoming messages
description: |
Handling inbound SMS with with API is easy. You just need to create a webhook endpoint and configure your number or account to point to the endpoint.
- If you are a test user try inbound messaging using below using 'Register Webhook endpoint'.
- If you are production user, use the `Phone Numbers API` to search, buy and manage your virtual number.
tags:
- Register webhook - Demo testing ONLY
consumes:
- application/x-www-form-urlencoded
parameters:
- in: formData
name: to
type: string
required: true
description: >-
The phone number you use for testing, without buying a virtual number. This is not applicable if you are a premium user.
Remember, this is only applicable if you are a demo user.
- in: formData
name: callback_url
type: string
required: true
description: >-
The callback URL for inbound SMS.
responses:
'200':
description: OK
schema:
$ref: '#/definitions/RegisterWebhookResponse'
'400':
description: Bad Request
schema:
$ref: '#/definitions/ErrorResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ErrorResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/ErrorResponse'
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/ErrorResponse'
'500':
description: Server Error
schema:
$ref: '#/definitions/ErrorResponse'
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/ErrorResponse'
security:
- OAuth2: []
'/https://example.com:webhooks/delivery-receipt':
post:
summary: Delivery Receipt
description: >-
This is not an API call but it is to showcase how the schema of delivery receipt will look like.
You can get delivery receipt by using `status-report-req` and `callback` parameters of 'Send SMS' request body.
tags:
- Callback
parameters:
- in: body
name: delivery-receipt
description: >-
The following are parameters sent in as a delivery receipt callback. You can subscribe to webhooks to receive notification when the delivery status of an SMS that you have sent with Vonage changes.
schema:
$ref: "#/definitions/DeliveryReceipt"
responses:
'200':
description: Your server returns this code if it accepts the callback
'/https://example.com:webhooks/inbound-sms':
post:
summary: Inbound SMS
description: >-
This is not an API call but it is to showcase how the schema of inbound SMS will look like.
You can get inbound SMS by registering your webhook URL using `Register webhook` and then passing 'inbound' header value as 'yes' in 'Send SMS'.
tags:
- Webhook
parameters:
- in: body
name: inbound-sms
description: >-
If you rent one or more virtual numbers from Vonage, inbound messages to that number are sent to your webhook endpoint. When you receive an inbound message, you must send a 2xx response. If you do not send a 2xx response Vonage will resend the inbound message for the next 24 hours.
schema:
$ref: "#/definitions/InboundMessage"
responses:
'200':
description: Your server returns this code if it accepts the callback
securityDefinitions:
OAuth2:
type: oauth2
tokenUrl: >-
https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials
flow: application
definitions:
RegisterWebhookRequest:
type: object
properties:
callback_url:
type: string
example: 'https://yourdomain.com/webhook'
description: your webhook endpoint on an HTTP server
title: Callback URL
to:
type: string
example: 3161111111
description: >-
Please enter the virtual number that has been provided to you. If you
are a test user then please enter the same mobile number that you are
using for test purposes. Individual virtual numbers can be alloted to
premium users which can be registered against the webhook enpoint.
title: Mobile Number
RegisterWebhookResponse:
type: object
properties:
message:
type: string
description: response message
example: Your callback url is registered.
SendSMSResponse:
type: object
properties:
message-count:
type: integer
description: The amount of messages in the request
example: 1
messages:
type: array
items:
$ref: '#/definitions/SendSMSResponseMessage'
SendSMSResponseMessage:
type: object
properties:
to:
type: string
description: The number the message was sent to
example: '447700900000'
message-id:
type: string
description: The ID of the message
example: 0A0000000123ABCD1
status:
type: string
description: "Code | Description\n -- | --\n '1' | You have exceeded the submission capacity allowed on this account. Please wait and retry.\n '2' | Your request is incomplete and missing some mandatory parameters.\n '3'\t| The value of one or more parameters is invalid.\n '4'\t| The api_key / api_secret you supplied is either invalid or disabled.\n '5'\t| There was an error processing your request in the Platform.\n '6' | The Platform was unable to process your request. For example, due to an unrecognised prefix for the phone number.\n '7'\t| The number you are trying to submit to is blacklisted and may not receive messages.\n '8' | The api_key you supplied is for an account that has been barred from submitting messages.\n '9' | Your pre-paid account does not have sufficient credit to process this message.\n '11' | This account is not provisioned for REST submission, you should use SMPP instead.\n '12' | The length of udh and body was greater than 140 octets for a binary type SMS request.\n '13' |\tMessage was not submitted because there was a communication failure.\n '14' |\tMessage was not submitted due to a verification failure in the submitted signature.\n '15' |\tDue to local regulations, the SenderID you set in from in the request was not accepted. Please check the Global messaging section.\n '16' |\tInvalid TTL\tThe value of ttl in your request was invalid.\n '19' |\tYour request makes use of a facility that is not enabled on your account.\n '20' |\tThe value of message-class in your request was out of range. See https://en.wikipedia.org/wiki/Data_Coding_Scheme.\n '23' |\tYou did not include https in the URL you set in callback.\n '29' |\tThe phone number you set in to is not in your pre-approved destination list. To send messages to this phone number, add it using Dashboard.\n '34' |\tThe phone number you supplied in the to parameter of your request was either missing or invalid.\n"
example: '0'
network:
type: string
description: The ID of the network of the recipient
example: '12345'
DeliveryReceipt:
type: object
properties:
msisdn:
type: string
description: The number the message was sent to. Numbers are specified in E.164 format.
example: '447700900000'
to:
type: string
description: The SenderID you set in `from` in your request.
example: AcmeInc
network-code:
type: string
description: The Mobile Country Code Mobile Network Code (MCCMNC) of the carrier this phone number is registered with.
example: '12345'
messageId:
type: string
description: The Vonage ID for this message.
example: '0A0000001234567B'
price:
type: string
description: The cost of the message
example: '0.03330000'
status:
type: string
description: A code that explains where the message is in the delivery process.
example: 'delivered'
x-possible-values:
- delivered
- expired
- failed
- rejected
- accepted
- buffered
- unknown
scts:
type: string
description: When the DLR was recieved from the carrier in the following format `YYMMDDHHMM`. For example, `2001011400` is at `2020-01-01 14:00`
example: '2001011400'
err-code:
type: string
description: The status of the request. Will be a non `0` value if there has been an error. See the [SMS error reference](/api-errors/sms) for more details
example: '0'
message-timestamp:
description: The time when Vonage started to push this Delivery Receipt to your webhook endpoint.
type: string
example: 2020-01-01 12:00:00
InboundMessage:
type: object
properties:
msisdn:
type: string
description: >-
`required`
The phone number that this inbound message was sent from. Numbers are specified in E.164 format.
example: '447700900001'
to:
type: string
description: >-
`required`
The phone number the message was sent to. **This is your virtual number**. Numbers are specified in E.164 format.
example: '447700900000'
messageId:
type: string
description: >-
`required`
The ID of the message (required)
example: 0A0000000123ABCD1
text:
type: string
description: >-
`required`
The message body for this inbound message. (required)
example: Hello world
type:
type: string
description: |
Possible values are: >-
`required`
- `text` - standard text.
- `unicode` - URLencoded unicode . This is valid for standard GSM, Arabic, Chinese, double-encoded characters and so on.
- `binary` - a binary message.
example: 'text'
keyword:
type: string
description: >-
`required`
The first word in the message body. This is typically used with short codes.
example: Hello
message-timestamp:
description: >-
`required`
The time when Vonage started to push this Delivery Receipt to your webhook endpoint.
type: string
example: 2020-01-01 12:00:00
timestamp:
description: A unix timestamp representation of message-timestamp.
type: string
example: "1578787200"
nonce:
type: string
description: A random string that forms part of the signed set of parameters, it adds an extra element of unpredictability into the signature for the request. You use the nonce and timestamp parameters with your shared secret to calculate and validate the signature for inbound messages.
example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
concat:
type: string
description: True - if this is a concatenated message.
example: 'true'
concat-ref:
type: string
description: The transaction reference. All parts of this message share this value.
example: '1'
concat-total:
type: string
description: The number of parts in this concatenated message.
example: '3'
concat-part:
type: string
description: The number of this part in the message. Counting starts at 1.
example: '2'
data:
type: string
format: binary
description: The content of this message, if type is binary.
udh:
type: string
description: The hex encoded User Data Header, if type is binary
ErrorResponse:
type: object
properties:
transactionId:
type: string
description: transaction id of the the request
title: Transaction ID
status:
type: string
description: Status
title: Status
name:
type: string
description: Error name
title: Error name
message:
type: string
description: Error message
title: Error message
info:
type: string
description: Additional information about error
title: Info