Introduction

Nexmo is now called Vonage, but there are still references to Nexmo in our URLs, code snippets and message templates.

Vonage's (formerly called Nexmo) Messages API consists of multiple messaging APIs that act as a gateway to the following channels:

  • WhatsApp Business.
  • Viber Service Messages.
  • Facebook Messenger.
  • SMS text messaging.

The Vonage Messages API does this by normalizing the information across all channels to abstracted parameters to, from and message.


API specification

Test the API on SwaggerHub


Base URL

https://api-prd.kpn.com/communication/nexmo


Conceptual model

Conceptual model


Definitions

inbound_url

The URL to which inbound messages are sent.

status_url

The URL to which the status of each message is sent. The status value can be submitted, delivered, read, rejected or undeliverable.

UUID

A universally unique identifier (UUID) is a 128-bit number used to identify information in computer systems.

Webhook

Webhooks are an extension of an API, but instead of your code requesting data from Vonage, Vonage sends data to you. The data arrives in a web request to your application. A webhook may be the result of an earlier API call (this type of webhook is also called a "callback"). Webhooks are also used to notify your application of events such as an incoming call or message.


API workflow

API workflow


Features and constraints

Features

Channel Outbound  Text Outbound  Image Outbound  Audio Outbound  Video Outbound  File Outbound  Template
WhatsApp YES YES YES YES YES YES
Viber Service   Messages YES YES N/A N/A N/A YES
Facebook   Messenger YES YES YES YES YES YES
SMS YES N/A N/A N/A N/A N/A
Channel Inbound  Text Inbound  Image Inbound  Audio Inbound  Video Inbound  File Inbound  Template
WhatsApp YES YES YES YES YES YES
Viber Service   Messages YES N/A N/A N/A N/A YES
Facebook   Messenger YES YES YES YES YES YES

Constraints

  • Each Messages application can have a maximum of 1 account of each of the following platforms:

    • WhatsApp Business.
    • Viber Service Messages.
    • Facebook Messenger.

WhatsApp

  • WhatsApp Business messages can only be sent and received by businesses that have been approved by WhatsApp. Your business profile should also have a green verified label to indicate that it is a legitimate business.
  • WhatsApp Business cannot be used to send to or receive messages from the following countries:

    • Crimea.
    • Cuba.
    • Iran.
    • North Korea.
    • Syria.

WhatsApp Message Templates

  • WhatsApp has specific rules for message templates. A WhatsApp message sent to a user for the first time, or outside of the 'Customer Care Window' (the 24 hours after the last message your customer sent you), is required to be a WhatsApp Message Template Message (MTM). MTMs were previously known as Highly Structured Messages (HSM).
  • MTM allows a business to send the template identifier along with the appropriate parameters, instead of the full message content. MTMs are designed to reduce the likelihood of spam being sent to users on WhatsApp. Do you want to use your own template? Please contact us at KPN to submit any new templates, as new templates need to be approved by WhatsApp. Over time, we will also add generic templates that can be used by all businesses. > If your customer initiates messaging with you, WhatsApp will not charge you for any messages (including MTMs) that you send back to the customer within the Customer Care Window. Any additional message you send to that customer beyond the Customer Care Window must be an MTM, for which WhatsApp will charge you.
  • For the purpose of testing, you can use the following template created by Vonage: whatsapp:hsm:technology:nexmo:verify.

The MTM parameters are an array.

