RingCentral Reference Implementation

All our customers will have access to our pre-coded implementation for RingCentral with Applets. With this implementation, you will be able to dial calls, send SMS, and store all interactions you made through RingCentral Implementation into a FreeAgent's Applet. While it is open to all our customers, only team administrators have access to create Applets and since these are code-based, support from a development team is recommended.

Once you finish with this Tutorial, you should have something like the following in your FreeAgent CRM account:

In this tutorial we will cover the following topics:

1. Requirements
2. Setting Up Your Account
   1. Phone Call Applet
      1. Phone Call Fields
      2. Phone Call App Actions
   2. SMS Applet
      1. SMS Fields
      2. SMS App Actions
3. Applet SDK
   1. Config File

1. Requirements

• JS Basic Knowledge.
• Access to our repository: RingCentral
• A RingCentral App Client ID: RingCentral Development
• A way to publish a web page such as GitLab Pages.

2. Setting Up Your Account

Before getting started, you will need to set up your account to get your Applet ready. We are going to need to create two Applets and setup an App action for each of them. Let's start creating and setting up your Phone Calls Applet.

2.1 Phone Call Applet

First, login into your FreeAgent Account and navigate to Admin Settings > Applet Setup > Applets

Once there, click on the “Add New Applet” button located in the top right corner. Add the following names:

• Name: Phone Calls*
• Singular Name: Phone Call*

* If you want to use a different name, we will explain what to do in the section “Applet SDK”.

Save your Applet and then navigate to Admin Settings > Applet Setup > Phone Calls > App Configuration

Here is where you will set up how your applet will look like. The following settings are recommended:

• Width: 300
• Hight: 500
• URL: The URL where your RingCentral Widget will be hosted.
• Params: The parameters that FreeAgent will send to your applet every time you open it. For this implementation you will need to send the following object:

{

 "clientId" : "RingCentral ClientId",

 "clientSecret" : "RingCentral Client Secret",

 "redirectUri" : "https://ringcentral.github.io/ringcentral-embeddable/redirect.html"

}

* You can get your clientId and clientSecret from RingCentral Developers.

Save your changes. Once you do, if you fill the "URL" field, you will notice, at the bottom of the page, your Applet ID. Copy and paste the ID to a secure place, you will need it later.

2.1.1 Phone Call Fields

Now you have set-up your Applet, let’s create some fields that will help you to maintain the sync between RingCentral and FreeAgent. 

First, navigate to Admin Settings > Manage Choice List

In the top right corner click on the “Create New Choice List” button. You will need to create 6 'empty' Choice lists with the names listed below, make sure you check the "Ad-hoc creation" box on all of them:

• Call Outcome
• SMS Read Status
• SMS Message Status
• SMS Type
• RingCentral Direction
• Status

Once you created the above choice lists, navigate to Admin Settings > Applet Setup > Phone Calls > Form Fields to create the corresponding Choice List fields and some other necessary fields.

Create the fields shown in the table below following that same order.

Note: Following the creation order for the fields is required to maintain the sequence of the "System Name" which is auto-generated by the platform.

If the sequence does not match, we will explain how to handle that in the section “Applet SDK”.

With these fields, we have finished the setup of the Phone Calls Applet.

2.1.2 App Actions

Now let's create an App Action that allows you to make calls from any of your contacts, once you click on it, the Applet will automatically dial the call.  To do so, navigate to Admin Settings > App Setup > Contacts > App Actions

There, click on the "Add New App Action" button, located In the top right corner.

Give your App Action a Name, select the Icon you wish, and select "Custom Code" as type. That will enable the code editor, there paste the following code:

(function(contact, context){

 context.clientAPI.sendEvent(`makeCall`, {

     record: contact,

   });

   return 0;

}(contact, context));

The above function will send an event named “makeCall” to your Applet. To learn more about this function, please visit the following tutorial:
Applets

2.2 SMS Applet

Now let’s set up your Messaging App, which will be an Applet as well. To do so, navigate to Admin Settings > Applet Setup > Applets

There, create a new applet with the following names:

• Name: SMS
• Singular Name: SMS

Now navigate to Admin Settings > Applet Setup > SMS > App Configuration

This time we are going to "copy" the configuration from our previous Applet, so, in the option named "Applet Configuration" select the Phone Calls Applet. 

Thanks to this, the configuration for the SMS Applet will be exactly the same as the Phone Calls Applet.

2.2.1 SMS Fields

