The smarter way to deliver messages.

Simplify multi-channel message delivery with one powerful API.


Overview

The Dispatch API enables you to send messages to users using a multiple channel strategy with a fallback condition.

Introduction

The Dispatch API provides the mechanism to specify their success conditions and act accordingly.

In the conceptual model we have an example with a failover list of two elements. The origin user wants to send a message to the receiver user and defines the order to try first in Viber and then SMS as a failover.

Conceptual Model

General Picture

 

Concepts

Definitions

Messaging channels: a channel is a user-facing messenger from which end users can send messages.

Failover: a 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: defines the criteria under which the current channel is considered to be failing and when the next one on the list needs to be triggered. The criteria are based on two variables:

  • Condition status: action to happen to consider the current step successful. The success of this step depends on whether or not this action happened before the time expired.
  • Expiry time: the time window within which the status had to be fulfilled.

Example:

If you send a message through Viber and the message is not delivered within 10 seconds, the same message will be sent through 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 preferred. The 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 sent back from the receiver. Applies only to the messaging channels that support replies.
  • Final-report: sends a POST request at the end of the failover with the details of the actions taken.

Prerequisites

You'll 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 checkmark 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. The API Store will then 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) which 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 messages 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. The API Store will then 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

Supported messaging channels:

  • SMS
  • Viber Service Messenger
  • Facebook
  • Whatsapp

Each Nexmo Application can have a maximum of 1 account for 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

Authentication

Oauth 2.0

For accessing and/or manipulating the resources, the client application (your application) needs to be granted permission to do so. The OAuth 2.0 standard defines a protocol that allows such third-party authorization through the use of access tokens. Access tokens are central in the protocol: these tokens, in the form of strings, are delivered by an authorization server (our authentication server) and they enable the client application to securely access protected data on behalf of the resource owner (the end user).

We use Client Credentials Grant which means the application makes the request to the authentication service by sending authorization credentials and the service responds with an access token along with other useful information.

Get Access Token

Copy your app's credentials and replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with the copied values, then execute the below cURL command to receive an access token.

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'

Note: If you are using cURL for Windows then please use the below command.

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 authorization 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": "BearerToken",
    "issued_at": "1521039195424",
    "client_id": "APP_CONSUMER_KEY",
    "access_token": "haf2SDl07E9N7RluNQ4kJ1TkGgso",
    "application_name": "6e38ed2d-48b1-4362-97d6-04254065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

Resources

Understanding Facebook Messaging

How to link your page

Send an email 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 to this website https://static.nexmo.com/messenger/ and follow the steps.

Understanding WhatsApp Messaging

How it works

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 Message Templates (MTMs). These were previously known as Highly Structured Messages (HSM).

WhatsApp requires that any message sent to a user for the first time, or 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 the 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.

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 to name, type, answer_url and event_url. Optional fields to be updated include 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 with the application uuid and the changes to name, type, answer_url and event_url. Optional fields to be updated include 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

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 Meaning
200 Success
201 Created
202 Accepted
400 Bad request
401 Unauthorized
404 Not Found
405 Method not Allowed
412 Precondition failed
429 Too many requests
500 Internal server error
502 Bad gateway
503 Service unavailable