Integrated Onboarding setup

The Integrated Onboarding allows you to offer a completely integrated signup experience to clients. After it is implemented, the Connect Button should trigger a pop-up which the client will use to create their WhatsApp Business API account.

After the signup is completed, the client will give you permission to manage their account. This will trigger a redirect back to your application, including all necessary data about the client, which you can use to retrieve the API key on their behalf. Make sure your redirect URL is set. Otherwise the permission can not be shared and will result in a client-facing error.

Here are a few screenshots to illustrate:

Integrated Onboarding works with both Partner Payment and Direct Payment. Different payment types have only two differences in the onboarding flow:

Partner paid clients will see a link to the terms of service on the sign up form.
Direct paid clients will see a checkbox to confirm the terms of service including the price list on a second page, which appears after the signup form and before the ES flow starts. This page also contains information about the price and a field to input a credit card.

Demo

Watch a quick Clickthrough showing how Integrated Onboarding works:

And a detailed explanation on how it works:

We have built a demo tool so you can see how to use and configure the 360dialog Connect Button and how to consume the associated redirects, which will allow you to onboard clients through the Integrated Onboarding.

Here is the Public Github Repo

Here is the Demo / Connect Button generator

Postman Collection

Here you can access a Postman Collection with all endpoints needed to implement Integrated Onboarding.

Registering a new client

When registering a new client, the whole flow should be followed.

See URL parameters available to understand how to make the process seamless for the client.

It is mandatory that the client registers the account under their own email address and Business Manager. Partners that register client accounts on behalf of clients will get banned.

Adding number to existing client

When adding a number to an existing client, the whole flow should be followed, but instead of creating a new account the client should log in their existing 360dialog Client Hub credentials.

See URL parameters available to understand how to make the process seamless for the client.

It is mandatory that the client registers the account under their own email address and Business Manager. Partners that register client accounts on behalf of clients will get banned.

Getting permission for active number

If you have clients registered under your 360dialog Partner Hub before Integrated Onboarding, you can set a permission flow for them so you can manage all clients the same way. See how to do this here. It is simply triggering step two of the onboarding flow.

This can also be used by existing clients with 360dialog Client Hub accounts to add new phone numbers to their existing accounts or to restart onboarding when the client closes the signup window before giving permission.

The choice if this number will be added to an existing WABA or a new one will be available after the signup process starts.

Getting permission in the 360dialog Client Hub

The client also has the option to give permission to a number directly in their 360dialog Client Hub.

To do so, the client can log in to the 360dialog Client Hub as usual → click on their profile in the bottom left → “Organization settings” → The current permissions will be listed and can be edited.

Building the integration

Integrated Onboarding works best with other Partner API features. We suggest that you read the Partner API documentation carefully to understand its almost unlimited possibilities and provide the best experience possible to your customers.

1. Set Redirect URL for your 360dialog Partner Hub

Set Redirect URL for your Partner Hub

PATCH https://hub.360dialog.io/api/v2/partners/{partner_id}

Request example

curl --request PATCH --url https://hub.360dialog.io/api/v2/partners/partner_id --header 'Authorization: ' --header 'Content-Type: application/json' --data '{ "webhook_url": "string", "partner_redirect_url": "string" }'

Path Parameters

Name

Type

Description

partner_id*

string

Your Partner Hub ID

Request Body

Name

Type

Description

webhook_url*

string

Your Webhook URL which needs to be previously created - see how in the Partner API integration document

partner_redirect_url*

string

The Redirect URL you will use

{
  "webhook_url": "string",
  "partner_redirect_url": "string",
  "brand_name": null,
  "id": "string",
  "logo_url": null,
  "onboarding_deeplink_add_params": true,
  "payment_plan": {},
  "payment_required": true
}

Important: To use the ConnectButton component of the 360dialog-connect-button package the redirect URL needs to match the route that has the button integrated.

2. Call the permission screen and consume the redirect

You can either create your own workflow or use the React.js button component provided by 360dialog.

If you have multiple 360dialog Partner Hubs (one for Partner Payment and one for Direct Payment, for example), you can create different buttons for each Hub and show them to users accordingly.

There are two options here:

2.1 Use our React.js Connect Button component

Install and add the 360dialog Connect Button via npm/yarn and follow the instructions on NPMJS

https://www.npmjs.com/package/360dialog-connect-button

npm install 360dialog-connect-button
yarn add 360dialog-connect-button

With the 360dialog Connect Button you will get the client ID, all newly permitted channel IDs as well as revoked channel IDs via a callback object that is provided to a callback function.

