Reading the agent's current lead with st_get_agent_active_lead

When an outside CRM needs to know which record a VICIdial agent is currently working, st_get_agent_active_lead is the call that answers it. It is part of the agent-side API (Agent API), meaning it operates against a live Agent session rather than the back-office database, and it returns the lead that agent has open on screen right now. For the bigger picture of how these endpoints fit together, see the VICIdial API overview.

When you'd use it

Reach for this when your CRM identifies agents by its own ID rather than by their VICIdial login. The function looks up the agent through the vicidial_users.custom_three field, which it treats as the CRM AgentID. So your CRM passes the ID it already knows, and VICIdial maps that back to the right user and the Lead they have in front of them. That makes it the natural glue for a screen-pop or a CRM panel that needs to mirror what the agent is seeing without scraping the agent screen.

How the call works

sequenceDiagram
  participant CRM
  participant API as api.php
  participant V as VICIdial
  CRM->>API: st_get_agent_active_lead (value, vendor_id)
  API->>V: match custom_three to a user
  V->>V: find that user's active lead
  V-->>API: lead_id, phone, fields
  API-->>CRM: SUCCESS line

The endpoint matches your CRM AgentID against custom_three, confirms that user is logged in, then reads the lead on their session and hands back a pipe-delimited line of fields. No lead means no record returned, even if the agent is logged in but idle between calls.

Parameters

• value — REQUIRED, the CRM AgentID (alphanumeric); matched against vicidial_users.custom_three.
• vendor_id — REQUIRED, the CRM TeamID (alphanumeric).

That is the whole input surface. On success the response carries the lead_id, phone number, vendor_lead_code, province, security_phrase, and source_id for the active record.

An example call

http://server/agc/api.php?source=test&user=6666&pass=1234&function=st_get_agent_active_lead&value=876543&vendor_id=207

A good response reads like SUCCESS: st_get_agent_active_lead lead found - 6666|7275551212|123456|9987-1234765|SK|WILLIAMS|JUH764AJJJ9, with the fields ordered lead_id, phone, vendor_lead_code, province, security_phrase, source_id. If the match fails you'll see ERROR: no active lead found - 6666, ERROR: user not logged in - 6666, or ERROR: no user found - 6666 instead.

The gotcha

The lookup hangs entirely on custom_three. If you never populated that field with your CRM AgentID, the function has nothing to match and returns ERROR: st_get_agent_active_lead not valid - 6666|207. Set custom_three on each user as part of provisioning the integration, and remember the agent has to be both logged in and holding a lead for a record to come back. For comparison with the read-only Non-agent API side of things, see reading a lead with lead_all_info.

If you're building a CRM bridge like this, it helps to run it against a dialer you actually control. VICIfast gives you a single-tenant VICIdial box with the agent API exposed and SSL ready out of the box, provisioned in under 40 seconds. See the plans to get a server to test against.