Pathways Guide

A Pathway in the Voicing AI platform defines the complete conversational flow between your AI assistant and the end user.
It is a structured, visual workflow composed of nodes, edges, and actions that together create intelligent, multi-turn, context-aware voice experiences.

This guide explains everything about building, configuring, and maintaining pathways — including architecture, node types, logic connections, retry and fallback handling, and best practices.

---

Table of Contents

1. Overview
2. Understanding Pathways Architecture
3. Core Components
   • Global Prompt
   • Nodes
   • Edges
   • Actions
4. Creating a New Pathway
5. Node Types
   • Conversation Node
   • Data Extraction Node
   • Action Node
   • Enable Transfer Node
6. Connecting Nodes with Edges
7. Pathway Execution Lifecycle
8. Retry and Fallback Logic
9. Variables and Context
10. Implementation Guide
11. Testing and Debugging Pathways
12. Best Practices
13. Troubleshooting
14. Example Flow: Account Balance
15. Summary

---

1. Overview

A Pathway is the blueprint of how your voice AI interacts with a user.
It determines what the assistant says, how it listens, what actions it performs, and how it transitions between conversational steps.

Pathways combine the following components:

• Global Prompt – defines personality and rules
• Nodes – represent conversational or functional steps
• Edges – define conditional routing
• Actions – connect the assistant to external systems
• Retry and Fallback – handle errors gracefully
• Enable Transfer – escalate to a human when needed

---

2. Understanding Pathways Architecture

Pathways operate as directed graphs where nodes act as individual steps, and edges connect them based on conditions.

[Welcome Node] → (intent == "billing") → [Collect_Account]
       ↓
(intent == "support") → [Troubleshoot]
       ↓
            (true) → [Fallback]

Core Responsibilities of the Engine:

• Execute the active node.
• Evaluate edge conditions in priority order.
• Trigger actions and record their outputs.
• Pass variables forward to maintain conversation context.

---

3. Core Components

Global Prompt

The Global Prompt defines the tone, style, and compliance rules that guide all conversations in a pathway.

You are a friendly and professional assistant.
Always greet users politely and keep responses concise.
Avoid sharing sensitive data.
If you’re unable to complete a request, escalate to a human agent.

Guidelines

• Use clear, simple behavioral rules.
• Keep it brief but comprehensive.
• Focus on persona, empathy, and compliance.

---

Nodes

A Node represents a single, self-contained action in a conversation.

Field	Description
Name	Unique identifier for the node
Type	Conversation / Data Extraction / Action / Enable Transfer
Prompt or Function	What the node says or performs
Inputs	Variables it reads from context
Outputs	Variables it writes to context
Connections	Outgoing edges defining the next steps

---

Edges

Edges define the logic that connects one node to another.
Each edge contains a condition, and if that condition is true, the flow transitions to the target node.

Condition: intent == "billing" → Target: Ask_Account_Number
Condition: true → Target: Fallback_Message

Field	Description
Source	Node from which the edge originates
Condition	Logical expression using context variables
Target	Next node if the condition is met
Priority	Evaluation order when multiple edges exist

Include one unconditional edge (true) as a fallback.

---

Actions

Actions connect your pathway to real systems (CRMs, APIs, or databases).
They are configured in Action Nodes.

{
  "action": "lookup_account_balance",
  "inputs": { "account_number": "12345678" },
  "outputs": { "balance": "240.00", "status": "active" },
  "maxRetry": 2
}

Tips

• Map inputs carefully to ensure API compatibility.
• Use outputs for future prompts or decisions.
• Set appropriate retry limits for reliability.

---

4. Creating a New Pathway

1. Navigate to Pathways → Create New.
2. Enter the pathway name, description, and linked assistant.
3. Configure the Global Prompt.
4. Add nodes in logical order (start with a welcome node).
5. Connect nodes with edges.
6. Add actions and map inputs/outputs.
7. Configure retry and fallback logic.
8. Test using both Web and Telephony clients.
9. Save and publish after validation.

---

5. Node Types

Pathways are composed of four primary node types, each serving a distinct purpose within the conversation lifecycle.
Every node operates in three sequential phases — Enter → Execute → Complete — before control passes to the next node through an edge.

These nodes together define how the assistant speaks, understands, acts, and escalates during an interaction.

---

Conversation Node

Purpose:
Delivers prompts, asks questions, or provides acknowledgments to the user.

Execution Trigger:
Activated immediately when the conversation flow enters this node. It generates a text or speech output through Text-to-Speech (TTS).

Field	Description
Name	Unique identifier for the node
Prompt	Message or instruction spoken to the user
Context	Variables used for personalization (e.g., {customer_name})
Connections	Outgoing edges to the next node(s)

Behavior:

• Dynamically substitutes variables from context in the prompt text.
• Automatically passes user responses to the next connected Data Extraction node.
• Displays visual connectors in the Flow Builder UI when linked downstream.

Example Prompt

Hi {customer_name}, how can I assist you today?

Best Practices