Now, we have to create the fields for this Applet. To do so, navigate to Admin Settings > Applet Setup > SMS > Form fields

Create the fields shown in the table below following that same order.

Note: Following the creation order for the fields is required to maintain the sequence of the "System Name" which is auto-generated by the platform.

If the sequence does not match, we will explain how to handle that in the section “Applet SDK”.

2.2.2 SMS App Action

Now that your SMS Applet is all set-up, let’s create a new App Action for your contacts that will open the Applet and allow you to send a message from any of your contacts. To do so, navigate to Admin Panel > App Setup > Contacts > App Actions

Give your App Action a Name, select the Icon you wish, and select "Custom Code" as type. That will enable the code editor, there paste the following code:

(function(contact, context){

 context.clientAPI.sendEvent('sendSMS', {

   record: contact,

 });

 return 0;

}(contact, context));

The above function will send an event named “makeCall” to your Applet. To learn more about this function, please visit the following tutorial:

Applets

3. Applet SDK

Everything is set up and ready for you to start using your applet. The next step is fork or download our RingCentral implementation from the following repository: RingCentral

3.1 Config File

Now you have the code in your hands, open the file “config.js” this is the only file you need to edit in order to start dialing calls and sending messages thru your Applet.

const SERVICE = {

   name: 'FreeAgentService',

   appletId: `your_Applet_ID`,

 };

Here is where you add the AppletID that you stored at the beginning of the tutorial.

Now let's take a look at the configuration of the fields.

PHONE_APPLET_CONFIGURATION.fields = {

   from: `${PHONE_APPLET_CONFIGURATION.name}_field1`, // Phone

   to: `${PHONE_APPLET_CONFIGURATION.name}_field2`, // Phone

   contact: `${PHONE_APPLET_CONFIGURATION.name}_field4`, // Reference to Contacts

   duration: `${PHONE_APPLET_CONFIGURATION.name}_field5`, // Number with mask `00:00:00`

   direction: `${PHONE_APPLET_CONFIGURATION.name}_field5`, // Choice List Adhoc,

   status: `${PHONE_APPLET_CONFIGURATION.name}_field6`, // Status

   note: `${PHONE_APPLET_CONFIGURATION.name}_field7`, // Note

   ringcentralId: `${PHONE_APPLET_CONFIGURATION.name}_field8`, // Text (unique)

Here you will notice that all the fields we created earlier are listed here and at the end of each {} there is a "_field#" That number should correspond to the System Name of each of your fields, therefore, it is really important that you make sure that you verify all your Field's system names. 

SMS_APPLET_CONFIGURATION.fields = {

   from: `${SMS_APPLET_CONFIGURATION.name}_field0`, // Phone

   to: `${SMS_APPLET_CONFIGURATION.name}_field1`, // Phone

   contact: `${SMS_APPLET_CONFIGURATION.name}_field2`, // Reference to Contacts

   subject: `${SMS_APPLET_CONFIGURATION.name}_field3`, // Note

   type: `${SMS_APPLET_CONFIGURATION.name}_field4`, // Choice List (Adhoc)

   messageStatus: `${SMS_APPLET_CONFIGURATION.name}_field5`, // Choice List (Adhoc)

   readStatus: `${SMS_APPLET_CONFIGURATION.name}_field6`, // Choice List (Adhoc)

   direction: `${SMS_APPLET_CONFIGURATION.name}_field7`, // Choice List (Adhoc)

   ringcentralId: `${SMS_APPLET_CONFIGURATION.name}_field8`, // Text (unique)

 }

Here you will need to do pretty much the same as with PHONE_APPLET_CONFIGURATION. If you notice the fields are not matching with your SMS App, then make the required changes for them to match the System Name.

Once you made the above changes, upload your code to your host (The one you used when you set up your Applet Configuration for your Phone Calls Applet.) 

We recommend that you use GitLab pages, but the important thing is to have your code in a public space form where FreeAgent can download the code.

Navigate to FreeAgent and once you open the Applet you should see something similar to the image below:

Every call and SMS you receive will popup in your Applet window. You will be able, as well, to make calls and send messages. 

Every call (inbound and outbound) and every message (sent and received) will be registered in the corresponding Applet (Phone Calls or SMS).

Of course, thanks to the App Actions you created for your contacts, you will be able to navigate to any contact and make a call or send a message right from the contact with a single click on the App Actions buttons.

We hope that this tutorial helps you get a better understanding of how Applets work and what you can accomplish with them. If you want to learn more about Applets, please visit the following tutorial: Applets