WhatsApp Integration

Begin a WhatsApp conversation within Colleague with a Candidate or Contact.

Open a WhatsApp panel and communicate directly with the receipient, with all conversations recorded as history against the record.

Receive WhatsApp notifications within Colleague.

Introduction

We are excited to announce our integration with WhatsApp for Business.

Once in place, when on a Candidate or Contact record, a user can mouseover a 'Message' icon and select WhatsApp.

This will open a conversation table and list the known WhatsApp conversations held with the Candidate/Contact by various users:

A user can then select the necessary conversation (or start a new conversation), and a chat window will appear on the right hand side:

All conversations with Candidates/Contacts through this workflow are recorded as histories against the record.

New conversations are initiated with the use of templates. WhatsApp for Business does not allow the first message to be freetext.

Templates are setup within a client's Meta account and accessed within Colleague when starting a new conversation:

Responses will appear as 'WhatsApp Notifications' in the toolbar:

In order to enable this integration, a client will need to setup the necessary account with Meta and link it to their required mobile number(s).

Key Information - Before Getting Started

WhatsApp for Business messages are initiated with the use of templates. WhatsApp does not allow the first message to a recipient to be freetext. Once the recipient has responded, you can then reply with freetext messages.

Your WhatsApp Templates are administered within the WhatsApp for Business account, not within Colleague.

WhatsApp for Business requires a mobile number that does not have any history on the WhatsApp platform (i.e. a newly purchased SIM card or a mobile number that has not been used to send WhatsApp messages previously).

If you wish to use an existing mobile number you have been using with WhatsApp, please use the following link for instructions: https://developers.facebook.com/docs/whatsapp/cloud-api/get-started/migrate-existing-whatsapp-number-to-a-business-account

There are no Colleague costs associated with the WhatsApp integration. WhatsApp will charge your Business Account for the messages sent using this service. Pricing is subject to Meta (estimate ~4p per message).

Under a standard account, a registered mobile number will be able to send 1,000 ‘Business Initiated’ Conversations per 24 hours. Other tiers are available, however these are subject to costs/tariffs as stipulated by WhatsApp.

Meta Account Setup

In order to setup the WhatsApp integration it will require that you setup a Meta Business Account: https://business.facebook.com/overview.

Once you’ve created and logged into the Account, you will now need to ensure you have a Meta Developer account.

Go to: https://developers.facebook.com/docs/development/register/

And click on the below URL:

Select ‘Developer’:

Once the Registration is complete you will then be able to create an App ID:

Press ‘Create App’.

Select Other:

Select Business:

Add App Name (we suggest you name this ‘Colleague’), your App Contact should be a contact at your business:

Within the Dashboard, under the WhatsApp section, select ‘Set up’:

This will open the App Dashboard.

From the left hand menu, under WhatsApp select ‘Configuration’:

Under Webhook fields, click ‘Manage’, then tick to select ‘messages’ and the 'Done':

With the App is created, you need to create a Permanent Token next.

To create a Permanent Token, go back to Business Settings > System Users.

Create a new System User (‘Admin’), if one has not been created already:

Once the System User has been created, assign the ‘Colleague’ app as an ‘Assigned asset’.

Under the Admin system user select ‘Generate new token’:

Select your ‘App’ (Colleague) and set the Token expiration to ‘Never’:

Under ‘Permissions’ ensure you have ticked ‘whatsapp_business_management’ and ‘whatsapp_business_messaging’:

Then press ‘Generate new token’.

Take note of your System Access Token.

Within Business Settings you then need to go to Accounts > Apps, select your 'Colleague' app and press on 'Open in App Dashboard':

This will take you back to your App Dashboard.

From the left hand menu, under WhatsApp select ‘API Setup’:

At this point you will need to add your mobile number.

Under section 5, you will have the option to ‘Add phone number’:

WhatsApp will send a code to verify your mobile number.

Once registered, return to 'Step 1' at the top of the page and select your mobile number from the mobile dropdown.

Take note of your WhatsApp Business Account ID.

With the registration of each mobile number Colleague will need to you to supply the below details:

Mobile Number
WhatsApp Business Account ID
System Access Token
Copy of the example API text generated against the mobile number:

Please send this through to the Support Team (support@colleaguesoftware.com)

Colleague we will then supply the Callback URL and Verify Token.

These details are entered under WhatsApp select ‘Configuration’:

Within the 'Webhook' settings:

Colleague Setup

The Integration settings within Colleague are stored within Global Settings and User Settings:

The settings are set with the IDs, tokens and URLs taken during the Meta registration and mobile number registration process.

The Global Settings will initiate a companywide WhatsApp mobile number, whereas the User Settings will be unique to the User.

If these settings are present it will prompt the SMS icon to become a ‘Message’ sub menu containing both SMS and WhatsApp:

How to get these ID / Tokens is covered lower in this document.

When enabled, the WhatsApp option will appear on the Candidate & Contact record, it will also be present as an option for Candidate & Contact Search results.

Templates

Templates are setup within your Meta WhatsApp account and accessed within Colleague when running the WhatsApp workflow.

Within your Meta Account > Business Settings > click on the ‘All tools’ menu and choose ‘WhatsApp Manager’:

Under ‘Account tools’ > select ‘Message templates’:

Create New Template

Select the 'Marketing' category, name the template and select Language (English UK):

Click 'Continue'.

Click 'Edit Template' and assign a ‘Header Text’ then enter the body message.

If you wish to use merge codes, these are added as variables and referenced in the message body for example {{1}}.

You will be able to determine the Colleague merge code by using the email form and selecting on any of the available merge fields:

For example Known As merge field is ‘KNOWNAS’.

Click Submit for the template to be reviewed by WhatsApp.

Once approved, you will get a response back from the WhatsApp Manager:

Please note: The first approval can take several days (subsequent approvals are seen to be processed quicker).

Example Templates

Header: Job Opportunity

Body: Hi {{1}}, nice to meet you. My name is {{2}} from Colleague Software. We are currently representing a client who is recruiting for a role that may suit your skills and experience. May I share the details with you?