Enabling Vicidial

Please contact your Account Manager before enabling this feature

Vicidial can be enabled in settings under 3rd Party Tools > Vicidial Dialler Settings or Additional Settings, then select Vicidial Dialler at the top

Please enter the full Vicidial endpoint url supplied by your provider, the Admin User and Admin Password. These 3 values must be present to enable the Vicidial connection. Select using the check boxes the modules that you would like connection fields to appear.

You can also enter a default country code eg 44 for Great Britain. This must be a number with no special characters.

Setup Lists for Vicidial

By clicking on Vicidial List Link you can enter Vicidial list details.  In the field on the left enter a friendly name for your list, adjacent to the right enter the Vicidial List ID - it is important to enter this correctly to add your Lead to the correct List in Vicidial.  Assigned To User is a default value which will use the id of the assigned user to the record in OpenCRM  - this will only work if you have used these user values in Vicidial as your list values.  Keep this adjacent value as 0.

When you have created these pick list values they will be selectible on editing your Lead, Contact or Company records.

Sending Contacts to Vicidial

Now you have entered the Vicidial settings and enabled this to display in the Contact module you should see a new block called Vicidial Connection.

• Vicidial Country Code - this is the default value set in the settings described above. It can be edited and should be a number with no other characters or letters to be accepted by Vicidial
• Phone No to Send - here you can select which phone number field to pull from the record.  You can use the pencil  to modify this picklist.  Use the field label as you value.  This picklist in relevant to just this module
• Vicidial List - here you can select the Vicidial List to send your Lead to. These list values can be setup using the description above
• Vicidial Rank - if you would like to apply a rank to the lead in Vicidial select the rank here
• Send to Vicidial Now - select this checkbox to send the lead to Vicidial on the next save or apply of the record
• Remove from Vicidial - this checkbox when checked will remove the Lead from the Vicidial queue when the record is saved

In order to send a Lead, Contact or Company record to Vicidial you must define these values

1. Enter a last name (ideally a first name as well) or a company name if you are in a company record
2. Enter a telephone number and select the relevant option in Phone No to Send
3. Check the Vicidial Country Code is entered and is just a number
4. Check Sent to Vicidial Now
5. Click Save or Apply on the record this will send the value to Vicidial, this may take a few seconds while the data is sent to Vicidial

After saving the record you can check if it sent and the details returned by selecting the detail tab and scrolling down to the Vicidial Connection block.

This page as well as displaying the details you have entered will show the values returned from Vicidial.  If an agent updates the record on Vicidial this should also update this record.

• Sent to Vicidial on - this the date and time the record was initially sent to Vicidial
• Vicidial Status - this in the status of the Lead in Vicidial at the time of opening the record.  This will either be the value returned on initially exporting to record to Vicidial or the last update received from Vicidial
• Vicidial Lead ID - this the lead id returned by Vicidial

If the status says "In Queue" then you have successfully sent the record to Vicidial.  If there is an error try to correct the error and resend.  If the status is "Failed to Send" they you Vicidial server is unavailable and we will attempt to resend.   Please check your Vicidial manual for other statuses.

DNC - Do Not Phone

If the field Do Not Phone is checked or the "yes". The the record will not be sent to Vicidial.  If you select this option after a record has been successfully added to the queue then the Send to Vicidial Now checkbox should automatically be selected and on saving the record a new status of DNC should be sent to Vicidial.

Updating OpenCRM records from Vicidial

Your provider should be able to connect Vicidial to our system using our REST API endpoint specially created for Vicidial.

This enables your agents to updated OpenCRM record fields from the agent interface.

Start by asking OpenCRM for an API key to connect your system to Vicidial.  Your provider should connect to our api using a url like this, replacing "yoursystem" with your system url.

https://yoursystem.opencrm.co.uk/api_rest.php?request=plain&vicidialUpdate&username=2b6a7c6148575d83e43f9ab6aef3343f&password=dsadsdssdsadadsdssadAOcPOr 