The button automatically handles the popup and redirect.

2.2 Build your own custom flow on any development language you choose

2.2.1 Call /permissions screen

In order to receive permissions to access clients' API keys, but also to enable the sign up flow for clients the following route needs to be called:

https://hub.360dialog.com/dashboard/app/<partner-id>/permissions

Independently of the development language you’re using, you should be able to use the browser’s open() method of the Window interface. It follows the syntax:

open(url, target, windowFeatures)

In the specific case this would result for example in the following method:

const windowFeatures = "toolbar=no, menubar=no, width=600, height=900, top=100, left=100"
open(https://hub.360dialog.com/dashboard/app/<partner-id>/permissions, "integratedOnboardingWindow", windowFeatures)

The permission screen is optimized to be opened in a popup without controls and a size of 600 px (width) by 900 px (height).

2.2.2 Consuming redirect

After the client signed in or up and granted permission to one or multiple phone numbers, your redirect URL is being called with query parameters.

Parameter in query

Description

client=<client-id>

Client ID

channels=[<channel-id>,<channel-id>]

Array of channel IDs, that were being permitted during the last call to the permission page

revoked=[<channel-id>]

OPTIONAL In case the client removes permissions to one or multiple numbers during the most recent call to the permission page, the channel IDs of the newly revoked channels will be present in the query

See the full list of possible URL Parameters here.

Usually the newly opened popup window should close automatically if the redirect URL matches the calling window’s URL. It will pass the query parameters to the calling window, where these can be retrieved by using the addEventListener() method together with the Window target:

window.addEventListener(
      "message",
      (event) => {
        const { data } = event;
        const queryString = `${data}`;        
        console.log(queryString);        
        // ?client=oaY9LLfUCL&channels=[y9MiLoCH]
      }, false
    );

To retrieve the parameters from the query string, e.g. ?client=oaY9LLfUCL&channels=[y9MiLoCH], the browser’s get() method of the URLSearchParams interface can be used.

let params = new URLSearchParams(queryString);
let channels = params.get("channels");
console.log(channels)
// [y9MiLoCH]
console.log(client)
// oaY9LLfUCL

Whenever a new channel is created and a channel permission is granted, you will receive a Webhook event. This can trigger the next step.

Learn how to use filters to get information about specific channels here.

If the newly opened popup window won't close after the redirect call (if redirect is the same as parent window URL), you can add a function that is executed on window.onload, ensuring that the parameters are processed only after the page has finished loading:

function processParams() {
  const params = window.location.search;
  if (window.opener) {
    window.opener.postMessage(params);
    window.close();
  }
}
window.onload = function() {
  processParams();
}

The code block below shows an example including explanations (your implementation may differ). You can initiate the Integrated Onboarding Flow with the function open360DialogPopup(window.location.origin)(remember that your implementation may differ):

// `processParams` function retrieves the current URL search parameters and posts them to the parent window.
// If there is an `opener` window, the function posts the parameters to it and closes the current window.
function processParams() {
  const params = window.location.search; // retrieve the current URL search parameters

  // Check if there is an opener window
  if (window.opener) {
    window.opener.postMessage(params); // post the parameters to the opener window
    window.close(); // close the current window
  }
}

// `window.onload` event is used to trigger the execution of the `processParams` function
// when the page has finished loading.
window.onload = function() {
  processParams();
};

// `open360DialogPopup` function opens a new window with the specified URL and options
// and adds a message event listener to the current window.
function open360DialogPopup(baseUrl) {
  window.removeEventListener("message", receiveMessage); // remove any existing message event listeners

  // Window options to be used in opening the new window
  const windowFeatures = "toolbar=no, menubar=no, width=600, height=900, top=100, left=100";
  const partnerId = "yourPartnerId";
  const redirectUrl = "yourRedirectUrl"; // additional redirect if needed - if you don't want to use your 
  // previously set partner redirect

  // Open the new window with the specified URL
  open(
    "https://hub.360dialog.com/dashboard/app/" + partnerId + "/permissions?redirect_url=" + redirectUrl,
    "integratedOnboardingWindow",
    windowFeatures
  );

  // Add a message event listener to the current window
  window.addEventListener("message", (event) => receiveMessage(event, baseUrl), false);
}

// `receiveMessage` function is the callback function that is executed when the message event is triggered.
// It retrieves the data from the event, sets it as the search parameters of the current URL,
// and returns if the origin of the event is not the same as the `baseUrl` or the type of `event.data` is an object.
const receiveMessage = (event, baseUrl) => {
  // Check if the event origin is not the same as `baseUrl` or `event.data` is an object.
  if (event.origin != baseUrl || typeof event.data === "object") {
    return;
  }
  const { data } = event; // retrieve the data from the event
  const redirectUrl = `${data}`; // create a redirect URL from the data
  window.location.search = redirectUrl; // set the redirect URL as the search parameters of the current URL
};

3. Create API key(s) via Partner API

Create an API key for each shared channel and store on your system for further use.

Create API key for a channel

POST https://hub.360dialog.io/api/v2/partners/{partner_id}/channels/{channel_id}/api_keys

Request example

curl --request POST --url https://hub.360dialog.io/api/v2/partners/partner_id/channels/channel_id/api_keys --header 'Authorization: ' --header 'Content-Type: application/json'

Path Parameters

Name

Type

Description

channel_id*

string

ID of the Channel you want to create the API key for

partner_id*

string

Your Hub's Partner ID

{
  "id": "string",
  "address": "string",
  "api_key": "string",   >> API key which was generated
  "app_id": "string"
}

Permission screen will only show after number is running, which means that the API key can be retrieved immediately after the redirect without any additional API calls.

Know the difference between different URLs:

partner_redirect_url is used for Integrated Onboarding only.

can only be set through API
should be a URL, that can be opened in a browser

webhook_url is used to receive any webhook events.

This is an API endpoint, that can receive POST requests.
can only be set through API

onboarding_deeplink is used for Embedded Signup

Is set through the profile section on the partner hub
should be a URL, that can be opened in a browser

Building the integration: video guides

Video 1: Overview and setting Redirect URL

Video 2: Adding the button and styling it

Video 3: Trigger flow and create API key

Video 4: Passing query parameters

URL Parameters

Here you can see details about accepted URL parameters when opening the /permission route on the Integrated Onboarding.

Parameter name

Description

Values

Stored in database?

Returned in redirect?

email

User email to pre-fill the signup form

string

Yes, as part of the client setup

name

User name to pre-fill the signup form

string

Yes, as part of the client setup

number

A specific phone number to request permission for. The number has to match the existing number in the hub. It includes the country code without the leading 00/+.

number

state

Any string value that shall be passed through and returned with the redirect.

string

Yes

redirect_url

Will be used as individual redirect URL instead of the globally set one.

string (encoded)

Will be used as the new redirect URL

partner

Any string value that shall be stored on the client model. Can be retrieved via API as partner_payload.

string

next

Can be used to redirect clients directly to either the login form or the signup form, in case they are not yet logged in.

Demo

Here is the Public Github Repo

Here is the Demo / Connect Button generator

PreviousPartner API integration NextOn-Premise WABA Integration

Last updated 2 years ago

Was this helpful?

hashtagDemo

hashtagPostman Collection

hashtagSignup step by step

hashtagRegistering a new client

hashtagAdding number to existing client

hashtagGetting permission for active number

hashtagGetting permission in the 360dialog Client Hub

hashtagBuilding the integration

hashtag1. Set Redirect URL for your 360dialog Partner Hub

hashtagSet Redirect URL for your Partner Hub

hashtagPath Parameters

hashtagRequest Body

hashtag2. Call the permission screen and consume the redirect

hashtag2.1 Use our React.js Connect Button component

hashtag2.2 Build your own custom flow on any development language you choose

hashtag3. Create API key(s) via Partner API

hashtagCreate API key for a channel

hashtagPath Parameters

hashtagBuilding the integration: video guides

hashtagVideo 1: Overview and setting Redirect URL

hashtagVideo 2: Adding the button and styling it

hashtagVideo 3: Trigger flow and create API key

hashtagVideo 4: Passing query parameters

hashtagURL Parameters

hashtagDemo

Demo

Postman Collection

Signup step by step

Registering a new client

Adding number to existing client

Getting permission for active number

Getting permission in the 360dialog Client Hub

Building the integration

1. Set Redirect URL for your 360dialog Partner Hub

Set Redirect URL for your Partner Hub

Path Parameters

Request Body

2. Call the permission screen and consume the redirect

2.1 Use our React.js Connect Button component

2.2 Build your own custom flow on any development language you choose

3. Create API key(s) via Partner API

Create API key for a channel

Path Parameters

Building the integration: video guides

Video 1: Overview and setting Redirect URL

Video 2: Adding the button and styling it

Video 3: Trigger flow and create API key

Video 4: Passing query parameters

URL Parameters

Demo