beta
Nexmo

Dispatch - Nexmo

Nexmo

Make sure your customers quickly receive your messages

Proactively re-routes messages to ensure optimal delivery

  • Communication

API reference on SwaggerHub

Introduction

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

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. Origin user wants to send a message to Receiver user and defines the order to try first in Viber and then SMS as failover.

Conceptual model

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

A Nexmo application instance is needed 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

Make sure you have a registered account on the API Store and created an application on the portal, to receive the associated client ID and secret. These are neccessary to request an access token. You will receive these after your app is approved on te API Store.

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: those 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 among other useful information.

Get Access Token

Copy your app's credentials (Consumer Key & Consumer Secret) to be used in the Authentication requests below.

Authentication in SwaggerHub:

  1. Upon loading completed within SwaggerHub, look top right for the Authorize button and click it.
  2. In the form, fill in client_id and client_secret fields, using your app's credentials.
  3. Click Authorize.
  4. Now you are authorized to issue the requests provided.

Authentication in Postman:

  1. Select Get Access Token from the collection.
  2. Make sure the right Environment corresponding to the API is selected.
  3. Edit the environment variables client_id and client_secret, using your app's credentials.
  4. Check the response code and message.
  5. Press the Send button to get the access token.
  6. Now you are authorized to issue the other requests in the collection.

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": "Bearer",
    "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"
}

How to...

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.

Login in 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 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.

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

API versions

Version   Description
1.0   Initial version