Introduction
Flows are the visual blueprints for your AI phone agents - defining what the agent says, collects, calls, and decides from “hello” to hang-up.What are Flows?
Blocks
Individual units of behavior - speak to callers, collect info, call APIs, transfer, end calls, and more.
Edges
Connections that determine which path the conversation takes next.
Variables
The agent’s short-term memory - values that change per call (caller inputs, system data, API results).
Why use Flows?
No code to start
Drag, drop, and configure. Ship fast without waiting on engineering.
Real-time & natural
Handle interruptions, clarifications, and pivots mid-conversation.
Built to scale
Confidently handle thousands of concurrent calls.
Integrations
Call your APIs and systems directly from the Flow.
Core concepts
How to change a Flow
1
Enter edit mode
Open your Flow and click Edit
2
Add blocks
Drag desired blocks from the left sidebar onto the canvas.
3
Configure blocks
Click a block to set prompts, fields, API details, and validation.
4
Connect blocks
Drag from a block’s output port (bottom) to the next block’s input (top).
5
Save
Click Save Each save creates a new version.
Versioning: Every save is a version. You can revert. Always test before pushing to production.
Connecting blocks with edges
1
Create an edge
Click and drag from the output of one block to the input of the next.
2
Configure the edge
Select the edge to open the editor and set guards/requirements.
3
Confirm & save
Define what must be present or confirmed before the edge is taken, then save.
Variables that must exist (and be non-empty) for the edge to be eligible.
Variables the caller should confirm before taking the edge (e.g.,@name, @address).
Call variables
What are call variables?
What are call variables?
Variables are dynamic containers that persist for the duration of the call - like the agent’s working memory.
How to set variables
How to set variables
Use Collect blocks for caller input, API Request blocks for external data, or add custom variables via the Variable modal.
How to access variables
How to access variables
Reference by name with @variable_name or select from the Variable modal. Use them in prompts, conditions, and API payloads.
Variable types
Variables in Phonely can store different types of data. Choose the appropriate type when collecting information from callers or storing data from API responses.| Type | Data Type | Description |
|---|---|---|
| text | string | General text |
| number | number | Numeric values |
| date | ISO date | Dates in ISO format |
| time | HH:mm | Times in 24-hour format |
| name | string | Caller names |
string | Email addresses | |
| phone | string | Phone numbers |
| url | string | Web addresses |
| address | object | Street, city, region, postal code, country |
| currency | number | Monetary values |
| percentage | number | Percent values |
| duration | string | Time spans |
| custom | any | User-defined schema |
Call outcome tagging
Outcome tags enable analytics, reporting, and automations after the call ends.
Automatic
System applies defaults like
completed, failed, or transferred.Custom
Set custom tags in End Call blocks for downstream workflows.
Conditional
Apply tags only when conditions on variables are met.
Testing & best practices
Test your Flows
- Simulation
- Live
1
Upload a recording
Validate recognition and branch logic with real audio.
2
Simulate variables
Seed test values for
@name, @phone, etc.3
Path testing
Walk each branch and confirm expected prompts.
4
Error testing
Force empty/malformed inputs to validate fallbacks.
Design guidelines
Conversation design
Conversation design
Keep prompts natural and concise, offer clear next steps, plan for interruptions, and confirm critical data before proceeding.
Technical hygiene
Technical hygiene
Test all branches, add fallback edges, watch performance metrics, and keep external dependencies resilient.
Variable management
Variable management
Use descriptive names, validate inputs, handle missing data gracefully, and scrub sensitive data when not needed.
Common patterns & workflows
- Customer Service
- Appointment Booking
- Lead Qualification
1
Start & welcome
2
Collect issue details
3
Filter by issue type
4
API request for account/order
5
Provide resolution
6
Confirm satisfaction
7
Route to human if needed
8
End with summary
Troubleshooting guide
Flow not responding
Flow not responding
Verify block connections, confirm required variables are set, test blocks individually, and check API auth/endpoints.
Poor call quality
Poor call quality
Review Talk block voice settings, try alternate voices, adjust rate and pauses, and check variable interpolation.
Transfer failures
Transfer failures
Confirm destination numbers/agents, test fallbacks, and verify timing and availability windows.
Variable issues
Variable issues
Check spelling/case, ensure values are set before use, validate data types, and test prompts using variables.
API integration problems
API integration problems
Test endpoints in isolation, verify credentials and headers, confirm request/response schemas, and watch rate limits/timeouts.
Conclusion
You now have the essentials to design reliable, natural AI phone experiences:- Start simple, iterate quickly.
- Integrate systems as needed.
- Test rigorously and monitor outcomes.
1
Start simple
Build with Start Call,Talk, and End Call
2
Add interaction
Use Collect and Question blocks.
3
Integrate systems
Add API Request and conditional edges.
4
Optimize
Use Filter and Time Filter to route intelligently.
5
Test thoroughly
Apply simulation and live testing practices above.