Using the Vicidial endpoints, you are able to pass in any field from the record to be updated, for example, if you have the custom field "Extra Charges" on all of the Leads, Contacts and Company modules, using the API, you can add this to any updates.

This means that any field which you can access is now editable on any of these modules by passing the field name (list below) and a value into the call you are making.

URL Structure Guide

https://systemname.opencrm.co.uk/api_rest.php?request=plain/vicidialUpdate&module=Contacts&username=insertusername&password=insertpassword&lead_id=vicidialid&vendor_lead_code=OpenCRMid&status=1

Looking at the above sample, the URL is broken down into various parts. Some of these are mandatory and have to be filled in, these are:

• systemname - this is the name of your OpenCRM system. This can be found when looking at the URL of your system when logged in
• module - This is the module in OpenCRM which holds the record you would want to update. This can be: Leads, Contacts or Accounts (Company)
• username & password - this will be the details of the API Key generated when setting up the connection. (see above FAQ)
• The following values should be appended as name=value pairs (these 3 are compulsory to find the correct record)
  • lead_id - This is the Vicidial Lead/Contact/Company id (normally matches vendor_lead_code)
  • vendor_lead_code - this is the OpenCRM Lead/Contact/Company id (normally matches lead_id)
  • status - current status of the lead with Vicidial (should default to 1 for Company and Contacts)

You then append the fields (full list below), for each respective module, that you want to update by adding &fieldname=value. So, if you wanted to update the persons last name in contacts you would add "&lastname=Bloggs" to the end ending up with the below result:

https://systemname.opencrm.co.uk/api_rest.php?request=plain/vicidialUpdate&module=Contacts&username=insertusername&password=insertpassword&lead_id=vicidialid&vendor_lead_code=OpenCRMid&status=1&lastname=Bloggs

Examples

Example 1 - Creating a new record:

https://systemname.opencrm.co.uk/api_rest.php?request=plain/vicidialUpdate&module=Contacts&username=insertusername&password=insertpassword&lead_id=1234&vendor_lead_code=0&status=1&firstname=Joe&lastname=Bloggs

In this example we are creating a new Contact called Joe Bloggs
By leaving the "vendor_lead_code" field with a value of 0, this then tells the system to create a new record which will then sync back the newly created CRM ID to Vicidial.
The process as to how this works is show below:

1. A new contact record is sent from Vicidial - vendor_lead_code=0, lead_Id=1234
2. OpenCRM creates a contact - CRMID=4567, vicidial_id=1234
3. That new contact is sent from OpenCRM to Vicidial - vendor_lead_code=4567, lead_id=1234
4. Vicidial updates it's record to set vendor_lead_code to 4567
5. Next time it sends that contact, it will send vendor_lead_code=4567, lead_id=1234
6. We find and update the contact with matching ID's

Example 2 - Updating an existing record:

https://systemname.opencrm.co.uk/api_rest.php?request=plain/vicidialUpdate&module=Leads&username=insertusername&password=insertpassword&lead_id=1234&vendor_lead_code=4567&status=1&firstname=Joe&lastname=Bloggs&postal_code=LN123GH

In this example we are updating the existing Lead with the  First and Last Name as well as updating the record with a postal code as well.
This URL has the matching IDs in  "lead_id" and "vendor_lead_code" that enables us to update this record.

Example 3 - Linking to an existing record:

https://systemname.opencrm.co.uk/api_rest.php?request=plain/vicidialUpdate&module=Contacts&username=insertusername&password=insertpassword&lead_id=1234&vendor_lead_code=4567&status=1&firstname=Joe&lastname=Bloggs&account_id=58937

In this example we are updating the Contact called Joe Bloggs and then linking him to an existing company by associating him with a company using the command "&account_id=58937" (the ID is from the existing company). 
 

Standard Fields that can be used:

These lists contain the most used fields but does not include all.

Leads:

