Nexmo Dispatch API

API reference on SwaggerHub

Introduction

The Dispatch API by Nexmo enables sending customer messages using a multiple channel strategy with fallback condition. You can send SMS text messages, MMS messages, WhatsApp messages and Facebook messages and Viber Service messages. The API provides a mechanism to specify the success conditions for messages and redirect to set fallback channels accordingly.

Conceptual model

The model shows an example with a failover list of two elements. In this case, the sending user wants to send a message to a receiving user and defines the order to try sending via Viber first and then via SMS as failover.

Conceptual model

Definitions

Messaging channels

A channel is a user facing messenger from which end-users can send messages

Failover

Backup operational mode in which the functions of a system component are assumed by secondary system components when the primary component becomes unavailable.

Failover condition

The failover applied to the messaging channels. Defines the criteria where the current channels fails and needs to trigger the next one from the list. The criteria is based on 2 variables:

  • Condition status: Action to happen to consider the current step successful. The success of this step depends if this action happened before the time expired.
  • Expiry time: The time window the status had to be fulfilled.

Example:

Send message through Viber and if it’s not delivered in 10s, send the same message using SMS. Webhook is 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. Dispatch API uses the following webhooks:

  • Message-status: Sends a POST request with any update related to the status of the message.
  • Inbound-message: Receives the message send back from the receiver. Applies only to the messaging channels that supports replies.
  • Final-report: Sends a POST request at the end of the failover with the details of the actions taken.

API workflow

Sequence diagram

Prerequirements

You need a Nexmo application instance to send messages.

Viber

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

In order to get started with Viber Service Messages you will need to email api_developer@kpn.com. API Store is going to handle the creation of your Viber Business account with the help of an official partner and come back to you with a a Viber Service Messages ID.

Facebook Messenger

Only an individual may have a Facebook Profile, whereas a business must have a Facebook Page. A Facebook user must initiate communication using Facebook Messenger via the business's Facebook Page. A message from the business to the Facebook user will otherwise be refused.

Facebook Messenger uses its own form of IDs for the Facebook User and the Facebook Page: - Facebook User (profile) - Page-Scoped ID (PSID) - Facebook Page (business) - Page ID

The Facebook User will have a Page-scoped ID (PSID) and this is unique for each Facebook Profile. The business can only obtain the PSID of a user when the user sends a message to the business. In Facebook Messenger, the default is for the customer to initiate a conversation with a business.

In order to get started with Facebook Messenger you will need to link your business's Facebook Page to the API Store. Contact api_developer@kpn.com with your application ID and your Facebook page ID.

You can then test things by sending a message as a Facebook User to your own Facebook Page. At this point you will receive an inbound message webhook to your server with the PSID of the Facebook user. You can now use this PSID to send a message back to the user.

WhatsApp

WhatsApp Business Solution can only be sent by businesses that have been approved by WhatsApp. This business profile will also have a green verified label to indicate that it is a legitimate business.

In order to get started with WhatsApp you will need to email api_developer@kpn.com. API Store is going to handle the creation of your WhatsApp Business account with the help of an official partner. Currently WhatsApp is in Limited Availability and only a certain number of customers will be onboarded.

Features and constraints

Features

Supported messaging channels:

  • SMS
  • Viber Service Messenger
  • Facebook
  • Whatsapp

Constraints

  • Each Nexmo Application can have a max of 1 account of each of the following platforms:

    • Viber
    • Facebook
    • Whatsapp
  • The WhatsApp Business Solution may not be used to send any messages to or receive messages from the following countries: Crimea, Cuba, Iran, North Korea and Syria.

Getting started

Setting up your third-party accounts

Set up Facebook Messaging

Send an e-mail to api_developer@kpn.com to apply for the JWT token. The Application ID and developer application name are required in order to generate the JWT token.

Log in in this website https://static.nexmo.com/messenger/ and follow the steps.

Set up WhatsApp Business Messenger

A business can start a conversation with a user and a user can start a conversation with a business.

WhatsApp has a core concept of Messages Templates (MTM). These were previously known as Highly Structured Messages (HSM).

WhatsApp requires that a message sent to a user for the first time, or is outside the Customer Care Window, is an MTM message.

The MTM allows a business to send just the template identifier along with the appropriate parameters instead of the full message content.

New templates need to be approved by WhatsApp. Please contact the API Store to submit the templates. Over time API Store will also add generic templates that can be used by all businesses.

MTMs are designed to reduce the likelihood of spam to users on WhatsApp.

For the purpose of testing, the API Store provides a template created by Nexmo, whatsapp:hsm:technology:nexmo:verify, that you can use:

