Nexmo Messages API

API reference on SwaggerHub

Introduction

The Nexmo Messages API actually consists of multiple messaging APIs that act as a gateway to the following channels:

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

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

Conceptual model

Conceptual model

Definitions

Webhook

An event notification transmitted via HTTP. It’s triggered when something happens. The data may be formatted in whatever way the developer chooses, though JSON and XML are the most preferred.

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.

API workflow

Conceptual model

Features and constraints

Features

Channel Outbound  Text Outbound  Image Outbound  Audio Outbound  Video Outbound  File Outbound  Template
SMS YES N/A N/A N/A N/A N/A
VIBER SERVICE  MESSAGES YES YES N/A N/A N/A YES
FACEBOOK  MESSENGER YES YES YES YES YES YES
WHATSAPP YES NO NO NO NO YES

 

Channel Inbound  Text Inbound  Image Inbound  Audio Inbound  Video Inbound  File Inbound  Template
FACEBOOK  MESSENGER YES YES YES YES YES YES
WHATSAPP YES NO NO NO NO YES

 

Constraints

Each Nexmo application can have a max. of 1 account of each of the following platforms:

  • Viber Service Messages
  • Facebook Messenger
  • WhatsApp Business Solution

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.

WhatsApp

WhatsApp Business Solution 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.

The WhatsApp Business Solution cannot be used to send to or receive messages from the following countries:

  • Crimea
  • Cuba
  • Iran
  • North Korea
  • Syria

WhatsApp 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 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. Want to use your own template? Please contact us 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.

Note: 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, we provide a template created by Nexmo, whatsapp:hsm:technology:nexmo:verify, that you can use:

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

Getting started

Setting up your third-party accounts

Viber

In order 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

In order 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 Nexmo'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.

WhatsApp

In order 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.

Authentication

To authenticate you'll need to request an access token. Use your API Store app's credentials (Consumer Key and Consumer Secret) to make an authentication request. The authorization service returns a JSON message that contains the access_token field.

Use one of the following 3 options:

cURL

Execute below cURL command to receive an access token. Replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with your app's credentials.

curl -X POST \
 'https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -d 'client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET'

If you are using cURL for Windows, please use the command below instead.

curl -X POST "https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials" -H "content-type: application/x-www-form-urlencoded" -d "client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET"

The authentication service returns a JSON message that contains the access token field.

{
    "refresh_token_expires_in": "0",
    "api_product_list": "[xxxxxxx]",
    "api_product_list_json": [
        " xxxxxxx"
    ],
    "organization_name": "kpn",
    "developer_email": "demo123@kpn.com",
    "token_type": "Bearer",
    "issued_at": "1521039195424",
    "client_id": "APP_CONSUMER_KEY",
    "access_token": "haf2SDl07E9N7RluNQ4kJ1TkGgso",
    "application_name": "6e38edxxxxxxxxxxxxxxxx4065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

SwaggerHub

  1. Click on the Authorize button on the top right.
  2. In the form, fill in client_id and client_secret, using your app's credentials.
  3. Click Authorize.

Postman

When using Postman, you will have to import the Swagger file into a Postman collection as follows:

  1. Open the API reference on SwaggerHub.
  2. On the top right, click Export, click Download API and click 'YAML Unresolved'.
  3. In Postman from the menu click File and click Import... Choose the YAML file you downloaded in the previous step. A new collection will be added.
  4. Select Get Access Token from the collection.
  5. Make sure the right environment is selected, corresponding to the API.
  6. Edit the environment variables client_id and client_secret, using your app's credentials.
  7. Check the response code and message.
  8. Press the Send button to get an access token.

Note: Request variables are no longer linked to an environment, but to the collection.

How to...

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 because you will need it to use Nexmo Messages.

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 uuid in 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 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

SwaggerHub:

  1. Select POST / in message resource.
  2. Click Try it out.
  3. Edit the application ID parameter and customize the body with your custom data for to, from 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 and message.
  3. Click Send.
  4. Check the response code and message.

WhatsApp example

Steps:

  1. Send MTM template.
  2. Send message to WhatsApp.

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

Besides WhatsApp message content type "text", other types are "template", "custom", "file", "image", "audio" and "video". The last 4 types mentioned, take a property called "url" and points to a public url where the file/image/audio/video is hosted. Maxmimum outbound media size is 64mb.

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