Lead Routing Mechanism

Content of the article: 

I. Pre-Routing

II. Lead Routing

III. Post Routing

Pre-Routing

Each and every lead routed to a salesperson will have pre-defined parameters which need to be considered.

1. Lead Submission

When a fresh lead (new leads: not rerouted leads, resubmitted lead and assigned lead) is submitted to client lead source or imported fresh leads (new leads: not rerouted leads, resubmitted lead and assigned leads) the lead should be under;

• Active account 
• Active project
• Active lead source
• The phone number field should not be left empty
• Background check for lead re-submissions under same phone number and project
• Valid URL and project mapping under CandyPixel

2. Routing Hours

Only the Leads under auto-routing type on Project settings will be routed during routing hours.

For the leads under the Same Salesperson Preferential Assignment (SSPA) type on Project settings will happen any time (not only during routing hours) when a lead is detected to be owned by the same salesperson in a different project.

3. Same Salesperson Preferential Assignment (SSPA) 

When we receive a new lead, we will check:

• The Project the lead belongs to has SSPA enabled
• If the lead exists in other projects (by same exact phone number)
• If those related leads are already assigned
• If the assigned salesperson exists in this same project

The lead will be assigned to the same salesperson.

• If the same lead is routing in different projects,  e.g. Project A and Project B, if the same salesperson exists in both projects.
• Accepting the lead in one project will result in the same salesperson being assigned the lead in the other project.
  
  

Lead Routing

1. Auto routing

Happens only within routing hours with below list checked: 

• Project must be active
• Project routing enabled
• Lead source routing enabled (which sets a flag on the lead to route or not)
• Lead routing enabled
• The lead has passed the route after date set (by default, the date is immediate i.e. the lead submission date)

The order of the leads to be routed are sorted as follows:

• Highest lead score first
• Oldest lead first

2. Salesteam

We check if the lead should be routed within an assigned sales team. Routing interval sequence is ignored.

• If the lead was assigned to a sales team: 
  The sales team must be active and enabled in the routing pool (it excludes teams in manual routing and teams in disabled backup routing pool). 
•  If the assigned sales team is inactive or not enabled in the routing pool:
  The assignment will be ignored,  and the lead will be routed to other teams in the project, based on routing interval sequence.
•  If the sales team is active:
  The lead will be routed to salespersons within the assigned team only, ignoring the routing interval sequence.

When there is no assigned sales team, or the assigned team was disqualified as above, we select the teams to be routed to, based on routing interval sequence: 

• If the team is in auto-routing
  They will be included at all times during routing hours
• If the team is in backup routing 
  They will be included after the interval set, based on the lead submission date 
• If the lead was received at 2 pm and the backup routing team will be eligible after 2 hours, the team will be eligible after 4 pm.
• If the lead was received at 4 am and the backup routing team will be eligible after 2 hours, the team will be eligible after 6 am

3. Salesperson

Then we will select all eligible salespersons from all the eligible teams:

• Active in the account, project, team, routing chance > 0
• Status is AVAILABLE 
• Not in cool-down 

4. Special handling

For users belonging to multiple eligible teams, e.g. user A belongs to Team 1 and Team 2 under the same Project. In this case, we need to resolve 2 issues:

Issue 1: The user has more than 1 chance receiving the lead

Issue 2: The user has different routing chances according to the team settings

We select the user settings from only one team, by using the following strategy:

• We select the team with the lowest routing attempts for the current session
• In case of a tie, we select the team which has the user with the earliest first available time

For users defined in ignore list for routing (lead specific)

• When the lead was previously assigned to a user and then rerouted, the previously assigned user will be ignored from the routing list.

5. Current routing algorithm 

We then iterate through the eligible salespersons' list by order of :

• Least routing attempts first
• First available time first 

The routing attempts counter is incremented every time we attempt to match the lead to the salesperson (i.e. we roll a random number to assign the lead to the user); whether the roll succeeds (number is lower than routing chance) or fails (number is higher than routing chance), we increase the counter.

The lead will be routed to the first salesperson to match.

6. Special case for only one salesperson available:

We match the lead immediately to any salesperson available if they are the only person available, ignoring the routing chance (except 0% routing chance). 

 7. Sending the lead

Once matched, the lead and user will be checked again before sending in case the state has changed. If the lead or user is invalid, we will abort sending. The routing attempts counter for the user will be decremented to account for the error.

In the case of sending failure, we will return the lead to the routing queue and create a log with FAIL status. The routing attempts counter for the user will be decremented to account for the error.

Post Routing

1. Receiving the response from the user

Once the lead is sent to the user, they will be shown the incoming lead screen on the mobile app to decide:

