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:
Signup first page with Partner Payment
Integrated Onboarding works with both Partner Payment and Direct Payment. Different payment types have only two differences in the onboarding flow:
- 1.Partner paid clients will see a link to the terms of service on the sign up form.
- 2.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.
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.
When registering a new client, the whole flow should be followed.
From June 26, if you have Cloud hosting enabled in your Partner Hub, Cloud hosting automatically becomes the default choice for all clients onboarded through Integrated Onboarding. If you prefer to onboard a number directly on-premise, you will have the option to include a "
hosting_type" parameter in the client creation request. Please refer to the documentation section about URL parameters.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.
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.
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.
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.
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 Menu → “Settings” → The current permissions will be listed and can be edited.
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.
patch
https://hub.360dialog.io/api/v2
/partners/{partner_id}
Set Redirect URL for your Partner Hub
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.
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.
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:
Install and add the 360dialog Connect Button via npm/yarn and follow the instructions on NPMJS
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.
Process flow of permission call and redirect + API key retrieval
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 |
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.
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
};
Create an API key for each shared channel and store on your system for further use.
post
https://hub.360dialog.io/api/v2
/partners/{partner_id}/channels/{channel_id}/api_keys
Create API key for a channel
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
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 | No |
name | User name to pre-fill the signup form | string | Yes, as part of the client setup | No |
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 | No | No |
state | Any string value that shall be passed through and returned with the redirect. | string | Yes | Yes |
redirect_url | Will be used as individual redirect URL instead of the globally set one. | string (encoded) | No | 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 | No | No |
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. | login / signup | No | No |
hosting_type | Can be used to register phone numbers with on-premise hosting. Allowed value: onpremise | string | No | No |
lang | Can be used to set the default language of the Integrated Onboarding (not including Meta’s ES)
Allowed values:
de, en | string | No | No |
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.