VICIdial Phone Integration

VICIdial is a base system that third-party vendors (such as Ytel and Freevoice) have built a phone platform around. It is also possible to purchase a VICIdial system and have it set up to meet your needs.

Integration Details

• Click 2 Call
• Incoming call screen pop-up
• Ability to post CRM contacts into dialer campaigns using WebHooks
• Call Dispositions

Integrating VICIdial with Forth

We have built a basic API structure that can be used with most VICIdial Phone Systems. Below are general instructions to allow Click-to-Dial, Contact Screen Pops, and Call Logging. As systems vary you may need to enlist help from the third-party phone system's support staff.

Before you begin the setup, your CRM account will need to have signed up for a phone system integration. If you have not yet and are interested, please contact sales@setforth.com or call (630) 394-6260.

Once you have signed up for the phone system add-on, you will then have access to the VICIdial Settings Page and can begin the setup and configuration process. 

Setting up VICIdial

These setup instructions are split into 3 sections:

1. Configuring VICIdial Settings in your CRM.

A. General Settings
B. User Mapping
C. Disposition Mapping
D. Adding Custom Dispositions (optional)

2. Setting Up a WebHook to Post Leads Into Your Dialer Campaign Lists.

A. Create a new WebHook
B. Input the WebHook URL
C. Add Field Mappings
D. Activate the WebHook

3. Configuring VICIdial Settings in your VICIdial Portal.

A. Screen Pops
B. Call Dispositions / Call Logging
C. Recording URL (optional)

NOTE: For demonstration purposes, this article uses images of Ytel's Contact Center. Your VICIdial portal may appear different but will contain all the same settings and options.

1. Configuring VICIdial Settings in your CRM.

A. General Settings

Location: Admin Tab > Settings > VICIdial

Input the information provided by your phone system provider in the General Settings section. 

• Active / Running: Checking this box will enable the phone system functionality in the CRM.
• URL: This will usually be domain.ytel.com or my.ytel.com. (This will be the same URL that your Users use to log in and operate the phone system.)
• USER: 101
• PASSWORD: To locate your password, log in to your VICIdial Portal and navigate to the Agents tab, then click the Modify button that corresponds to the API User (Agent ID 101).
• SEARCH: Select Yes or No using the Radio buttons on whether you the search capability active.
• Limit Call Logging to Company Token: Checking this box will enable you limit call logging to ...
• PREVIEW: Select Yes or No using the Radio buttons.
• FOCUS: Select Yes or No using the Radio buttons.
• Auto-Pause Campaign on Click to Call: Checking this box will allows agents to automatically pause their status before initiating a click-to-dial operation and apply a pause reason for reporting purposes, enhancing workflow efficiency and reducing manual intervention.

The password will be displayed in the Password field.

B. User Mapping

Location: Admin Tab > Settings > VICIdial

Enter the X5 Admin Agent IDs that correspond to each User in your CRM. 

Phone System Agent ID: These are the Agent IDs listed in the Agents > Agent tab in your VICIdial Portal (shown below)

C. Disposition Mapping

Location: Admin Tab > Settings > VICIdial

Disposition Mapping allows you to update the Workflow Status of CRM contacts, by changing their Disposition inside the Phone System. This works by mapping the Phone System Dispositions to the CRM System Dispositions and then mapping the CRM System Dispositions to a Workflow Status.

| Phone System Disposition --> CRM System Disposition --> Workflow Status |

Start by mapping the CRM System Disposition to the Phone System Disposition. 

System Disposition: Select a CRM System Disposition, then input the name of the corresponding Phone System Disposition (These are the codes in the Status column inside the X5 Admin Portal).. Only the Statuses with the Selectable column set to Y will be active in the phone system.

Adding Custom CRM Dispositions (optional) 

Location: Admin Tab > Settings > Call Settings > Dispositions

From the Custom Disposition page, you can add Custom Dispositions by entering them in the input field or choose to exclude any of the system dispositions by checking the box next to the Disposition you would like to exclude. You may add custom dispositions in your CRM to match custom dispositions from the phone system.

**Note: Before creating custom dispositions it is best practice to exhaust using all the System Dispositions and to be careful not to create unnecessary custom dispositions. Once created, you are not able to delete a custom disposition.

System Disposition to a Workflow Status

Next, map the active CRM System Dispositions to a Workflow Status.

