# VICIdial Integration

> Connect Menace Voice to VICIdial through Asterisk ARI for call control, in-group transfers, and lead updates

## Overview

Use this integration when VICIdial owns the customer call and connects Menace Voice
to it through Asterisk. Menace Voice uses Asterisk ARI for audio and VICIdial APIs for
operations that must affect the original customer leg:

- Hang up the customer call when the agent ends the conversation
- Transfer the customer to a VICIdial in-group
- Update selected VICIdial lead fields from gathered workflow context

VICIdial credentials and lead-field controls are an advanced organization
feature. Context Mapping in Transfer Call tools is generally available and can
also route calls for telephony providers that are not connected to VICIdial.

## Prerequisites

Before configuring VICIdial, ensure that:

- Asterisk ARI is connected to Menace Voice as described in the
  [Asterisk ARI integration](./asterisk-ari)
- VICIdial sends the customer call to the Asterisk dialplan that enters the
  Menace Voice Stasis application
- You have VICIdial agent API credentials with permission to hang up and
  perform in-group transfers
- If workflows will update leads, you also have non-agent API credentials with
  permission to call `update_lead`

## Enable the organization feature

1. Open **Platform Settings** by going to https://voice.menaceui.com/settings
2. Enable **External PBX integrations**.

This switch reveals VICIdial credentials in Asterisk telephony configurations
and lead capture/update settings in workflow configurations. Disabling it hides
those VICIdial-specific controls without deleting their saved values; Context
Mapping remains available in Transfer Call tools.

## Configure VICIdial credentials

1. Open **Telephony Configurations**.
2. Create or edit an **Asterisk ARI** configuration.
3. In **External PBX**, set **External PBX Type** to **VICIdial**.
4. Configure the agent API:
   - **Agent API URL**: normally ends in `/agc/api.php`
   - **Agent API User**
   - **Agent API Password**
5. To update leads, configure the non-agent API:
   - **Non-Agent API URL**: normally ends in `/vicidial/non_agent_api.php`
   - **Non-Agent API User**
   - **Non-Agent API Password**
6. Save the configuration.

The non-agent API is optional when no lead updates are required. If it is used,
its URL, user, and password must all be present. Credentials are stored with the
telephony configuration and are returned masked by the Menace Voice API.

## Pass VICIdial call identity to Asterisk

Menace Voice needs VICIdial's call identity to control the original customer leg.
Configure VICIdial or the connecting dialplan to preserve these SIP headers on
the call that enters the Menace Voice Stasis application:

| Header | Purpose |
| --- | --- |
| `X-VICIDIAL-callerid` | Call-control identifier used by the agent API |
| `X-VICIDIAL-user` | Remote-agent user used by the agent API |
| `X-VICIDIAL-lead_id` | Lead identifier used by optional lead updates |
| `X-VICIDIAL-campaign_id` | **(Optional)** Campaign context retained with the call |
| `X-VICIDIAL-ingroup_id` | **(Optional)** Original in-group available to transfer fallback routing |

Hangup and transfer require the call-control identifier and remote-agent user.
Lead updates additionally require the lead ID. The source in-group header is
only required when a transfer mapping uses the `source` fallback.

### Pass lead data in additional headers

Configure VICIdial or the dialplan to attach lead fields as headers, for example
`X-VICIDIAL-first_name`, `X-VICIDIAL-city`, or `X-VICIDIAL-vendor_lead_code`.
Headers with empty values are ignored.

Each lead field is then read individually during call setup, so Menace Voice captures
only the fields you list:

1. Open the workflow's **General Settings**.
2. Under **External PBX Field Updates**, find **Lead Fields To Capture**.
3. Add one entry per field, named **without** the `X-VICIDIAL-` prefix — enter
   `first_name` to capture `X-VICIDIAL-first_name`.

<Note>
  Every field you add costs one extra request to Asterisk while the call is being
  set up, which delays the agent's first response. List only the fields your
  prompts actually use.
</Note>

#### Discover which fields your PBX sends

Each inbound call logs the available field names automatically:

```text
[ARI org=7] Available vicidial lead fields on channel 1712...: ['callerid',
'city', 'first_name', 'lead_id', 'user'] — add the ones you need under the
workflow's Lead Fields To Capture setting
```

Listing the names costs a single request no matter how many headers are present,
because it reads names only — never values.

Captured fields are available to workflow prompts through template variables
named after the header suffix:

```text
Hello {{external_pbx_call.lead.first_name | there}}, I see you're calling
from {{external_pbx_call.lead.city}}.
```

## Configure in-group transfers

In-group mappings select a VICIdial destination from information gathered by
the agent during a call.

