Call Trail

Every call has a trail — a short array of caller-perspective labels in the order Allison's tools fired during the call, with consecutive duplicates collapsed. It's the path the caller took, in plain language. Same field shows up on the call.ended webhook payload AND on GET /v1/calls/{id} so you can render it the same way in real-time integrations and historical lookups.

What it looks like

{
  "trail": ["Lookup Shipment", "Lookup Shipment Locations", "Send Booking SMS"]
}

Render in your UI however you want:

• Breadcrumb column: trail.join(" > ") → Lookup Shipment > Lookup Shipment Locations > Send Booking SMS
• Chip list: map each entry to a chip
• Timeline: combine with started_at + duration_seconds for time-anchored display
• Slack message: include the joined string in the call notification body

Examples across industries

The trail is universal — it works the same way regardless of what your business does. Some real-world examples:

Where labels come from

Allison resolves each label automatically — no configuration needed:

• Custom integrations you've added (under Settings → Knowledge → Integrations) use the integration's Name field as the trail label. If you named your integration "Lookup Shipment", that's what appears in the trail. Edit the integration name to change how it shows up.
• Built-in tools (transfer, callback, message, escalation, calendar booking, order taking, etc.) use a fixed set of labels designed to read naturally to a human reviewer.

What's NOT in the trail

A few categories of tool calls are deliberately excluded so the trail stays focused on the caller's actual journey:

• Internal lookups (foundational knowledge searches, caller-history checks) support Allison's responses but aren't user-facing actions
• Terminal actions (end_call) are always at the end, redundant
• Low-signal mechanics (send_dtmf keypresses) are usually internal navigation, not part of the caller's narrative
• Integrations with action_type = 'check' are pre-flight gating mechanics (blocked-caller lookups, suppression filters, eligibility checks). They run BEFORE a caller-visible action and aren't part of the caller's path. Set your integration's action type to check to keep that step out of the trail.

If a tool fires that isn't in the registry and isn't a custom integration of yours, it's skipped. We never show raw tool keys to subscribers.

How consecutive duplicates are handled

If Allison calls the same tool back-to-back (e.g., the caller asked about three different loads in a row, so Lookup Shipment fired three times), the trail collapses it to a single entry:

• Raw: [Lookup Shipment, Lookup Shipment, Lookup Shipment, Lookup Shipment Locations]
• Stored: [Lookup Shipment, Lookup Shipment Locations]

Non-consecutive duplicates are preserved — they reflect the caller navigating back to a previous step:

• [Lookup Shipment, Lookup Shipment Locations, Lookup Shipment] stays as-is. The caller looked up a load, asked about hours, then asked about a different load.

The distinction matters when you're using the trail to understand call patterns — pure repetition is noise; back-and-forth navigation is signal.

What the trail is NOT

• Not timestamps. Each entry doesn't carry a time. The order is the only timing signal. (We may add a separate tool_calls field with timestamps and arguments later if subscribers ask.)
• Not status indicators. A failed tool call still appears in the trail — the attempt was part of the caller's path. Failure detail lives in the call transcript and Watchtower scoring.
• Not arguments. Trail entries are labels only — they don't include the data the tool received (caller phone, reference numbers, etc.). For diagnostic detail, look at the call summary or transcript.
• Not transcripts. The trail is a high-level sketch of what happened — for the actual conversation, use GET /v1/calls/{id} and read summary.transcript.

Pairing trail with other fields

The trail works best when combined with other call fields:

• disposition tells you the outcome (transferred, escalated, completed, missed). Trail tells you the path that led there.
• summary is a full prose recap. Trail is the skeleton — useful as a column / chip / one-liner where prose doesn't fit.
• contact_id lets you link the call back to a contact in your CRM. Combine with trail to build a "this caller's last 5 visits" history view.

Backwards compatibility

trail is a new field added to existing payloads. If you're already consuming call.ended in your handler, ignore the field if you don't need it — webhooks are forward-compatible by design (see using-webhooks.md on ignoring unknown fields). Old calls (placed before this feature shipped) have an empty trail array — render them with - or "no tool data" if you want to disambiguate visually.