Setting a disposition from outside with external_status

The external_status function is the Agent API call that sets the Disposition on a logged-in agent's current call. Instead of the agent clicking a result button, your app sends the status. It is what you wire up when dispositions live in an external workflow tool and you want VICIdial to record the same outcome. New to this interface? Read how to call the Agent API first, and the VICIdial API overview for the wider context.

When you'd use it

Reach for it when the result of a call is decided in your own system: a sale confirmed in a payment tool, a form submitted in a CRM, or a script that auto-dispositions on a rule. It also schedules callbacks, so an external calendar can drop a future callback straight onto the Lead. The status you pass has to be a real disposition code in that VICIdial system, the same ones the agent would see on screen.

How the call works

sequenceDiagram
  participant App
  participant API as agent_api.php
  participant V as VICIdial
  participant Agent as Agent screen
  App->>API: external_status (agent_user, value)
  API->>V: verify agent is logged in
  V->>Agent: set disposition on current call
  V->>V: write status and any callback
  V-->>App: SUCCESS external_status function set

VICIdial confirms the agent is logged in, applies the status to the call currently on their disposition screen, writes any scheduled callback, and returns a plain-text result. The agent's screen reflects the disposition on its next poll.

Parameters

• value — required, any valid status code in the VICIdial system, such as A for a generic disposition or CALLBK for a scheduled callback.
• callback_datetime — required when the status is a scheduled callback, in YYYY-MM-DD+HH:MM:SS format.
• callback_type — USERONLY or ANYONE. Default is ANYONE.
• callback_comments — optional comments shown when the callback comes back, under 200 characters.
• qm_dispo_code — optional call status code used if QueueMetrics is enabled.
• agent_user, user, pass, source — the standard Agent API fields that target the agent and authorize the call.

An example call

A simple disposition is one parameter:

http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=external_status&value=A

A scheduled callback carries the extra fields:

http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=external_status&value=CALLBK&callback_datetime=2012-01-25+12:00:00&callback_type=USERONLY&callback_comments=callback+comments+go+here&qm_dispo_code=1234

Success comes back as SUCCESS: external_status function set - A|6666, echoing the status you set and the API user. As with every Agent API call, the body is plain text, so check the SUCCESS prefix and log the tail.

Gotchas worth knowing

The biggest trap is sending a value that is not a configured status. You get ERROR: external_status not valid - A|6666 and nothing is recorded, so validate your codes against the campaign before you send. If the agent has already logged out or never logged in, you get ERROR: agent_user is not logged in. And remember the callback rule: when the status is flagged as a scheduled callback, callback_datetime is mandatory; skip it and the callback will not land where you expect. The plus sign between the date and time in callback_datetime is literal, not a URL-encoded space. To place a call rather than disposition one, pair this with the external_dial guide.

Every VICIfast server runs the Agent API over HTTPS on its own Branded subdomain, so syncing dispositions from your workflow tool into VICIdial is straightforward from day one. See our pricing to get started.