• salutationtype = Salutation
• firstname = First Name
• phone = Phone
• lastname = Last Name
• mobile = Mobile
• company = Company
• fax = Fax
• designation = Designation
• email = Email
• leadsource = Lead Source
• industry = Industry
• leadstatus = Lead Status
• annualrevenue = Annual Revenue
• rating = Rating
• noofemployees = No Of Employees
• lane = Street
• code = Postal Code
• city = City
• country = Country
• state = State
• phone_ext = Extension
• homephone = Home Phone
• dob = Date Of Birth
• middlename = Middle Name
• lane2 = Street 2
• assistant_email = Assistant Email
• comments = this comment will be recorded as an activity linked to the Lead, Contact, Company record that was sent

Contacts:

• salutationtype = Salutation
• firstname = First Name
• phone = Office Phone
• lastname = Last Name
• mobile = Mobile
• account_id = Company Name
• title = Title
• fax = Fax
• department = Department
• email = Email
• contact_id = Reports To
• mailingstreet = Mailing Street
• otherstreet = Other Street
• mailingcity = Mailing City
• othercity = Other City
• mailingstate = Mailing State
• otherstate = Other State
• mailingzip = Mailing Zip
• otherzip = Other Zip
• mailingcountry = Mailing Country
• othercountry = Other Country
• emailoptout = Email Opt Out
• phone_ext = Extension
• middlneame = Middle Name
• greeting = Greeting
• email2 = Email2
• contacttype = Contact Type
• contact_folder = Folder
• sage_ref = Sage Reference
• assistant_email = Assistant Email
• comments = this comment will be recorded as an activity linked to the Lead, Contact, Company record that was sent

Company:

• accountname = Account Name
• phone = Phone
• website = Website
• fax = Fax
• otherphone = Other Phone
• account_id = Member Of
• email1 = Email
• employees = Employees
• email2 = Other Email
• ownership = Ownership
• rating = Rating
• industry = industry
• siccode = SIC Code
• accounttype = Type
• annual_revenue = Annual Revenue
• bill_street = Billing Address
• ship_street = Shipping Address
• bill_city = Billing City
• ship_city = Shipping City
• bill_state = Billing State
• ship_state = Shipping State
• bill_code = Billing Code
• ship_code = Shipping Code
• bill_country = Billing Country
• ship_country = Shipping Country
• vatnumber = VAT Number
• credit_limit = Credit Limit
• credit_limit_days = Time To Pay
• overdue_balance = Overdue Balance
• outstanding_balance = Outstanding Balance
• currentspend = Current Spend
• variance = Spend Variance
• vatexempt = VAT Exempt
• sage_install = Sage Install
• sage_balance = Sage Balance
• account_crm_id = Company Id
• due_balance = Due Balance
• pricebook = Pricebook
• credit_status = Credit Status
• paymenttype = Payment Type
• creditcheckon = Credit Check On
• creditcheckby = Credit Check By
• def_currency = Default Currency
• sage_ref = Sage Reference
• shipemail = Shipping Email
• billemail = Billing Email
• companynumber = Company Number
• bill_street_2 = Billing Address 2
• ship_street_2 = Shipping Address 2
• xero_ref = Xero Reference

Custom Fields and how to use them:

If you have created your own custom field then you will be able to add them to the API call as well. To do this you will need to find the field name for that custom field. The best place to see this is to go to Settings > Studio > Custom Field Settings: 

Then select the module that you would like to find the field name from, in this case we selected Company:

This then lists all the new custom fields that you have created for that module. You would then find the field and take note of the 'Database Name'. So, let us say we wanted to add the field 'Total North Employees" to the API call and tell it to be 50%, we would then need to add '&cf_433=50' to the end of the URL as shown below:

https://systemname.opencrm.co.uk/api_rest.php?request=plain/vicidialUpdate&module=Accounts&username=insertusername&password=insertpassword&lead_id=1234&vendor_lead_code=4567&status=1&account_id=58937&cf_433=50

Remember, custom fields use the Database Name and not the Field Label itself.