• Keep prompts short, natural, and clear.
• Maintain one conversational goal per node (e.g., greeting, confirmation, or question).
• Always connect to a logical next node, typically an Extraction or Action node.

---

Data Extraction Node

Purpose:
Processes user speech or input and extracts structured data such as intent, identifiers, or keywords.

Execution Trigger:
Runs automatically once the system receives and transcribes the user’s voice input from the preceding Conversation node.

Field	Description
Function Name	Internal identifier for the extractor
Properties	List of variables to extract (key, type, description)
Data Type	String / Integer / Boolean / Enum
Description	Defines what kind of information is being captured

Behavior:

• Converts user speech to text through ASR/STT.
• Maps extracted entities to context variables (e.g., intent, account_number).
• Supports enums for intent classification (billing, support, etc.).
• Routes to the appropriate next node based on extracted values.
• Uses reprompts or fallback edges when extraction confidence is low.

Example Property

Parameter: intent
Type: enum
Values: [billing, technical, sales, other]
Description: Identifies the purpose of the call.

Best Practices

• Define only essential extraction fields.
• Use enums for consistent and predictable branching.
• Include type validation (number, string length, etc.).
• Add reprompts for unrecognized or missing input.
• Keep extraction focused—one clear purpose per node.

---

Action Node

Purpose:
Performs backend operations such as database lookups, API calls, ticket creation, or data validation.

Execution Trigger:
Invoked when its incoming edge condition is satisfied, typically after an Extraction or Conversation node.

Field	Description
Action Name	Registered backend integration or service
Inputs	Context variables used as parameters for the action
Outputs	Variables returned and saved back to context
Priority	Execution order (P1 executes before P2)
Rules	Conditional statements to evaluate action results
Max Retry	Number of retries for transient failures

Behavior:

• Reads input variables from session context.
• Executes an API call or backend function.
• Writes response data to context for later use.
• Evaluates result-based rules to determine the next edge.
• Supports automatic retries and backoff for recoverable errors.

Example

{
  "action": "lookup_account_balance",
  "inputs": { "account_number": 12345678 },
  "outputs": { "balance": 240.00, "status": "active" },
  "priority": "P1",
  "maxRetry": 2
}

Best Practices

• Keep one purpose per Action Node.
• Validate input data before execution.
• Use rules to route success or failure paths.
• Configure retries for network-dependent operations.
• Log action outputs for debugging and analytics.

---

Enable Transfer Node

Purpose:
Transfers the conversation from the virtual assistant to a human agent, ensuring a seamless handoff.

Execution Trigger:
Activated manually (by user request or condition) or automatically (on repeated failure or escalation rule).

Field	Description
Platform	Contact center or telephony system used for handoff
Transfer Prompt	Message spoken before transferring
Context	Key variables passed to the human agent
Target	Destination agent, queue, or department

Behavior:

• Plays a polite transfer prompt before initiating the handoff.
• Shares essential context with the live agent (e.g., name, intent, issue summary).
• Marks the AI session as complete and transitions to human assistance mode.
• Ensures a smooth user experience with zero context loss.

Example Prompt

I’ll connect you with a specialist who can help you further.

Best Practices

• Always include a courteous closing or explanation before transfer.
• Pass only relevant context variables (avoid sensitive data).
• Ensure the receiving agent can view all shared context.
• Use this node as the final fallback in complex pathways.

---

Node Interaction Summary

Node Type	Role	Input Source	Output	Common Next Step
Conversation	Speak or prompt user	Context	User response	Data Extraction
Data Extraction	Parse and extract user intent/data	User input	Extracted variables	Action or Conversation
Action	Execute backend process	Context variables	Updated context	Conversation or Transfer
Enable Transfer	Escalate to a human agent	Context variables	Handoff summary	End of flow

---

6. Connecting Nodes with Edges

Edges define how the system decides the next step.

[Extract_Intent]
 ├─ (intent == "billing") → [Ask_Account_Number]
 ├─ (intent == "technical") → [Troubleshoot]
 └─ (true) → [Fallback_Node]

Tips

• Evaluate edges by priority (1 = highest).
• Always include a true fallback edge.
• Use explicit comparisons for clarity.

---

7. Pathway Execution Lifecycle

1. Conversation node speaks to the user.
2. User response is transcribed via STT.
3. Data Extraction node parses and stores variables.
4. Edges evaluate conditions to determine the next step.
5. Action node performs backend operations.
6. Conversation continues or escalates via transfer.

Flow Diagram:

Conversation → Extraction → Action
       ↘ success / failure ↙
           Fallback / Transfer

---

8. Retry and Fallback Logic

Action nodes can retry automatically on transient failures.

maxRetry: 2
Variable: retry_count
Condition Edge: retry_count >= 2 → Enable_Transfer

Recommendations

• Include helpful retry messages.
• Log retry attempts for diagnostics.
• Always add a fallback route to avoid dead ends.

---

9. Variables and Context

Context represents the shared memory of a pathway.
It stores every variable collected or produced during the conversation and makes it available to later nodes.