2. Set Up WebHook to Post Leads Into Dialer Campaign Lists.

Location: Contacts tab > WebHooks

A. Create a new WebHook.

Ensure the Title describes what the WebHook is doing or where it is going.

B. Input the WebHook URL and select the Method

The URL should be: http://my.ytel.com/vicidial/non_agent_api.php?
**In many cases, your URL may be different. We recommend to double check with your phone system provider.

The Method should be GET.

**Note: The Port and Authentication fields can be left blank.

C. Add Field Mappings.

Your phone system provider should give you instructions that include a list of required fields that need to be posted into their system. In many cases, they will only provide a very large posting string.

Example Posting String:

http://my.ytel.com/vicidial/api/non_agent.php?vendor_lead_code=--A--VENDOR_LEAD_CODE--B--source=DPP+CRM&user=101&pass=test123&function=add_lead&phone_number=--A--PHONE--B--&campaign_dnc_check=Y&campaign_id=999999&list_id=888888&duplicate_check=DUPLIST&hopper_priority=99&add_to_hopper=Y&first_name=--A--FIRSTNAME--B--&last_name=--A--LASTNAME--B--

After analyzing the above Posting String, we can see the following fields are required:

vendor_lead_code 
source
user
pass
function
phone_number
campaign_dnc_check
campaign_id
list_id
duplicate_check
hopper_priority
add_to_hopper
first_name
last_name

The above list of fields will all be input as the "Field Name".

For static value fields such as user, pass or list_id, select the Value as ---Custom Value---. This will cause a new input box to appear, where you will type the actual value of that Field Name.

For variable value fields such as first_name, phone_number or vendor_lead_code select the field that corresponds to this data in your CRM. For example, you would have mapped those fields to: First Name, Home Phone and ID.

Your finished WebHook should look similar to this:

**Note: In the above image, we used a ---Custom Value--- {ANYPHONE} for the phone_number field. This allows the system to pull from any phone number field (Home Phone, Work Phone, or Cell Phone).

For more information, please review VICIdial's API Documentation.

D. Activate the WebHook

Refer to the "How to Activate a WebHook" section in our Setting Up WebHooks article.

3. Configuring VICIdial Settings in your VICIdial Portal.

Location:  VICIdial Portal

The steps in this section will take place inside your X5 Admin Portal. From the Campaigns > Campaign tab, click the "Modify" icon corresponding to your primary dialer campaign.

A. Screen Pops

Location:  VICIdial Portal > Campaigns > Campaign tab > Modify Campaign page

Input the URL below, into the Web Form field.

VARhttps://login.forthcrm.com/index.php?module=contacts&page=lookup&phone=--A--phone_number--B--

**Note: You may need to change the portion of the example URL "login.forthcrm.com" to the domain which your users log in to. If your users don't log in to the same domain as in the URL, the Screen Pops will NOT function. 
 

Next, scroll down and set Get Call Launch to the option "Web form". This directs the VICIdial system to launch the URL you placed in Web Form on the previous step in a separate window when a call is answered.

B. Call Dispositions / Call Logging

Location: VICIdial Portal > Campaigns > Campaign tab > Modify Campaign page

API Key - You must request an API Key from Forth support (email requesting a Ytel API Key to support@setforth.com). This will be a string needed for the disposition posting to be accepted.

Once you have obtained your API Key, add it to the end of the URL below by replacing the "XXX". Then paste the entire URL into the Dispo Call URL box. 

VARhttps://login.forthcrm.com/post/ytel.php?vendor_lead_code=--A--vendor_lead_code--B--&dispo=--A--dispo--B--&comments=--A--comments--B--&phone=--A--phone--B--&agent=--A--agent_log_id--B--&api_key=XXX
**Additional clarification about Disposition URL fields

• api_key: This field is required and must be included.
• vendor_lead_code: This field is not required, but is strongly recommended. This field should contain the contact's Customer ID. If this field is not present, the phone field must be present.
• phone: This field is required if the vendor_lead_code is missing (see above).
• dispo: Optional field.
• comments: Optional field.
• agent: Optional field.

 C. Recording URL (optional)
 

If your VICIdial system supports call recording posting, you can add a parameter similar to the one below to the end of the Disposition URL. This will add a link to the call recording to the call logs.

&recording_url="https://app.callerready.com/Recording/PlayCallRecording?CallSid=--A--calls_id--B--

Article Version History: