How to find the call ID ra_call_control needs

The ra_call_control API lets you hang up or transfer a call that a Remote agent is handling. A remote agent is a person who works a VICIdial campaign from an outside phone line rather than a softphone sitting on your office network, which means you cannot just click a button on a screen they do not have. Every call to that API needs three required fields, and the one that trips people up is the value field, which wants a call ID. This post shows you exactly what that ID looks like, where it is delivered, and how to read it from a live call so your control requests actually match the right call.

What the value field actually wants

The value parameter is the call ID of the call you want to control. It is not the lead ID, not the user ID, and not the phone number, and using any of those is the most common reason a request quietly fails. It is a fixed-format string that looks like Y0315201639000402027. The leading Y is part of it, followed by a timestamp-style block and a counter. VICIdial generates this string when the call is set up and carries it through the call's life, so you have one stable handle to reference no matter how the call moves.

Along with value, the API also requires agent_user, which is the remote agent's VICIdial user, and stage, which is one of HANGUP, EXTENSIONTRANSFER, or INGROUPTRANSFER. If you get the call ID wrong or send it for a call the agent is not actually on, the API answers with an error like ra_call_control not valid and echoes the value, agent, and stage back to you. That echo is your debugging friend: compare the value it received against the string you meant to send and the mismatch is usually obvious.

Where the call ID lives on a live call

The call ID is delivered to the remote agent two ways, and either one is a valid source. First, it arrives as the CallerIDname field on the inbound call. Second, it can ride in a special SIP header. SIP, the Session Initiation Protocol, is the signalling protocol that sets up and tears down VoIP calls, so a custom header is just an extra line of metadata attached to the call setup. If your carrier or trunk passes CallerIDname through to the remote agent's leg without rewriting it, the agent or your CRM can read the value straight off the caller ID display.

• From CallerIDname: read it off the inbound call presentation on the remote agent's line.
• From a SIP header: parse the custom header out of the INVITE if your phone or app exposes raw SIP.
• Keep the leading Y and the full length intact. It is one opaque token, not something you assemble or trim yourself.

One practical gotcha: some carriers strip or overwrite the CallerIDname on the way to an external line, which is the same field a normal call uses to show a CID (caller ID) to the agent. If you never see the Y-string arrive, check whether the trunk is preserving that field before you blame the API. When CallerIDname is unavailable, the special SIP header is the fallback source for the same call ID.

How the ID flows to your control call

sequenceDiagram
  participant V as VICIdial
  participant A as Remote agent line
  participant C as Your CRM
  participant API as ra_call_control
  V->>A: Inbound call with CallerIDname Y0315
  A->>C: Agent reads the call ID
  C->>API: value equals Y0315 plus agent_user plus stage
  API->>V: Hangup or transfer the matched call

Once you have the string, you pass it as value alongside agent_user and stage. For an in-group transfer you add ingroup_choices, and the reserved word DEFAULTINGROUP sends the call to whatever in-group or campaign originated it. For an extension transfer you add phone_number, a full number that dials through the default context. Get the call ID right and the rest of the call is matched for you automatically.

If you are new to all of this, start with our pillar guide on how VICIdial remote agents work, then read the three stages ra_call_control supports to see what HANGUP, EXTENSIONTRANSFER, and INGROUPTRANSFER each do. If you would rather not manage Asterisk and API plumbing yourself, our managed VICIdial plans hand you a working dialer in under a minute.