Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.phonely.ai/llms.txt

Use this file to discover all available pages before exploring further.

Flows are the visual blueprints that define exactly how your AI phone agent behaves, from the greeting, to data collection, to decisions, actions, and the final call outcome. They describe what the agent says, what it asks, what it stores, what APIs it calls, and how the conversation moves forward.
Flow builder in action
Flows are made of several core elements:

​
1. Blocks

Blocks are the individual steps in your workflow. Each block performs one clear function, such as:
  • Speaking to the caller (Talk)
  • Collecting information (Collect).
  • Applying logic or conditions (Filter, Time Filter)
  • Calling an external system (API Request, Google Sheets, Code)
  • Transferring or ending a call (Transfer Flow, End Call)
  • Sending messages (Email, SMS)
  • Running post-call actions.
Blocks are intentionally focused complex behavior is created by connecting blocks together, not by overloading a single block.

​
2. Connections & Exit Conditions

Connections determine how the conversation moves forward. An edge can represent:
  • A simple continuation (always go next)
  • A conditional path (only proceed if a condition is met)
  • An exit outcome (success, failure, escalation, etc)

​
Exit condition tooltips

When you hover over a connection handle or edge, Phonely now displays a tooltip explaining which condition is applied, why the edge exists or what will cause the call to take that path.
Edge Tool Tip Message
This makes large or complex flows easier to understand and debug at a glance.

​
3. Variables

Variables store information during the call, such as:
  • Caller-provided inputs.
  • API responses.
  • System-generated data (timestamp, outcomes, etc.)
List Of Available Variables
They act as the agent’s short-term working memory for the duration of the call.

​
Canvas Controls

Phonely includes several canvas tools to help you navigate and organize large workflows. You’ll find tools for:
  • Add new blocks
  • Using sticky notes
  • Organizing blocks
  • Replacing invalid variables
  • Undo/Redo actions
  • Viewing your change history
See the dedicated toolbar quick actions guide for more details.

​
Create a Flow

1

Go to the agent design page.

2

Click the + to create a new workflow or select an existing workflow and click the Edit button.

3

Click the “+” button between existing blocks or at the end of a chain to insert a new block.

4

New blocks are auto-positioned to keep the layout readable.

The canvas is where you visually design and manage your workflow.
How To Add A New Block
5

Click any block in your flow to open its configuration panel.

Each block contains different settings, and the options you see will depend on the type of block you’re setting up.
Example Configuring A Collect Block
6

Connect blocks

You can change connections between blocks by hovering over an edge clicking the X button, and then place your cursor over the output node of one block and drag the edge to connect to the input node of another block.
7

Save your changes.

Every save creates a new version you can review or revert.
8

Publish when ready.

Publishing makes the version live for real callers.

​
Copy & Paste Across Tabs

You can now select one or multiple blocks. Copy them and then paste them into another open Phonely tab. This allows you to reuse logic across flows and build variations without starting from scratch.
Selecting Blocks Copy Paste

​
Save, Version, and Publish

Every save creates a new version. Versions can be reviewed or reverted. When publishing, review the version details and confirm the version you want to make live for callers.

​
Call variables

Variables are dynamic containers that persist for the duration of the call - like the agent’s working memory.
Use Collect blocks for caller input, API Request blocks for external data, or add custom variables via the Variable modal.
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.
TypeData TypeDescription
textstringGeneral text
numbernumberNumeric values
dateISO dateDates in ISO format
timeHH:mmTimes in 24-hour format
namestringCaller names
emailstringEmail addresses
phonestringPhone numbers
urlstringWeb addresses
addressobjectStreet, city, region, postal code, country
currencynumberMonetary values
percentagenumberPercent values
durationstringTime spans
customanyUser-defined schema

​
Call outcome tagging

Outcome tags enable analytics, reporting, and automations after the call ends.
Call outcomes are configured at the block level. Each block in your workflow can have an outcome tag assigned to it. When a call ends on that block, the call is tagged with that block’s outcome. If the block where the call ends does not have an outcome tag set, Phonely falls back to the last block the call visited that had an outcome defined. This means you only need to tag the blocks that represent meaningful endpoints or milestones in your flow, you don’t need to tag every block.
1

Open any block in your workflow

2

Find the Call Outcome Tagging field in the block settings

3

Select an existing outcome or type a custom one

Outcome Tagging End Block
Some examples of tags that you can use include: appointment scheduled, lead qualified, customer satisfied, escalation needed, no show followup, etc.
Test from here feature

​
Testing & best practices

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

Keep prompts natural and concise, offer clear next steps, plan for interruptions, and confirm critical data before proceeding. 
Test all branches, add fallback edges, watch performance metrics, and keep external dependencies resilient.
Use descriptive names, validate inputs, handle missing data gracefully, and scrub sensitive data when not needed.

​
Troubleshooting guide

Verify block connections, confirm required variables are set, test blocks individually, and check API auth/endpoints.
Review Talk block voice settings, try alternate voices, adjust rate and pauses, and check variable interpolation.
Confirm destination numbers/agents, test fallbacks, and verify timing and availability windows.
Check spelling/case, ensure values are set before use, validate data types, and test prompts using variables.
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:
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.