^^Example MTM^^
         "type":"template",
         "template":{
            "name":"whatsapp:hsm:technology:nexmo:verify",
            "parameters":[
               {
                  "default":"Nexmo Verification"
               },
               {
                  "default":"64873"
               },
               {
                  "default":"10"
               }
Parameter Description Example
default (1) MTM name Vonage (formerly called Nexmo) Verification
default (2) Valid for 64873
default (3) Time in minutes 10
^^Example WhatsApp API call ^^
{
   "from":{
      "type":"whatsapp",
      "number":"WHATSAPP_FROM_NUMBER"
   },
   "to":{
      "type":"whatsapp",
      "number":"WHATSAPP_TO_NUMBER"
   },
   "message":{
      "content":{
         "type":"template",
         "template":{
            "name":"whatsapp:hsm:technology:nexmo:verify",
            "parameters":[
               {
                  "default":"Nexmo Verification"
               },
               {
                  "default":"64873"
               },
               {
                  "default":"10"
               }
            ]
         }
      },
      "whatsapp": {
        "policy": "deterministic",
        "locale": "en-GB"
      }
   }
}

Viber

  • Viber Service Messages can only be sent by businesses that have been approved by Viber. The business profile should also have a green check to indicate that it is a legitimate business.

Facebook

  • A Facebook user can only initiate communication with your business using Facebook Messenger via your business's Facebook page. A message from your business to the Facebook user will otherwise be refused.
  • Facebook Messenger uses its own IDs for users and business pages:

    • Facebook User (profile): Page-Scoped ID (PSID).
    • Facebook Page (business): Page ID.
  • A user will have a Page-scoped ID (PSID), which is a unique ID for each Facebook user profile. A business can only obtain the PSID of a user when the user sends a message to the business via their page. In Facebook Messenger, the default is for the customer to initiate the conversation with a business.


Getting started

Make sure you've read Getting Started for more info on how to register your application and start trying out our APIs.

Authentication

The API follows the KPN Store API Authentication Standard to secure the API. It includes the use of OAuth 2.0 client_id and client_secret to receive an access token.

Go to the Authentication tab on top of this page to find out how to:

  • Authenticate to an API using cURL.
  • Authenticate to an API on Swaggerhub.
  • Import Open API Specifications (OAS), also called Swagger files into Postman.

Setting up your third-party accounts

WhatsApp

To get started with WhatsApp you will need to e-mail us your API application ID. We will handle the creation of your WhatsApp Business Account with the help of an official partner. Currently, WhatsApp has limited availability and only a certain number of customers will be onboarded.

Viber

To get started with Viber Service Messages you will need to e-mail us your API application key. We will handle the creation of your Viber Business Account with the help of an official partner and come back to you with a Viber Service Messages ID.

Facebook

To get started with Facebook Messenger you will need to link your business's Facebook page to the API. In order to do this, login at Vonage's Facebook link page and follow their steps.

You can test whether Facebook Messenger is enabled by sending a message as a Facebook test user to your business' Facebook page. You will receive an inbound message webhook at your server with the ID of the test user. You can use this ID to send a message back to the user.


How to...

Test the API in the Sandbox

You can now test WhatsApp Business in the Sandbox.

My API Store:

  1. Go to 'My API Store'.
  2. Click on 'Sandbox'.
  3. In the section 'Additional APIs to request for testing', go to 'Messages - Vonage'.
  4. Click on the button 'Request to test'.

A note confirms your request. After the request has been accepted, you will receive instructions via e‑mail and the Vonage Messages API is displayed in the 'APIs ready for testing' section of the Sandbox. Use your API Store credentials to test the API in SwaggerHub.

Create an application

SwaggerHub:

  1. Select POST /applications.
  2. Click 'Try it out'.
  3. Edit the request body by filling out the name, type, status_url and inbound_url.
  4. Click 'Execute'.
  5. Check the response code and message.

Postman:

  1. Select (POST) Create new application resource.
  2. Fill out the name, type, status_url and inbound_url.
  3. Click 'Send'.
  4. Check the response code and message.

Remember the application ID. You will need it to use the Vonage Messages API.

Check owned applications

SwaggerHub:

  1. Select GET /applications.
  2. Click 'Try it out'.
  3. Edit the parameters by filling out the page_index and page_size.
  4. Click 'Execute'.
  5. Check the response code and message.

Postman:

  1. Select (GET) Retrieve your applications resource.
  2. Fill out the name, page_index and page_size.
  3. Click 'Send'.
  4. Check the response code and message.

Check application details

SwaggerHub:

  1. Select GET /applications/{uuid}.
  2. Click 'Try it out'.
  3. Edit the parameters by filling out the application UUID.
  4. Click 'Execute'.
  5. Check the response code and message.

Postman:

  1. Select (GET) Retrieve an application resource.
  2. Fill out the application UUIDin the URL.
  3. Click 'Send'.
  4. Check the response code and message.

Update application configuration

SwaggerHub:

  1. Select PUT /applications/{uuid}.
  2. Click 'Try it out'.
  3. Edit the parameters by filling out the application UUID and the changes on name, type, answer_url and event_url. Optional fields to be updated include answer_method and event_method.
  4. Click 'Execute'.
  5. Check the response code and message.

Postman:

  1. Select (PUT) update an application resource.
  2. Edit the parameters by filling out the application UUID and the changes on name, type, answer_url and event_url. Optional fields to be updated include answer_method and event_method.
  3. Click 'Send'.
  4. Check the response code and message.

Delete an application

SwaggerHub:

  1. Select DELETE /applications/{uuid}.
  2. Click 'Try it out'.
  3. Edit the parameters by filling out the application UUID.
  4. Click 'Execute'.
  5. Check the response code and message.

Postman:

  1. Select (DELETE) Destroy an application resource.
  2. Edit the parameters by filling out the application UUID.
  3. Click 'Send'.
  4. Check the response code and message.

Send a message with WhatsApp Business

SwaggerHub:

  1. Select POST / in message resource.
  2. Click 'Try it out'.
  3. Enter your application ID and customize the body with your custom data for to, from, type (whatsapp) and message.
  4. Click 'Execute'.
  5. Check the response code and message.

Postman:

  1. Select (POST) Send Message resource.
  2. Fill out the application ID in the header and the body with your custom data for to, from, type (whatsapp) and message.
  3. Click 'Send'.
  4. Check the response code and message.

WhatsApp example

Steps:

  1. Send MTM template.
  2. Send message to WhatsApp Business.
^^WhatsApp Business MTM template example^^
{
   "from":{
      "type":"whatsapp",
      "number":"WHATSAPP_FROM_NUMBER"
   },
   "to":{
      "type":"whatsapp",
      "number":"WHATSAPP_TO_NUMBER"
   },
   "message":{
      "content":{
         "type":"template",
         "template":{
            "name":"whatsapp:hsm:technology:nexmo:verify",
            "parameters":[
               {
                  "default":"Nexmo Verification"
               },
               {
                  "default":"64873"
               },
               {
                  "default":"10"
               }
            ]
         }
      },
      "whatsapp": {
        "policy": "deterministic",
        "locale": "en-GB"
      }
   }
}
^^WhatsApp message example^^
{
    "from":{
        "type":"whatsapp",
        "number":"4474xxxxxxxx"
    },
    "to":{
        "type":"whatsapp",
        "number":"9181xxxxxxxx"
   },
   "message":{
      "content":{
         "type":"text",
         "text":"Hello there, This Message is from Message Flow API ."
      }
   }
}

Apart form the WhatsApp message content type text, you can also use other types, such as template, custom, file, image, audio and video. The last 4 types, have the property url and point to a public URL where the files, image, audio or video is hosted. The maximum outbound media size is 64 Mb.


Return codes

Code Description
200 Success.
201 Created.
202 Accepted.
302 Found. Link in location header.
400 Bad request.
401 Unauthorized.
403 Forbidden.
404 Not found.
405 Method not allowed.
412 Precondition failed.
429 Too many requests.
500 Internal server error.
502 Bad gateway.
503 Service unavailable.


HTTP response headers

The following tables display the standard response headers that are returned with each API response:

Standard response field name Description
sunset This field will be populated with the deprecation details. By default the value is n/a.
api-version Indicates the API version you have used.
quota-interval Used to specify an integer (for example, 1, 2, 5, 60, and so on) that will be paired with the quota-time-unit you specify (minute, hour, day, week, or month) to determine a time period during which the quota use is calculated.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-limit Number of API calls an user can make within a given time period.
If this limit is exceeded, the user will be throttled and API requests will fail.
quota-reset-UTC All quota times are set to the Coordinated Universal Time (UTC) time zone.
quota-time-unit Used to specify the unit of time applicable to the quota.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-used Number of API calls made within the quota.
strict-transport-security The HTTP Strict-Transport-Security (HSTS) response header lets a web site tell browsers that it should only be accessed using HTTPS, instead of using HTTP. All present and future subdomains will be HTTPS for a maximum of 1 year and access is blocked to pages or sub domains that can only be served over HTTP including HSTS preload lists of web browsers.
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload.
Access control field name Description
access-control-allow-credentials Tells browsers whether to expose the response to frontend JavaScript samp when the request's credentials mode (Request.credentials) is include.
When a request's credentials mode (Request.credentials) is include, browsers will only expose the response to frontend JavaScript samp if the Access-Control-Allow-Credentials value is true. Boolean.
access-control-allow-origin Indicates whether the response can be shared with requesting samp from the given origin.
access-control-allow-headers Used in response to a pre-flight request which includes the Access-Control-Request-Headers to indicate which HTTP headers can be used during the actual request.
access-control-max-age Indicates how long the results of a pre-flight request (that is the information contained in the Access-Control-Allow-Methods and Access-Control-Allow-Headers headers) can be cached.
access-control-allow-methods Indicates which HTTP methods are allowed on a particular endpoint for cross-origin requests.
For example: GET, PUT, POST, DELETE.
content-length The Content-Length entity header indicates the size of the entity-body, in bytes, sent to the recipient.
content-type The Content-Type entity header the client what the content type of the returned content actually is.

Mopinion feedback