How Context Works

• Each session maintains a session context (persists through the call) and a node context (temporary, cleared after the node finishes).
• Variables are created by:
  • Data Extraction Nodes (e.g., intent, account_number)
  • Action Nodes (e.g., balance_amount, ticket_status)
  • System variables (e.g., retry_count, session_id)
• When multiple variables share the same name, the latest value overrides the previous one for the current session.

Using Context

• Reference variables inside prompts using {variable_name}.
• Reference them in conditions or rules directly (e.g., account_status == "active").
• Action inputs can map to any available context variable.

Best Practices

• Use snake_case for all variable names.
• Verify variable types before evaluating conditions.
• Avoid exposing PII or sensitive values in prompts or logs.
• Clean up or reset unused variables after session completion.
• Pass only necessary fields when transferring to a human.

Example

Hi {{customer_name or "there"}}, your current balance is {balance_amount}.

---

10. Implementation Guide

Step 1 – Conversation Node: Welcome_Message

Field	Value
Name	Welcome_Message
Prompt	“Thank you for calling. How can I assist you today?”
Next	Extract_User_Intent

Step 2 – Data Extraction Node: Extract_User_Intent

Property	Type	Description
intent	enum	Detects user’s purpose (“billing”, “support”, etc.)
user_query	string	Captures free-form request

Edges

(intent == "billing") → Ask_Account_Number
(intent == "technical") → Troubleshoot
(true) → General_Help

Step 3 – Conversation Node: Ask_Account_Number

Prompt:

Please share your 8-digit account number.

Next: Extract_Account_Number

Step 4 – Data Extraction Node: Extract_Account_Number

Property	Type	Description
account_number	integer	Captures account number from user response

Edges

(account_number > 0) → Lookup_Balance
(true) → Ask_Account_Number  // reprompt if missing

Step 5 – Action Node: Lookup_Balance

Field	Value
Action Name	lookup_account_balance
Inputs	account_number
Outputs	balance_amount, account_status, last_payment_date
Max Retry	2

Rules

(account_status == "active") → Provide_Balance_Info
(true) → Account_Suspended_Message

Step 6 – Conversation Node: Provide_Balance_Info

Prompt:

Your current balance is {balance_amount}. The last payment was on {last_payment_date}. Do you need further assistance?

Edges

(user_response == "no") → End_Call
(true) → Extract_User_Intent

Step 7 – Conversation Node: Account_Suspended_Message

Prompt:

Your account appears to be suspended. I will connect you with a support specialist.

Next: Enable_Transfer

Step 8 – Enable Transfer Node

Field	Value
Platform	Contact center system
Transfer Prompt	“Connecting you to an expert...”
Context Passed	customer_name, account_number, intent, issue_type

---

11. Testing and Debugging Pathways

Web Client

• Run the pathway directly in the browser.
• Observe live logs with color-coded layers:
  • Purple – Node execution
  • Teal – Extraction events
  • Gray – Edge evaluation
  • Pink – Rule or condition results

Telephony Client

• Enter a valid phone number.
• Test full end-to-end flow including speech, transfer, and latency.
• Each call generates a unique Call ID for tracking.

---

12. Best Practices

• Keep one objective per node.
• Always include a fallback edge.
• Use enums for stable intent routing.
• Keep prompts conversational and concise.
• Validate variable types before condition checks.
• Configure reasonable retry counts.
• Pass only necessary context to human transfers.
• Test both web and telephony flows before release.

---

13. Troubleshooting

Issue	Cause	Resolution
Node not executed	Missing or incorrect edge	Verify incoming edge and condition
Edge not triggered	Type mismatch	Correct variable type or value
Extraction empty	Low confidence	Add reprompts or expand enums
API failure	Timeout or credentials issue	Validate integration settings
Looping conversation	Missing fallback	Add a true fallback route
Missing context	Variable not passed	Include variable in node context
Transfer fails	Platform misconfigured	Check telephony or CC integration

---

14. Example Flow: Account Balance

[Welcome_Message]
      ↓
[Extract_User_Intent]
   ├─ (intent == "billing") → [Ask_Account_Number] → [Extract_Account_Number] → [Lookup_Balance]
   │                                                                  ├─ (active) → [Provide_Balance_Info] → [End/Loop]
   │                                                                  └─ (inactive) → [Account_Suspended_Message] → [Enable_Transfer]
   ├─ (intent == "technical") → [Troubleshoot]
   └─ (true) → [General_Help]

This demonstrates the entire conversational cycle — from greeting, understanding, action execution, and branching to fallback or escalation.

---

15. Summary

Pathways bring structure and consistency to AI-driven conversations.
They combine Conversation, Extraction, Action, and Transfer nodes linked through Edges to produce natural, goal-oriented voice flows.

With proper use of:

• Global Prompts for tone,
• Edges for decision logic,
• Context for memory, and
• Retry and transfer for resilience,

your assistant becomes intelligent, reliable, and user-friendly.

---

Last updated: [04/12/2025]
Version: 1.0