{{1}} code: {{2}}. Valid for {{3}} minutes.
{
   "from":{
      "type":"whatsapp",
      "number":"WHATSAPP_NUMBER"
   },
   "to":{
      "type":"whatsapp",
      "number":"TO_NUMBER"
   },
   "message":{
      "content":{
         "type":"template",
         "template":{
            "name":"whatsapp:hsm:technology:nexmo:verify",
            "parameters":[
               {
                  "default":"Nexmo Verification"
               },
               {
                  "default":"64873"
               },
               {
                  "default":"10"
               }
            ]
         }
      }
   }
}

Important WhatsApp rules

If your customer initiates messaging with you, WhatsApp will not charge you for any messages (including MTMs) that you send back to the customer, for up to 24 hours following the last message that your customer sent you. This 24 hour period is known as 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.

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 on Try out
  3. Edit the request body by filling the name, type, status_url and inbound_url
  4. Click on execute button
  5. Check the response code and message

Postman:

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

Remember the application id because it will be needed to use Dispatch

Check owned applications

SwaggerHub:

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

Postman:

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

Check application details

SwaggerHub:

  1. Select GET /applications/{uuid}
  2. Click on Try out
  3. Edit the parameters by filling the application uuid
  4. Click on execute button
  5. Check the response code and message

Postman:

  1. Click on (GET) Retrieve an application resource
  2. Fill the application uuid in the URL
  3. Click on send
  4. Check the response code and message

Update application configuration

SwaggerHub:

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

Postman:

  1. Click on (PUT) update an application resource
  2. Fill the parameters by filling the application uuid and the changes on name, type, answer_url and event_url. Optional fields to be updated include are answer_method and event_method
  3. Click on send
  4. Check the response code and message

Delete an application

SwaggerHub:

  1. Select DELETE /applications/{uuid}
  2. Click on Try out
  3. Edit the parameters by filling the application uuid
  4. Click on execute button
  5. Check the response code and message

Postman:

  1. Click on (DELETE) Destroy an application resource
  2. Fill the parameters by filling the application uuid
  3. Click on send
  4. Check the response code and message

Send message with failover

SwaggerHub:

  1. Select POST /dispatch
  2. Click on Try out
  3. Edit the applicationID parameter and customize the body with your workflow
  4. Click on execute button
  5. Check the response code and message

Postman:

  1. Click on (POST) Send Message resource
  2. Fill the ApplicationId in the header and the body with the information to send messages.
  3. Click on send
  4. Check the response code and message

Facebook Messenger Example

{
  "from": 
    {
      "type": "messenger",
      "id": "FB_SENDER_ID"
    },
  "to": 
    {
      "type": "messenger", 
      "id": "FB_RECIPIENT_ID"
    },
  "message": 
    {
      "content": 
        {
          "type": "text",
          "text": "This is a Facebook Messenger message sent from the Dispatch API"
        }
    }
}

Viber Example

{
  "from": 
    {
      "type": "viber_service_msg",
      "id": "VIBER_SERVICE_MESSAGE_ID"
    },
  "to": 
    {
      "type": "viber_service_msg", 
      "id": "TO_NUMBER"
    },
  "message": 
    {
      "content": 
        {
          "type": "text",
          "text": "This is a Viber Service Message sent from the Dispatch API"
        }
    }
}

WhatsApp Example

Steps: 1. Send MTM template 2. Send Message to WhatsApp

MTM Template example:

{
  "template":"failover",
  "workflow":[
    {
      "from":{
        "type":"whatsapp",
        "number":"$WHATSAPP_NUMBER"
      },
      "to":{
        "type":"whatsapp",
        "number":"$TO_NUMBER"
      },
      "message":{
        "content":{
          "type":"template",
          "template":{
            "name":"whatsapp:hsm:technology:nexmo:verify",
            "parameters":[
              {
                "default":"Nexmo Verification"
              },
              {
                "default":"64873"
              },
              {
                "default":"10"
              }
            ]
          }
        }
      },
      "failover":{
        "expiry_time":600,
        "condition_status":"read"
      }
    },
    {
      "from":{
        "type":"sms",
        "number":"$FROM_NUMBER"
      },
      "to":{
        "type":"sms",
        "number":"$TO_NUMBER"
      },
      "message":{
        "content":{
          "type":"text",
          "text":"This is an SMS sent via the Dispatch API"
        }
      }
    }
  ]
}

WhatsApp Message example:

{
  "template":"failover",
  "workflow":[
    {
      "from":{
        "type":"whatsapp",
        "number":"447418342140"
      },
      "to":{
        "type":"whatsapp",
        "number":"918197792563"
      },
      "message":{
        "content":{
          "type":"text",
          "text":"This is logging message for test "
        }
      },
      "failover":{
        "expiry_time":60,
        "condition_status":"read"
      }
    },
    {
      "from":{
        "type":"sms",
        "number":"31647356950"
      },
      "to":{
        "type":"sms",
        "number":"31617185666"
      },
      "message":{
        "content":{
          "type":"text",
          "text":"This is a fallback SMS sent from the Workflows API for whatsapp messenger"
        }
      }
    }
  ]
}

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