Messages Documentation

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

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

Features and constraints

Features

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
      
        Code copied
        
            
      

         "type":"template",
         "template":{
            "name":"whatsapp:hsm:technology:nexmo:verify",
            "parameters":[
               {
                  "default":"Nexmo Verification"
               },
               {
                  "default":"64873"
               },
               {
                  "default":"10"
               }

      Example WhatsApp API call 
      
        Code copied
        
            
      

{
   "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 What's in it for you for more info on how to register and start testing 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 Developer Portal:

1. Go to 'My Developer Portal'.
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 Developer Portal 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
      
        Code copied
        
            
      

{
   "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
      
        Code copied
        
            
      

{
    "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.