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.


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.


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 - Nexmo.
  4. Click on Request for testing. An e‑mail message opens. Just click on the Send button.

After the testing request has been accepted, you will receive instructions via e‑mail and the Nexmo 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 Nexmo 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 - WhatsApp Business example

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.