FocalScope WhatsApp integration

FocalScope integrates with WhatsApp using Twilio third-party service.

Note: The registration and activation process for WhatsApp account might take up to 3-4 weeks.

Before going further please ensure that you have following:

• Personal Facebook account
• Business registration document. You will need to upload it in several places.
• Business address. You will need to fill it several times.
• Business logo (640x640 jpeg or png w/o transparency). Please put the file somewhere on your web site. It will be used as a background for the WhatsApp account.

Create Twilio account

Open https://www.twilio.com/, click on [Sign up] button, fill required fields and complete the account creation.

Create Facebook business account

To get a WhatsApp number your have to register a Facebook business account. Please go to https://business.facebook.com click on [Create Account] and Facebook will guide you through the creation process (see the Facebook kb article describing the process).

For the business account use the name that corresponds to the name in your registration documents.

Go to [Business Settings]->[Business Info] (direct url is https://business.facebook.com/settings/info) and copy the [Business Manager ID] from here. You will use it later.

Prepare Twilio account for WhatsApp

Open [Account] menu in Twilio topbar and select [General Settings].

Your project is named like "Your first Twilio project". Please rename it to "WhatsApp Integration" or something meaningful and copy the account SID from here.

Click on [Explore Products] on the left pane and choose [Messaging] here, then go to [Messaging/Senders/WhatsApp] and click on [Sign up to request access] button.

You will be redirected to form where you need to fill a bunch of information.

• For a phone number use your personal or your business number. It is not a WhatsApp phone number.
• Select “No” for "third-party vendor".
• Twilio Account SID is the string you get before.
• Facebook Business Manager ID is the number from the very first step.
• Select "Customer Support" for the "use case".

Eventually you will receive pre-approved notification from Twilio via email. It normally takes about 1 week.

Upgrade the account, buy a number and submit sender profile to Twilio

When you receive the first pre-approved email you will need:

• upgrade the account,
• buy a phone number,
• submit WhatsApp sender profile for this number.

To upgrade the account click on the [Upgrade] in the [Billing] menu on topbar, fill the company and billing address and top-up the account balance.

Next step is buying a phone number: click on [Explore Products] on the left and choose [Phone Numbers] and go to [Phone Numbers/Manage/Buy a number]

Select a number with 'Voice' support, 'SMS' support or both. Depending on the number's country you may need to create address and regulatory bundle with your company registration documents.

Last step here is to submit the WhatsApp sender profile

• Go to [Messaging/Senders/Whatsapp senders], click on the [New WhatsApp Sender] button and create a new profile with the bought number.
• [Business Display Name] value should correspond to your Facebook Business name and to your registration document.
• For the logo please specify url to the prepared file on your website.

Note:  It is not easy to change the business name and the logo url after the registration (It requires Twilio and WhatsApp approval again).

In about 1 to 2 days you will receive email from Twilio with the second pre-approved notification.

Approval for Twilio and Facebook business verification

After receiving second pre-approval email you need to

• approve Twilio on Facebook Business Manager and
• start verification of the Facebook Business Account, it can take 4-5 days.

The email from Twilio contains details of the process. For Twilio approval go to the [Business Settings/Requests] page, select [Received] tab and [Approve] the request. For the Facebook verification you have to upload the business registration document.

Eventually Facebook will verify your account and will send the notification email.

You can see the current state in the [Business Settings/Security Center] page on the [Verification] pane.

In 1-2 weeks after the Facebook business verification have completed Twilio and WhatsApp enable the number and you will receive the last email.

Message template (aka consent message), approval and denial word

You can send a message to a customer only within 24 hours from the last received message from this customer. If you are out of this time frame - you must engage user with pre-approved message and continue with usual free-form messaging only when the user responds back with approval.

Example of this preapproved message:

Sorry for the delayed answer on your question. Please enter GO to get it or FORGETME to deny any further conversation.

For this example the approval word is GO and the denial word is FORGETME.

Please go to [Messaging/Senders/WhatsApp templates], click on [New message template] button, fill the [Template Name] as you wish, choose "Issue Resolution" for [Template category], put in the message text into the [Message body].

Please ensure that the message is the single line and there is no invisible line ending. To check it move the cursor to the very end of the message — cursor should stop immediately after the dot. For example, following is incorrect: cursor stops on new line, not after the dot.

Also, to help a user add two [Quick reply] buttons to the message template - one with the approval and one with the denial word.

In 2-3 hours WhatsApp will review and confirm the consent message. And after that the number is ready to integrate with FocalScope.

Collecting data required by FocalScope

To complete the WhatsApp installation you need to register webhooks and collect following data pieces:

• Account SID: string prefixed with AC like AC80fg49834jfsd9fkdsjfio49jlae9743
• API Key SID: string prefixed with SK like SK4b951b45e5155179229d03217e7ce5a4
• API Key Password: free form string like Q8WYpKvadK2cP8YFCdrLgIK1FlEVpBce
• WhatsApp number: full whatsapp number with country code like +6599998888
• Consent message: it is the message body from the pre-approved message template
• Approval and denial words: they are menitoned in the pre-approved message template and are used for quick reply buttons

Account SID

Switch to [Manager account/General Settings] page and copy the [Account SID] value

API Key SID and Password

Select [Accounts/API Keys & token] in the top menu, click on [Create API key] button on the top, give a name for the key, select "Standard" for [Key type] and click on [Create API Key] button below

Copy somewhere the key [SID] and [Secret] values, tick the [Got it! I have saved my API key SID and secret ...] checkbox and press the [Done] button.

WhatsApp number

Go to [Messaging/Senders/WhatsApp Senders] page and copy the number from here.

Consent message, approval and denial words

See Message template (aka consent message), approval and denial word section.

Webhooks registration

Open [Messaging/Senders/WhatsApp Senders] page, click on correspondent WhatsApp number and put following URLs in the fields:

• [Webhook URL for incoming messages] —  https://<instance>.focalscope.com/_cros_/net/whatsapp.im/twilio/incoming
• [Status callback URL] —  https://<instance>.focalscope.com/_cros_/net/whatsapp.im/twilio/status

Then click on [Update WhatsApp Sender] at bottom of the page.

Registration in FocalScope

After the webhooks registration and collecting the data you are ready to use WhatsApp communication channel from the FocalScope system.

Note: "Fluent mode" is under beta test now. If you instance does not have it please get in touch with FocalScope support team and we will enable the last steps for the integration setup. 

Open the [Settings] page in the "Fluent mode" UI.

Then navigate to [Channels/Whatsapp/Accounts], select [New] in the context menu and fill in the fields with the collected data.

WhatsApp click-to-chat link

You should place the WhatsApp click-to-chat link somewhere on your site. This link redirects a user to WhatsApp app and helps him/her to start a dialog over the WhatsApp channel.

WhatsApp link has such form: https://wa.me/6588889999. For more details about the link format please read in the article in WhatApp FAQ.