• If the lead is accepted, the lead will be marked as assigned and removed from the routing queue
• If a cooldown period was set, the user will be put in cooldown
• A log will be created with the ACCEPT event
  
  
• If the lead is declined or timeout (after the timeout period, currently set at 25 seconds (this may change based on future analysis)), the lead will be rerouted immediately.
• A log will be created with the DECLINED(reject) or TIMEOUT depending on the user action
• After 3 times timeout, the user will be automatically marked as AWAY and will not receive further leads
  
  
• If the user is the only one available, the lead will keep being routed to the same user

2. Aborted Leads

A lead may be assigned, deleted or archived by another user while it is being actively routed.  This creates possibilities of conflicts if the lead is already in-flight, i.e. pending the user’s decision to accept or reject the lead. 

We handle these scenarios as follows: 

Scenario 1:  If the lead is assigned to another user while the lead is in-flight
The assignment is deferred until after the in-flight lead’s status is resolved:

• If the lead was accepted by the user, then lead is assigned to the accepting user and the pending assignment is ignored
• If the lead was rejected by the user or timed out, then the pending assignment is processed and the lead is assigned to the intended user.
  
  • A log will be created with the ABORT event with the reason ‘manualAssign’

Scenario 2: If the lead is claimed another user while the lead is in-flight
The assignment is deferred until after the in-flight lead’s status is resolved:

• If the lead was accepted by the user, then lead is assigned to the accepting user and the pending claim is ignored
• If the lead was rejected by the user or timed out, then the pending claim is processed and the lead is assigned to the intended user
  • A log will be created with the ABORT event with the reason ‘claim’

Scenario 3:  If the lead is archived or deleted
The user should not be able to accept the lead in any case.

• An abort message is sent to the application, and the incoming lead screen is automatically cancelled. 
  • A log will be created with the ABORT event with the reason ‘pendingDelete’ or ‘hardDelete’ (in the  case the lead was not in-flight)

Scenario 4: If the abort message was not processed
The user managed to accept the lead before the abort message is processed in time 

• There will be an error result as the lead will no longer exist.
  
  • A log will be created with the CERR event with the reason ‘Invalid lead id’

4. Errors

Being a highly dynamic and high-latency environment, we could not avoid some kinds of errors, such as changes in the lead’s status or salesperson’s status while the lead is in the process of being routed.

The errors are captured and reported in the routing logs with the following types:

• FAIL The lead failed to be sent to the user e.g. the connection was invalid or the application did not respond within a set time
• EXPIRE The lead was successfully sent but a response was not received from the user within a set time
• ERROR A server-side error occurred when the lead was accepted e.g. the lead was already assigned
• CERR An error that was caused by the mobile application e.g. the user tried to accept a lead that was already being rerouted 

5. Known Issues

We are aware of some specific situations where users accept a lead and will encounter an error that is caused by a bug in our mobile application. 

• Duplicated Lead Routing (Server-End Error)
  
  In this situation, the application is supposed to send only one acceptance message to the server but instead sends more than one message simultaneously (or some other mechanism creates message duplication causing the server to receive a duplicate message). As a result, the first message received is considered valid and the lead is assigned to the user. The second message is invalid because the lead is already assigned (due to the first message), then an error occurs. We have observed this type of error happens once every few thousand routing events and are working to handle it correctly.
  
  
• Duplicated Lead Routing (Mobile App Error)
  
  The Server-End error also happens in the reverse direction, where the same lead routing message can be duplicated when sent to the application. In this case, the application may show the incoming lead screen twice. Where the first screen will be visible to the user while the second is not visible. This second screen will be visible after the user has completed handling the lead they just accepted, and when they accept the next lead, they are actually accepting the same lead again, which will result in an error as the lead has already been assigned.
  
  
• Incoming Lead Notification Screen (Mobile App Error)
  
  A third situation where this error occurs is when the application fails to remove the incoming lead notification from the user’s notification tray after it was handled by the user. In this situation, the user was able to access the incoming lead screen which is already stale and tries to accept the lead which could have already been accepted by the same user or have been rerouted to someone else, which will result in an error. 

6. Work In Progress 

In working towards fixing these issues, our first priority is to guarantee that no leads that have been accepted by any user will be accidentally accepted and assigned by another user after the event i.e. User A accepts a lead then the lead gets routed to user B -- this has not happened. Our second priority is to ensure the routing and rerouting process happens as quickly as possible, which comes with the trade-off that some inaccuracies may occur.

7. No Zero Errors

Finally, to put these errors in context, these errors are a relatively small proportion of successfully routed leads (less than 2% of all events) and are mostly caused by factors which are mainly outside of our control e.g. the quality of the user’s internet connection (high latency and instability of mobile connectivity), how the internet works in general (messages are routinely resent by intermediary servers causing duplicate messages), and device-specific inconsistencies such as available memory, Android battery and memory optimisations. Therefore we cannot guarantee zero errors.