.. _apa-admin: .. only:: html .. note:: :doc:`Vous pouvez consulter une version française de ce guide ici. ` ======================= APA Administrator Guide ======================= For APA 2.8, updated March 1, 2021 .. only:: pdf .. contents:: .. only:: html `PDF Version `_ Introduction ------------ This guide explains how to set up SCOPTEL to enable use of Agent Portal Application (APA) by your installation's endusers. APA is meant to be used in call centers using the Automatic Call Distributor (ACD) feature in SCOPTEL. It speeds up the work of agents by providing telephony actions on their desktop along with their workstation telephone. APA Premium offers the same functionalities as APA, with added CRM integration. Incoming calls trigger the opening of the appropriate customer page in the CRM for immediate use. The APA software is available at http://download.scopserv.com/software/. Requirements ------------ You must have SCOPTEL installed and running with a valid licence and this licence must include permission to us for activating APAs. In SCOPTEL, under *Configuration > Server > License*, you can see whether you have SCOPSERV APA included in your licence and how many units are allowed. This number indicates the number of simultaneous connections allowed. If your agents work remotely, your SCOPTEL installation must also be accessible on a public IP address, and in the case you have a firewall between your server and Internet access, it must not block access to the public port. By default this is port 5555, same as the SCOPTEL GUI port. It is also possible to work through a VPN as long as the APA can directly access your server's IP address. If your agents only need to work in a local environment, then your server's IP address must be accessible on their local network. SCOPDEV Installation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ SCOPDEV is included in the latest version on SCOPTEL. If you want to make sure your system has the latest available version, you can run this command: :: $ scopserv_yum install scopserv-api-events Agent Configurations --------------------------------------- To enable agents to use APA or APA Premium, follow these steps: 1. In SCOPTEL, go to *Configuration > Telephony > Queues and Agents*, and click the *Agents* tab. #. Select the agent to edit. #. For *APA Mode*, select "Basic" or "Premium". #. Click **Save**. Repeat for all the agents you want to enable and When all your changes are made, click **Commit**. Auto-Answer ^^^^^^^^^^^^^^^^^^^^ Typically, call centers will want to set *auto-answer* option in SCOPTEL. To set auto-answer: 1. In SCOPTEL, go to *Configuration > Telephony > Extensions*. #. Select the extension. #. Under **Phone Options**, **SIP Alert**, select the correct **Device** type. This will enable the *auto-answer* feature. #. You may selectively choose which types of calls this applies to, for example Queues (ACD). When all your changes are made, click **Commit**. Pause Codes ^^^^^^^^^^^^^^^^^^^^ APA can be used by agents to switch to 'pause' mode. If you need agents to be able to select pause codes, you must define them in SCOPTEL: 1. In SCOPTEL, go to *Configuration > Telephony > Queues and Agents*. #. Go under the **Tag/Pause Code** tab. #. Click on **Add a new Tag/Pause Code**. #. Select a tenant. #. Write a code and tag. 'Tag' is what will be displayed in APAs. #. Click **Add**. SCOPDEV will be automatically updated and will provision APAs with this info next time they log in. CRM Integration ------------------------ APA supports the following integrations: - Zoho - Zoho Desk - ZenDesk - Salesforce Incomming calls will triggers APA to open a browser window in the CRM. Depending on the CRM, one of the following will occur: - display contact info screen for known contact - display new contact form - display new task or ticket form For example, in Salesforce you would see something like this displayed for an incoming call from an existing contact: .. image:: ../assets/apa/crm_salesforce.* :width: 80% :align: center When the integration is activated, the agent must also already be logged into the CRM to use it, otherwise they will be sent to the login screen. An integration is set on a tenant. You can set one integration for each tenant. Each must have its own key. To activate the integration : IMS is the external service that enables CRM integration. As a reseller, you must first get your IMS reseller account from SCOPSERV. You must specify your location to be linked with the right IMS server for your location. You need to take note of the IMS server URL to use it as described beelow. Salesforce ------------------------ To set up integration with Salesforce, you will need to keep both IMS and Salesforce portal open. Follow these steps: Notes: Your Salesforce account must have REST API Enabled. Check here the Salesforce editions in which the API is available. Salesforce accounts with Person Accounts enabled are not supported. In IMS: 1. Open IMS. #. Go into *Tenants* and click **New Tenant**. #. Type the name of a tenant that matches the one in your SCOPTEL installaton and click **Save Tenant**. #. Go into *Providers*, then click **New Provider Config**. #. Select the tenant created previously. #. Select *Salesforce (V2 API)* in CRM Provider. #. Take note of the generated *API Key* and *OAuth2 Return URL*. In Salesforce: #. Log into your Salesforce developper account. #. Click on *Gear icon > Setup*. #. On the sidebar, under the section PLATFORM TOOLS, select *Apps > App Manager.* #. Click **New Connected App** button on the top right of the webpage. #. Enter an App name, example 'PBX', a contact e-mail and press **Save**. #. Scroll down to API (Enable OAuth Settings) and enable the checkbox *Enable OAuth Settings*. #. In *Callback URL* field, copy the OAuth2 Return URL from IMS. #. Give the following permissions: - Access and manage your data (api) - Access your basic information - Access to your unique identifier (openid) - Full Access - Perform requests on your behalf at any time - Provide access to your data via the Web #. Press **Save**. #. Click *Apps > App manager > Find your app* from the list and click **View**. #. In the API section note the *Customer key* and *Customer secret*. #. Click on **Manage** at the top and **Edit Policies**. #. Go to the OAuth policies section and set Permitted users to *All users may self-authorize*. #. Press **Save**. In IMS: #. In the provider creation page, enter the *Customer Key* and *Customer Secret*. Call Logging ^^^^^^^^^^^^^^^^ If you want to log external calls to Salesforce, you need to define the extension number for every user. This way, the integration can map the extension number of the agent that received the call to the Salesforce user. For this, you need to use the existing *Extension* field. 1. In Salesforce, click on *Gear icon > Setup*. #. On the sidebar under the section ADMINISTRATION, select *Users > Users*. #. Open the users for whom you need to report calls. #. Press **Edit**. #. Populate the *Extensioni* field with the extension number. #. Press **Save**. #. Repeat for each user. Recording Logging ^^^^^^^^^^^^^^^^ Call recordings are saved to SCOPTEL when this feature is turned on. Links to the recordings are saved to the *Description* field of the activity by default. To change this behavior: In Salesforce: 1. Click on *Gear icon > Setup*. #. On the sidebar, under the section PLATFORM TOOLS, select *Object and Fields* then *Object Manager*. #. Open the Activity object, and go to *Fields & Relationships > New*. #. Select the type URL, then click **Next**. #. Choose a field label (we recommend *Recording*). The name will be autogenerated. #. Click **Next**. #. Choose who can view the field, then **Next**. #. Check *Task Layout*, uncheck *Event Layout*. #. Click **Save**. #. Go back to *Fields & Relationships* and find your newly created field, copy the text under "FIELD NAME". In IMS: #. In IMS, copy the field name under *Recording Field ID (Activity Object)*. Contact Matching Strategy ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Salesforce requires that phone number lookup be performed using the last 4 or 7 digits. otherwise Salesforce will not return any data. In SCOPTEL: 1. Go to *Configuration > Telephony > Manager*. #. Select your tenanat to edit. #. Select the *CRM* tab. #. Enter the IMS URL and copy the API Key from IMS. #. Set the contact matching to "Match at least X number of characters" and configure either 4 or 7. #. Click **Save**, then **Commit**. In IMS: #. Set the lookup order and behavior according to your preferences. #. Click **Save Configuration**. #. In the listing, press the **Start** button in the blue box. A new browser tab will be launched, asking you to grant permissions to the Client ID you just created. #. Press **Approve**. The integration is now active. Zoho ------------------------ To set up integration with Zoho, you will need to keep both IMS, SCOPTEL, and Zoho Accounts open. Follow these steps: In IMS: 1. Open IMS. #. Go into *Tenants* and click **New Tenant**. #. Type the name of a tenant that matches the one in your SCOPTEL installaton and click **Save Tenant**. #. Go into *Providers*, then click **New Provider Config**. #. Select the tenant created previously. #. Select *Zoho* in CRM Provider. #. Take note of the generated *API Key* and *OAuth2 Return URL*. In SCOPTEL: #. Go to *Configuration > Telephony > Manager*. #. Select your tenant to edit. #. Select the *CRM* tab. #. Enter the IMS server URL and copy the API Key from IMS. #. Click **Save**, then **Commit**. In Zoho: #. Login into https://accounts.zoho.com/developerconsole. #. Click **ADD CLIENT**. #. When asked to choose a client type, select **Server-based Applications**. #. Enter the *Client Name*, for example: "ScopTEL PBX". #. Enter a *Homepage URL*, for example: "https://www.scopserv.com". #. In the Authorized redirect URIs field, enter the *OAuth2 Return URL*. #. Press the **Create** button and Zoho will generate the *Client ID* and *Client Secret*. Call Logging ^^^^^^^^^^^^ If you want to log external calls to Zoho, you need to define the extension number for every Zoho user. This way, the integration can map the extension number of the agent that received the call to the Zoho user. You can use an existing standard field from the User entity, or you can also create a custom field (as explained below.) In Zoho: 1. Log into your Zoho CRM account with administrative privileges. #. Go to *Setup > Users and Control > Users*. #. Select the user you want to edit from the list of available CRM users and click the **Edit** icon. #. In the *Edit User* form, click the *Manage fields* link #. In the *User form builder* select a *Phone field* from the *New Fields* tray on the left and drag the required field type, and drop it into the desired module section on the right. #. Specify the label of the field. The label will be converted to a field id in which spaces are replaced with "_". For example, the field label "Extension Number" will convert to the field id "Extension_Number" #. Refresh the Edit User page, populate the newly created field with the extension number and click **Save**. #. Repeat for all users. In IMS: #. Type the name of the field id in the *Extension Field ID (User object)* field. Recording Logging ^^^^^^^^^^^^^^^^^ Recordings are saved to the "Description" field of the Call activity, as no fields can be added to Call objects. If you want to save recording links, in IMS type "Description" in the *Recording Field ID (Call object)* field. Last Steps ^^^^^^^^^^^^^^ In IMS: 1. Set the lookup order and creation behavior according to your preferences. #. Click **Save Configuration** and then go back. #. Press the **Start** button in the blue box. A new browser tab will be launched, asking you to grant permissions to the Client ID you just created. #. Press **Approve**. The integration is now active. Kuando Busylight ---------------- Busylight is a device connected to agents' computer that emits light of different color based on the status of the agent. This allows you to view at a glance if an agent is available, and to avoid disrupting a busy agent. To install Kuando Busylight: 1. Download the KuandoHub software from this web page: https://www.plenom.com/downloads/download-software/. Choose the version appropriate to your operating software. #. Install and execute KuandoHub. #. In KuandoHub, go to *Platform Priorities* and make *HTTP* active. #. In KuandoHub, go to *Advanced Settings* and turn *HttpServer* to **On**. #. In APA, the default settings are set so it will connect to KuandoHub. This is toggled in *Settings > Enable Busylight* Busylight runs as a service on localhost:8989.