Who can use this feature?
System administrator
This installation and setup guide is intended for System Administrators who are responsible for installing the connector and enabling the integration between Qwil Messenger and Salesforce.
What to expect?
Deploying the connector involves five simple steps:
- Download and install the package from the AppExchange.
- Generate a System API Key/Master System API Key from within Qwil Messenger to allow Salesforce to connect to your Qwil Messenger organisation.
- Create a Named Credential record in Salesforce to store the key and secret generated in step 2 for usage by your Salesforce users.
- Specify the Custom Metadata Type values in Salesforce to map the fields between systems and to define how the connector will work for your organisation.
- Edit the client record Page Layout in Salesforce to include the Qwil Messenger Salesforce Connector custom component included with the package.
Note: To use the Qwil Messenger Salesforce Connector your organisation will need to move to a Qwil package that includes APIs. Please get in contact with our sales team to discuss this further if you are unsure.
Before You Start
The Qwil Messenger connector works by linking your Client and Staff records on Qwil Messenger to your Client Object and User Object on Salesforce. Once this link is established, the connector provides trusted access to the functionality using System API Keys rather than the native Qwil permissions of each user. This means that a staff user who has access to the client via Salesforce is able to create, manage, chat and review Qwil information for the client even if some of these features are not directly available for the staff user in Qwil.
Before you start setting up the connector, there are some key field mappings you need to determine to specify as part of the process.
Mapping Staff Users
For staff to use the connector, they require access to both Qwil Messenger and Salesforce. However, unlike the requirement to perform user administration action natively on Qwil, staff users only need to have the basic Staff user role (vs User Administrator or Systems Administrator) to perform the actions via the connector.
As part of the connector setup, you need to specify the unique value on the staff member's Salesforce User record that maps to their Qwil Staff record. On Qwil, you can map to a unique value in either the Primary Email Address field or the Identifier field. This means that you could map a user's Email or Username field value on Salesforce, or even an alternate value such as an Alias that contains a unique ID for the staff user.
Note: Whatever value you decide to use as your unique value to map between the two systems, ensure that this value is NOT EDITABLE by the staff member themselves (i.e. it must be a system admin only who can edit and update this value). This is important as the security is dependant upon you linking an authenticated user on Salesforce to their security profile on Qwil and providing access accordingly.
Mapping Client Users
Client user mapping is more involved. This is because the Salesforce Object your Qwil Client is managed via may differ depending on your particular Salesforce solution (i.e. using Person Accounts on Financial Services Cloud), and the connector enables you to create client profiles on Qwil Messenger from within Salesforce.
[As part of the connector setup, you need to specify the unique value for a Client's record, and mappings for their First Name, Last Name, Invitation Phone Number and Primary Email Address.
Client records can be linked by either the Primary Email Address field or by using the Salesforce Record ID which is mapped to the Qwil Messenger Identifier field. Client records created on Qwil using the connector automatically populate the Record ID of the linked Salesforce record into the Identifier field. However, if you create/bulk upload your client records directly on Qwil or created them prior to deploying the connector, you will need to populate this field retrospectively using our APIs.
The diagram below outlines an example of the Salesforce Contact record mapping between the two systems.
When mapping the field for the Invitation Phone Number, please be aware that Qwil requires this number in the International format without spaces. For example, the UK mobile number "07700 910005" would need to be formatted as "+447700910005" before being sent to Qwil. In some cases, it may be easier to create a calculated field on your Client object in Salesforce that performs this transformation of data stored in your editable mobile phone fields in Salesforce to avoid staff having to manually update this value every time they invite a new client to Qwil.
Note: If you decide to link your client records using an email value on the Salesforce record mapped to the Qwil Primary Email Address, be aware of the potential security implications if users are able to change this field on the records, and therefore changing the details they can view within Qwil Messenger from the Salesforce record.
Step 1. Download and Install the Qwil Messenger AppExchange Package
Once you download our app from the AppExchange, you will be navigated to an installation confirmation page and required to enter your Salesforce credentials for your organisation.
- Follow the steps to accept the terms and conditions and install the package for your specified organisation.
- The installation process can take up to 15 minutes to complete and you will be notified by email once the process has completed.
- Upon completion, login to Salesforce and search "Installed Packages" in the setup Quick Find search bar. Under Installed Packages you should see the Qwil Messenger Salesforce Connector package now available.
2. Generate a System API Key
As a Qwil Messenger System Administrator use the web/desktop application to navigate to the administration menu. Under the API Keys menu section, select System API Keys.
Select + Create a System API Key and enter the following information:
| Field | Input Value/Comments |
|---|---|
| Name | This is a name to describe the use of the connector for your reference. |
| CIDR Blocks |
The CIDR Block value is used to specific a set of designated IP addresses that are allowed to interact with your organisation using this API key. Although optional, we recommend that you specify the CIDR blocks for security reasons. Salesforce provides a list that you can use to determine which values to enter here. Multiple CIDR blocks can be entered as long as they are separated by a comma. |
| This key can export data | Unchecked |
| This key can perform read-only actions | Checked |
| This key can perform write-only actions | Checked |
| This key can perform data reviewer actions | Checked |
Below is an example of the values for a key to use with Salesforce.
Click Create and copy the System API Key and System API Key Secret values presented on the next screen.
Note: You will only be able to access the secret and the key once from this screen. Once you click ok you cannot retrieve the values and you will need to create a new key.
3. Create a Named Credential Record
- Search "Named Credentials" in the Setup Quick Find search bar and open Named Credentials.
- Add a New Named Credential and fill in the following settings and click Save.
| Field | Input Value/Comments |
| Label |
Qwil Messenger Salesforce Connector This must be the exact text to make the connector work properly. |
| Name |
Qwil_Messenger_Salesforce_Connector This must be the exact text to make the connector work properly. |
| URL |
https://<region>.qwil.io The region parameter in the URL path is the name of the region where you Qwil Organisation is hosted. If you are unsure, as a system administrator login to the web app and access the Settings Menu under the Customisation section on the admin menu. Your region is shown on the bottom of the Billing Tab. |
| Identity Type | Named Principal |
| Username | This is the API Key value generated in Step 2. |
| Password | This is the API Secret value generated in Step 2. |
| Generate Authorisation Header | Checked |
| Allow Merge Fields in HTTP Header | Checked |
4. Specify Custom Metadata Type Values
- To configure the package search "Custom Metadata Types" in the setup Quick Find search bar. You will see the Qwil Messenger record.
- Click Manage Records and create a new record by pressing New.
You will now have to fill in the following settings according to your organisation's requirements.
| Field | Input Value/Comments |
| Label |
Qwil |
| Qwil Name |
Qwil |
| Client Email API Field Name |
This is the API name of the field on the associated record for the client in Salesforce where the client email address is to be mapped to in Qwil Messenger. This field is the primary email address value and is a primary key in Qwil for a user. As such, it must be unique to every Client user. |
| Staff ID Field API Name | This is the API name of the field on the user record in Salesforce that captures unique lookup value linking the staff member to their Qwil user record. This can be either their primary email address field, or the identifier field in Qwil. Whichever of the two values is used, both are a unique key in Qwil for a user. As such, it must be unique to every Staff user. |
| Using Super API Key |
Only select this option if you are using a Super API key to interact with Qwil Messenger. If you are unsure, leave this option unchecked. |
| Client Chat History Visible |
Use this option to determine what staff users will see when they look at a client's chat history on Salesforce. "View All" will mean the user can records for chats that they have not participated in. The "View Own Chats" option will only allow the user to see the chats they have participated in with the client. |
| Qwil Region |
This is the name of the region where you Qwil Organisation is hosted. If you are unsure, as a system administrator login to the web app and access the Settings Menu under the Customisation section on the admin menu. Your region is shown on the bottom of the Billing Tab. |
| Client Lookup Type |
Client records can be linked using either the Primary Email Address or the Salesforce Record ID. We recommend you use the Salesforce Record ID as this cannot be edited in the Salesforce User interface by the end user. If you use the email address value please be aware that if a user can edit this value they can change the record it is looking up against in Qwil and potentially bypassing your security controls. |
| Client First Name Field API Name |
This is the API name of the field on the client record in Salesforce that captures First Name value. |
| Client Last Name Field API Name |
This is the API name of the field on the client record in Salesforce that captures Last Name value. |
| Default Client Job Title |
Every user in Qwil is required to have a job title. This can be their role at the company, or in the case of clients we also recommend just using the word "Client" so these users are easily distinguished from staff. If you have a preferred default value you want add when creating clients on Qwil via the connector enter it here. If you leave this blank, staff users will have to input a value for job title manually. Note, even with the default, this can still be changed by the inviting staff user. |
| Client Invitation Phone No.Field Api Name |
This is the API name of the field on the client record in Salesforce that captures Invitation Phone Number. To create a record on Qwil, this needs to be an internationally formatted number preceded by the "+" symbol. For example, +44xxxxxxxxxx. If your base numbers are not in this format, consider creating a formula field on your record that creates the format and which is mapped to the Qwil value. |
| Staff Can Edit Invitation Phone Number |
When inviting a client, or when they are Pending, a secure SMS number is required. If desired, you can force users to edit the core Salesforce record data where the phone is mastered rather than changing the value at the point of invitation. |
| Default Contact Group Name |
Every client user in Qwil must belong to at least one Contact Group that is shared with at least one active staff user. The contact groups that are used to created the user address books each require a name. By default, we recommend using the Last Name of the primary client member followed by a common defining term such as "Relationship". If you want to follow this convention automatically when creating a group as part of the invite user process, simply enter the value to append in this field. If you leave it blank, users will have to enter this value each time they create a group as part of the invitation process. Note, even with the default, this can still be changed by the inviting staff user. |
| Add inviting user into new groups |
This setting applies when inviting a new client, who will need their own individual Contact Group. Often a client will exist in their own contact group as it is not common to desire/allow for communication between clients(obvious exceptions with partners/spouses). And every one of these Contact Groups must contain at least one staff user. When creating a new group in the invite process, this setting will by default select the staff user sending the invite. They will show as a selection to add to the group on the invite screen, and can be removed if this staff member does not wish to have access to the client user. |
Once you have populated all of the value required, Click Save.
5. Edit the client record Page Layout in Salesforce
Once you have completed these set-up steps, you now need to add the component to the Page Layout for the Object in Salesforce that masters your Client records.
To do this follow these steps:
- In Setup, navigate to the object manager and click on the record. In our example, we will be using the Contact object.
- Click on Lightning Record Pages and click on the Record Page where you want to add the functionality. Select the Edit option for this page. You may have multiple to update which means you perform this process for each Page Layout.
- On the Page, add a Custom Tab named "Qwil Messenger" in the appropriate location.
- From the side menu drag and drop the Custom - Managed component name QwilChatTabsMenu into the newly created Qwil Messenger Tab.
Save the page layout and repeat this process for all of the layouts you wish to update.
Once you have performed these actions, navigate to the page layout as a user to confirm the functionality is working correctly.