1. Open or create a **Transfer Call** tool.
2. Select **Context Mapping** as the destination source.
3. In **Rule 1**, enter a context path, such as `qualified`,
   `gathered_context.qualified`, or `initial_context.qualified`. An unprefixed
   path checks gathered context first and then initial context.
4. Add one route for each expected value and its destination in-group ID.
5. Optionally select **Add routing rule** to check another context path when the
   rule above it does not match, and use the arrows to order the rules.
6. Optionally configure a fallback in-group. Enter `source` to return the
   caller to the original in-group captured from the SIP headers.
7. Save the tool and attach it to the workflow.

Rules are evaluated top to bottom. The first rule whose context value matches
one of its routes wins, so put the most specific routing first; the fallback
applies only after every rule misses. The match is case-insensitive. Menace Voice
performs final variable extraction before resolving the mapping. If no rule or
fallback matches, the transfer fails and the agent can recover instead of
silently hanging up the caller.

## Configure lead field mappings

Lead field mappings copy selected values from gathered context into the
VICIdial lead before transfer or hangup.

1. Open the workflow's **Configurations** dialog.
2. In **External PBX Field Updates**, add a mapping.
3. Enter the gathered-context path and the destination VICIdial lead field.
4. Add any additional mappings and save the workflow configuration.

For example, map `extracted_variables.customer_state` to `state`. A context
path can address a direct gathered-context value or a nested value. Mappings
whose source value is absent are skipped.

The VICIdial adapter ignores mappings that target the API control parameters
`source`, `user`, `pass`, `function`, and `lead_id`. The non-agent API
configuration is required for mappings to be applied. A lead-update failure
does not prevent Menace Voice from attempting the requested transfer or hangup.

## Configure disposition mapping

Menace Voice can record a completed call's outcome on the VICIdial lead's `status`
column, so a call Menace Voice handled appears in the same reports as one an agent
handled. First,
[configure the business outcomes for each workflow](../../developer/call-dispositions#configure-outcomes-for-a-workflow).
You can then map those raw outcomes to the status codes used by your VICIdial
deployment:

1. Open **Platform Settings** and enable **Disposition mapping** under
   Preferences.
2. Select **Configure mapping**.
3. Choose the VICIdial status code you want recorded for each Menace Voice
   disposition. A disposition left as itself is sent unchanged.
4. Select **Add disposition** for any custom workflow outcome or end-call tool
   reason that is not already listed, then save your preferences.

Use the status codes already configured in your VICIdial deployment. Menace Voice
does not prescribe the mapping, and VICIdial exposes no API for discovering
those codes automatically. Consult your own VICIdial status configuration or
report when choosing each target value.

The mapped code is written to `gathered_context.mapped_call_disposition`, which
is what VICIdial write-back, the disposition run filter, and reports read. To
send it in a webhook, reference that field explicitly. The automatically added
top-level webhook field contains the raw `gathered_context.call_disposition`.
See [Call Dispositions](../../developer/call-dispositions#understand-the-stored-fields)
for the complete data model.

<Note>
  Map your do-not-call outcomes to `DNC` to have Menace Voice add the customer's
  number to VICIdial's `SYSTEM_INTERNAL` do-not-call list. A lead status stops
  the current list being redialed; only the DNC entry travels with the number.
</Note>

A disposition that does not contain one to six letters, numbers, underscores,
or hyphens is not written at all. VICIdial keeps whatever it recorded for the
call, usually `RAXFER`. An unmapped disposition that already fits this format is
written unchanged. Menace Voice never truncates a longer outcome into a
plausible-looking but incorrect status.

## Runtime behavior

When the workflow transfers the call, Menace Voice resolves the configured in-group,
applies available lead updates, asks VICIdial to transfer the customer leg, and
then closes only the local Asterisk media leg.

When the conversation ends without a transfer, Menace Voice persists final gathered
context, applies available lead updates, asks VICIdial to hang up the customer
leg, and then closes the local Asterisk leg.

## Troubleshooting

- **VICIdial settings are not visible:** enable **External PBX integrations**
  in Platform Settings.
- **The local media leg ends but the customer remains connected:** confirm that
  `X-VICIDIAL-callerid` and `X-VICIDIAL-user` reach Asterisk and that the agent
  API credentials can control the call.
- **A transfer cannot resolve a destination:** inspect the workflow's final
  gathered context, the configured context path, and the mapping values.
- **The `source` fallback fails:** ensure `X-VICIDIAL-ingroup_id` is present on
  the inbound call.
- **Lead fields are unchanged:** confirm `X-VICIDIAL-lead_id`, the non-agent API
  credentials, and the destination field names.
- **Leads keep VICIdial's own status:** the call's disposition has no entry
  under **Disposition mapping**, or its mapped code is longer than six
  characters. Both are reported in the call logs, naming the disposition to
  map.