# Guidelines
Source: https://docs.phonely.ai/agent-design/guidelines
Define the shared goals, response style, and boundaries that guide your agent across flows.
Guidelines define the goals, communication style, and boundaries that should remain consistent across an agent's conversations. They are available to every flow that has **Include Guidelines** turned on.
Use Guidelines for shared behavior. Put instructions that apply only to one flow or one part of a call in that flow or block instead.
## Choose where information belongs
| Put it in | Use it for |
| :--------------------------------------------------- | :---------------------------------------------------------------------- |
| **Guidelines** | Agent-wide goals, tone, boundaries, objections, and business rules |
| [**Knowledge Base**](/agent-knowledge-base/overview) | Detailed reference material the agent may need when answering questions |
| [**Flow Settings**](/flow-editor/flow-settings) | Context and instructions that apply to one flow |
| **Block configuration** | The objective, wording, or behavior for one step in a flow |
Avoid copying the same instruction into several places. Conflicting instructions make the agent's behavior less predictable and make future updates harder to maintain.
## Choose guideline sections
Add only the sections your agent needs:
| Section | Use it for |
| :----------------- | :--------------------------------------------------------------- |
| **Objective** | The primary result the agent should work toward |
| **Response Style** | Tone, personality, concision, and speaking style |
| **Never Do** | Strict actions, claims, or promises the agent must avoid |
| **General Info** | Short, stable business facts the agent may reference at any time |
| **Rebuttals** | How to respond to common objections or pushback |
| **Out of Scope** | What to do when a request cannot be answered or handled |
| **Custom** | Additional agent-wide guidance that does not fit another section |
Prefer the most specific section. For example, place a prohibited promise in **Never Do**, not in a broad Custom section. Keep detailed policies, service information, and frequently changing facts in the Knowledge Base rather than repeating them in **General Info**.
### Configure Response Style
The **Response Style** section combines written guidance with two agent settings:
* **Personality** sets the general conversational style, such as Direct, Formal, Persuasive, or Friendly.
* **Humanize speech** allows the agent to use vocal fillers such as “hmm” and “umm.”
Use the written section for details the preset does not express, such as how concise answers should be or how the agent should respond to an upset caller.
## Write effective guidelines
* State what the agent should do in direct, specific language.
* Define a clear fallback when the agent cannot complete a request.
* Use **Never Do** for genuine hard boundaries, not general preferences.
* Keep shared guidance independent of a particular flow path or block.
* Remove instructions that duplicate or contradict another section.
> **Example:** If the caller asks for a service you cannot confirm, explain that a team member can follow up and offer to collect their contact details. Do not invent availability or pricing.
## Add and edit sections
Open **Agent Design**, then select **Guidelines**.
1. Select **Add Section** and choose a section type.
2. Select the section in the sidebar and enter its guidance.
3. Add a **Custom** section only when no predefined section fits; give it a specific name.
Changes save automatically after you stop editing. Wait for the status to show **Saved** before leaving the editor. You can delete any configured section; only Custom sections can be renamed.
To get help with a section, select it and choose **Ask AI**. Ask AI can inspect or improve the selected section, so review the result alongside the other Guidelines.
## Use Guidelines in a flow
New flows include the agent's Guidelines by default. To review the setting for a flow, open [Flow Settings](/flow-editor/flow-settings) and find **Include Guidelines**.
Turn the setting off only when that flow should operate without the shared guidance. If a flow needs additional instructions, keep Guidelines enabled and add the flow-specific context in Flow Settings or the relevant blocks.
## Test the behavior
Before testing, confirm that **Include Guidelines** is turned on for the flow. Then:
1. Use **Web Chat** to check the agent's goal, boundaries, objection handling, and out-of-scope response across the main conversation and important alternate paths.
2. Use **Web Call** to hear its tone, pacing, and Response Style.
3. Resolve any conflict between Guidelines, Flow Settings, and block instructions before relying on the updated behavior.
## Troubleshooting
Confirm that **Include Guidelines** is turned on for the flow. Then check for conflicting or more specific instructions in Flow Settings and the active block. Rewrite broad guidance as a direct rule in the most appropriate section.
Review all configured sections for duplicated or conflicting instructions. Keep one source for each rule, make the desired behavior specific, and test more than one conversation path.
# Agent Setup
Source: https://docs.phonely.ai/agent-design/overview
Understand the parts of a Phonely agent and where to configure each one.
Agent Setup brings together the shared parts of one agent: how it sounds, how it should behave, what it knows, and the settings that apply across its calls. The agent's flows then determine what happens before, during, and after each call.
If you completed onboarding, start with the agent and starter flow Phonely created for you. You do not need to create another agent to begin configuring it.
## Understand the parts of an agent
| Area | Use it to |
| :--------------------------------------------------- | :--------------------------------------------------------------------------------------------------- |
| [**Voice**](/agent-design/voice/overview) | Choose how the agent sounds |
| [**Guidelines**](/agent-design/guidelines) | Define shared objectives, response style, and boundaries |
| [**Knowledge Base**](/agent-knowledge-base/overview) | Provide documents, websites, and calls the agent can use as knowledge |
| [**Flows**](/key-concepts/flows) | Control the conversation, routing, data collection, and actions |
| **Settings** | Manage the agent's identity, phone numbers, call behavior, compliance, and other agent-wide controls |
Voice, Guidelines, Knowledge Base sources, and Settings are configured for the agent. Flows belong to that agent and control individual call paths.
## How flows use shared configuration
An agent can have multiple flows, but they use the same agent-level configuration. Each flow can decide whether to include the agent's Guidelines and which uploaded documents or websites it can reference.
Use [Flow Settings](/flow-editor/flow-settings) to control those choices for one flow. Put instructions that apply only to one part of a call in that flow or block instead of adding them to the agent's shared Guidelines.
## Open Agent Settings
In **Agent Design**, select **Settings**. From there, you can update the agent name and primary number, duplicate or delete the agent, and open these settings areas:
| Area | Use it for |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------- |
| **Call Settings** | Call-wide timing and behavior |
| **Phone Numbers** | The agent's phone numbers and blocked numbers |
| **Compliance** | Recording and compliance controls |
| **Analytics** | Analytics Fields (including call topics on agents that already use them), sentiment definitions, and API-recorded outcomes |
| **Advanced** | Specialized behavior that normally does not need to change during initial setup |
Start with the defaults unless a business requirement calls for something different. Before handling real calls, confirm the phone number, timezone, recording, and compliance settings required for your use case.
## Recommended setup order
1. Review the agent created during onboarding.
2. Choose a Voice and define the agent's Guidelines.
3. Add only the knowledge sources the agent needs.
4. Review the starter flow and adjust its conversation and actions.
5. Review Agent Settings, then publish and test the flow before using it for live calls.
For the complete first-call process, follow [Quick Start](/get-started/quick-start).
# Voice
Source: https://docs.phonely.ai/agent-design/voice/overview
Choose, configure, and test how your agent sounds during calls.
Voice controls the speech callers hear during phone conversations. The selected voice and its settings belong to the agent and apply across its inbound and outbound flows.
Use [Guidelines](/agent-design/guidelines) to control the agent's personality, tone, and response style. Voice controls how those responses sound when spoken.
## Choose a voice
Open **Agent Design**, then select **Voice**.
1. Play a voice to preview it with the sample text in the test card.
2. Search by voice name or filter the library by language, gender, accent, or other available traits.
3. Select the voice you want the agent to use.
The selected voice appears first in the library. Use the heart control to save favorites, and use **Mine** to view voices owned by you or your organization. To give one of these voices a clearer label, select **Rename voice** in its row, enter a name, and select **Save**. Renaming is unavailable while the agent is read-only.
Choose a voice that remains clear at phone-call audio quality and fits the conversations the agent handles. Accent, pacing, and pronunciation are usually more important than how expressive a voice sounds in a short sample.
## Customize the voice
Use **Voice Settings** to adjust the selected voice. Changes save automatically.
| Setting | What it controls |
| :------------------- | :----------------------------------------------------- |
| **Speed** | How quickly the agent speaks; range varies by provider |
| **Languages** | Which languages the agent understands and replies in |
| **Background Noise** | Optional office ambience and its volume |
| **Pronunciations** | How Cartesia voices pronounce specific names or terms |
### Choose the agent's languages
**Languages** is the single control for what your agent hears and says. New agents start with English.
What you can choose depends on two things:
* **The transcriber.** Each speech recognition engine supports its own set of languages. Switching engines keeps only the languages the new one accepts.
* **The selected voice.** A voice that speaks one language limits the agent to that language. Choose a Spanish-only voice on an English agent and the agent handles Spanish, not both.
When only one language is available, the control becomes a single choice and explains why. If a multi-language selection has to narrow, an inline message and a toast name the voice and the one language the agent will use.
Select only the languages your callers actually use. Extra languages give the agent more ways to mishear a caller without improving the conversations you expect.
### Add pronunciations
**Pronunciations** is available for Cartesia voices. Add an entry when the agent needs to say a name, brand, acronym, or specialized term consistently.
Enter the written word and its pronunciation, then play the entry before saving it. Expand **Phonemes** only when the generated pronunciation needs a precise adjustment.
### Configure transcription
Expand **Advanced** in Voice Settings to add **Transcription Keywords**, which help the transcriber recognize uncommon names, product terms, or identifiers.
The **Transcriber** itself is selected in **Agent Settings > Advanced > Interruptions Control**. Keep the default unless testing shows that another engine better fits the language or audio conditions of your calls. Changing the engine keeps your language selections compatible with it and applies that engine's interruption defaults.
## Test the voice
Enter a representative sentence in the test card. Include names, numbers, or specialized terms the agent will commonly say.
1. Preview several voices with the same text so the comparison is meaningful.
2. Select a voice, adjust its settings, and preview it again.
3. Confirm the pronunciation, pace, and background sound before testing the complete agent.
4. Use **Web Call** to hear the voice in a real conversation and check turn-taking, interruptions, and phone-call audio quality.
A voice preview tests synthesized speech, not the complete call experience. Always complete a Web Call before relying on a new voice or major setting change.
## Add or clone a voice
Select **Add or Clone a Voice** when the built-in library does not contain the voice you need.
Choose **Add a voice**, then select the provider and model. Enter the voice ID from the provider and select its language. Add an optional **Name** to label the voice in your library, or leave it blank to use a name derived from the provider's voice name. Adding the voice also selects it for the current agent, so test it before using the agent for live calls.
To compare the same provider voice on different models, add it again with the same voice ID and a different model. Each model has its own library entry. Give the entries distinct names so you can tell them apart when choosing a voice. The form prevents adding the same provider voice ID on the same model again.
Choose **Clone a voice**, then upload or record a clear 1–2 minute sample. Enter a unique name, gender, and language, and confirm that you have permission to clone and use the recording. Compare the generated samples before saving one. The saved voice becomes the current agent's selected voice.
## Troubleshooting
Either the selected voice speaks a single language, or the transcriber does not support that language. Select a multi-lingual voice, or change the transcriber in **Agent Settings > Advanced > Interruptions Control**, then set **Languages** again.
If the selected voice supports **Pronunciations**, add the word and test a clearer pronunciation. If the setting is unavailable, select a Cartesia voice or another voice that already pronounces the term correctly.
Confirm that the intended voice is still selected and rerun the preview after changing Speed, Background Noise, or Pronunciations. Then use Web Call: phone audio, caller interruptions, and the surrounding conversation are not represented by an isolated voice preview.
# Knowledge Base
Source: https://docs.phonely.ai/agent-knowledge-base/overview
Give your agent trusted information to use during calls.
Use the Knowledge Base for facts and reference material your agent may need, such as services, pricing, policies, operating hours, and frequently asked questions.
Keep behavior in [**Guidelines**](/agent-design/guidelines). Use the Knowledge Base for information the agent should look up rather than instructions it should always follow.
## Choose a source
Select **+** in the Knowledge Base to add a source:
| Source | Use it for |
| -------------------- | ---------------------------------------------------- |
| **Blank Document** | Write and maintain information directly in Phonely |
| **Upload File** | Add an existing PDF, DOCX, or TXT file |
| **Add Website** | Add one public page or select pages from a site |
| **Upload Recording** | Add an MP3, WAV, M4A, or WebM recording for playback |
| **Import External** | Import selected documents from LivePro |
Documents and websites provide the reference content that flows can use. Recordings are available for playback and show a transcript when one is available, but they are not selected as flow knowledge sources.
## Add useful content
Organize information around the questions callers ask. Use descriptive titles, clear headings, and direct answers. Keep related details together so the agent can retrieve enough context to answer accurately.
For reliable results:
* include the exact facts the agent should use;
* remove duplicate or conflicting versions of the same information;
* state exceptions beside the rule they modify; and
* update time-sensitive details when they change.
Avoid using the Knowledge Base for tone, conversation rules, or actions the agent must always take. Put those instructions in [**Guidelines**](/agent-design/guidelines), [**Flow Settings**](/flow-editor/flow-settings), or the relevant block.
## Manage sources
Use **All**, **Docs**, **Sites**, and **Calls** to filter the source list, or search by name. Select a source to review its details.
Edits to written documents and website content save automatically in the detail panel. A website source does not refresh automatically when its public page changes. Uploaded files can be opened for review, but their contents are not edited in Phonely.
Documents and websites can be **Active** or **Inactive**. An inactive source remains in the Knowledge Base but is not used for retrieval. Use **Select** to activate or deactivate multiple documents and websites, or to delete multiple sources, including recordings.
Deleting a source removes it from the agent. Confirm that its content is no longer needed before deleting it.
## Make sources available to a flow
Knowledge Base sources belong to the agent. In a flow's [**Flow Settings**](/flow-editor/flow-settings), choose whether that flow can use all or selected documents and websites.
In a supported prompt field, insert **All Knowledge Base**, **All Documents**, **All Websites**, or a specific source from **Available Variables**. For example, a [**Talk**](/blocks/flow-blocks/talk) block can use selected reference material while answering caller questions.
If you add or replace a source, review the flow's source selection before testing it again.
## Verify the answers
Test with questions that the source answers directly, questions that require details from different sections, and questions the source does not answer. Confirm that the agent uses the documented facts and does not invent missing information.
Start with **Web Chat** for a quick content check, then use **Web Call** when you also need to review how the answer sounds. After a test, open **Call Details** and review **Referenced Knowledge Base** to see which content the agent used.
## Troubleshooting
Confirm that the document or website is active and available in the flow's **Flow Settings**. Then check that the relevant block prompt includes the intended Knowledge Base source and publish the updated flow before testing it.
Search for another source that contains an older version of the same information. Update or deactivate conflicting content, then test the question again.
Open the website source and review the saved content. Add the correct page or update the saved content when the public page has changed.
Uploaded files are read-only in the Knowledge Base. Replace the file, or create a **Blank Document** when the content needs to be maintained directly in Phonely.
# Agent Review
Source: https://docs.phonely.ai/agent-review
Triage issues reported while reviewing calls.
Agent Review organizes issues that your team reports from calls. It provides a shared queue for moving an observed problem from review to resolution.
Use [Call History](/call-history-ai-analytics/call-history-ai-analytics) to investigate a call. Use Agent Review when the investigation needs to become tracked work.
## Work through the queue
Issues are grouped by agent. Filter the queue by organization, date range, severity, or tags, then use the status tabs:
| Status | Meaning |
| --------------- | ------------------------------------ |
| **Open** | Reported and waiting for work |
| **In Progress** | Actively being investigated or fixed |
| **Resolved** | Addressed and complete |
| **Cancelled** | Closed without further work |
| **All** | Every issue in the current scope |
Open an issue to review its description, call context, transcript, tags, and other available details. Update the status as the work progresses.
## Keep reviews actionable
* Describe the observed behavior rather than only the expected fix.
* Include enough call context for another person to reproduce or understand the issue.
* Use severity for impact and tags for categorization.
* Mark an issue resolved only after the relevant behavior has been checked.
Agent Review does not change an agent or flow. Make product changes in [Agent Design](/agent-design/overview), test them, then return to the issue to record its final status.
# Add Blocked Numbers
Source: https://docs.phonely.ai/api-reference/endpoint/add-blocked-numbers
POST /agent-block-list
Add one or more phone numbers to an agent's block list.
Adds phone numbers to an agent's block list. The API key must belong to the supplied user, and that user must have access to the agent.
The response separates numbers that were added from numbers that failed validation or were already blocked. Handle both arrays because a request can partially succeed.
# List Documents
Source: https://docs.phonely.ai/api-reference/endpoint/agent-documents
GET /agent-documents
List the documents in an agent's knowledge base.
Returns the documents associated with an agent's knowledge base. The API key must belong to the supplied user, and that user must have access to the agent.
Use the related operations to upload or delete documents. An upload accepts up to 10 PDF, DOCX, or TXT files per request, with a maximum size of 10 MB per file.
# List Websites
Source: https://docs.phonely.ai/api-reference/endpoint/agent-websites
GET /agent-websites
List the websites in an agent's knowledge base.
Returns the website sources associated with an agent's knowledge base. The API key must belong to the supplied user, and that user must have access to the agent.
Use the related operations to add or delete a website source. When adding one, `limit`, `maxDepth`, `includePaths`, and `excludePaths` control how the website is crawled. Phonely caps `limit` and `maxDepth` at 10.
# List Blocked Numbers
Source: https://docs.phonely.ai/api-reference/endpoint/block-list
GET /agent-block-list
List the phone numbers blocked for an agent.
Returns the phone numbers blocked for an agent. The API key must belong to the supplied user, and that user must have access to the agent.
# Delete Document
Source: https://docs.phonely.ai/api-reference/endpoint/delete-agent-documents
DELETE /agent-documents
Delete a document from an agent knowledge base.
# Delete Website
Source: https://docs.phonely.ai/api-reference/endpoint/delete-agent-websites
DELETE /agent-websites
Delete a website from an agent knowledge base.
# Duplicate Agent
Source: https://docs.phonely.ai/api-reference/endpoint/duplicate-agent
POST /duplicate-agent
Create a copy of an agent you can access.
Creates a new agent from an existing agent's configuration. The API key must belong to the supplied user, and that user must have access to the source agent.
The response identifies the new agent by its `agentId` and includes its name and owning user ID.
# Generate an Agent
Source: https://docs.phonely.ai/api-reference/endpoint/generate-agent
POST /agent-generations
Create an inbound agent and its first flow from a prompt.
Starts asynchronous generation of a new inbound agent and its first flow from a natural-language prompt.
Send a unique `Idempotency-Key` with every logical request. Repeating the same request with the same key returns the existing generation instead of creating another agent. Reusing the key with different request data returns an idempotency conflict.
The initial response includes a `generationId` and a `Location` header. Poll that location until the status is `completed` or `failed`.
Store the idempotency key until generation reaches a terminal status. Retrying a failed generation with the same request and key safely reuses its reserved agent and flow instead of provisioning duplicates.
## Generation statuses
| Status | Meaning |
| ------------ | -------------------------------------------------------- |
| `queued` | The request was accepted and is waiting to start |
| `generating` | Phonely is building the agent and first flow |
| `completed` | The response includes the new `agentId` and `workflowId` |
| `failed` | The response includes an error code and message |
Only users with permission to edit agent design in the selected organization can generate an agent.
# Get Agent
Source: https://docs.phonely.ai/api-reference/endpoint/get-agent
POST /get-agent
Return basic information about one accessible agent.
Returns the agent's ID, name, and owner ID, plus its country and business phone number when available. The API key must belong to the supplied user, and that user must have access to the agent.
This endpoint returns a compact agent record rather than the complete flow configuration.
# Generation Status
Source: https://docs.phonely.ai/api-reference/endpoint/get-agent-generation
GET /agent-generations/{generationId}
Check the status of a prompt-based agent generation.
Returns the current status of an agent generation owned by the authenticated user.
Poll the URL supplied in the creation response's `Location` header. Stop polling when the status is `completed` or `failed`. A completed response includes the generated `agentId` and `workflowId`; a failed response includes an error code and message.
Generation status responses are not cached.
# Get Agents
Source: https://docs.phonely.ai/api-reference/endpoint/get-agents
POST /get-agents
List basic information for a user's agents.
Returns compact records for the agents assigned directly to the supplied user. Each record includes the agent's ID, name, owner ID, country, and business phone number when available.
The `X-Authorization` API key must belong to the supplied user ID.
# Get Call
Source: https://docs.phonely.ai/api-reference/endpoint/get-call
POST /get-call
Return one call belonging to an accessible agent.
Returns call details and analysis for the supplied call and agent IDs. The API key must belong to the supplied user, and that user must have access to the agent.
Phonely returns `404` when the call does not exist or does not belong to the specified agent.
# Get Organizations
Source: https://docs.phonely.ai/api-reference/endpoint/get-orgs
GET /get-orgs
List the organizations assigned to a user.
Returns compact records for the organizations assigned to the supplied user. Each record includes the organization ID and name.
The `X-Authorization` API key must belong to the supplied user ID.
# Import Number
Source: https://docs.phonely.ai/api-reference/endpoint/import-number
POST /import-number
Import a Twilio phone number for an accessible agent.
Imports a Twilio number and assigns it to an agent. The API key must belong to the supplied user, and that user must have access to the agent.
The agent must be on a paid plan and must not already have a business phone number. Only `twilio` is accepted as the source in this production version.
Treat the Twilio account SID and auth token as secrets. Do not place them in client-side code, screenshots, or logs.
# List Calls
Source: https://docs.phonely.ai/api-reference/endpoint/list-calls
GET /calls/{agentId}
List and filter calls for an accessible agent.
Returns a paginated list of calls for an agent. Authentication must grant access to the agent in the path.
Repeat array query parameters such as `status`, `sentiment`, `call_type`, `outcome`, `ended_reason`, and `mode` to include multiple values. Dates use ISO 8601 date-time values, and durations are measured in seconds.
Use `campaign_id` or `ab_test_id` to restrict results to a campaign or A/B test.
The response's `total` is the number of matching calls before `limit` and `offset` are applied.
# List Voices
Source: https://docs.phonely.ai/api-reference/endpoint/list-voices
GET /list-voices
Return the public voices available for agents.
Returns public voice records with their IDs and display metadata, including language, accent, tags, gender, and multilingual support when available.
This endpoint does not require authentication.
# Upload Documents
Source: https://docs.phonely.ai/api-reference/endpoint/post-agent-documents
POST /agent-documents
Upload documents to an agent knowledge base.
# Add Website
Source: https://docs.phonely.ai/api-reference/endpoint/post-agent-websites
POST /agent-websites
Add a website to an agent knowledge base.
# Remove Blocked Numbers
Source: https://docs.phonely.ai/api-reference/endpoint/remove-blocked-numbers
DELETE /agent-block-list
Remove one or more phone numbers from an agent's block list.
Removes phone numbers from an agent's block list. The API key must belong to the supplied user, and that user must have access to the agent.
The response separates numbers that were removed from numbers that were invalid or not present. Handle both arrays because a request can partially succeed.
# Report Call Error
Source: https://docs.phonely.ai/api-reference/endpoint/report-call-error
POST /report-call-error
Submit feedback about a call to the Phonely team.
Submits the call ID, a contact email, and a description of the problem for review. The API key must belong to the supplied user, the user must have access to the agent, and the call must belong to that agent.
Use a specific `reason` that explains the observed behavior and the expected behavior.
# Set Post-Call Outcome
Source: https://docs.phonely.ai/api-reference/endpoint/set-post-call-outcome
PATCH /calls/{agentId}/{callIdOrPhone}
Update custom outcome data for a call.
Updates any supplied custom outcome, numeric value, or metadata for a call belonging to the agent.
Identify the call with either its call ID or a customer phone number. For a phone number, `preference=last` updates the most recent matching call by default; use `preference=first` for the earliest match. Formatting characters are removed before the phone number is validated and matched.
Fields omitted from the request are left unchanged.
# Update Agent
Source: https://docs.phonely.ai/api-reference/endpoint/update-agent
POST /update-agent
Update supported setup fields for an accessible agent.
Updates supported agent setup fields. The API key must belong to the supplied user, and that user must have access to the agent.
When updating `orgId`, the destination organization must be accessible to the user. Voice IDs and conversation styles are validated before the update is applied.
# Introduction
Source: https://docs.phonely.ai/api-reference/introduction
Authenticate requests and work with supported Phonely API resources.
Use the Phonely API to generate and manage agents, inspect calls, manage agent knowledge sources, work with phone numbers, and retrieve organization data. The base URL is `https://app.phonely.ai/api`.
## Get your API key
1. Sign in to the Phonely app.
2. Open **Settings**, then select **Account**.
3. Under **Access**, reveal and copy the **API Key**.
## Authenticate requests
Send the key in the `X-Authorization` header unless an endpoint states that authentication is not required.
```bash theme={null}
curl https://app.phonely.ai/api/agent-generations/GENERATION_ID \
-H "X-Authorization: YOUR_API_KEY"
```
## Generate an agent
1. [Start an agent generation](/api-reference/endpoint/generate-agent) with a prompt and an idempotency key.
2. [Check the generation status](/api-reference/endpoint/get-agent-generation) until it completes or fails.
The navigation groups the remaining endpoints by resource. Each endpoint guide documents its request, response, access checks, and important limitations.
To add browser-based voice calls to your own application, use the [Web SDK](/api-reference/web-sdk).
## Supported API surface
The endpoints listed in this API Reference are the supported customer API contract. Routes used internally by the Phonely application, including billing and Ask AI operations, are not public integration endpoints even when they use an `/api` URL.
Keep your API key confidential. Do not share it publicly or commit it to source control.
# Web SDK
Source: https://docs.phonely.ai/api-reference/web-sdk
Add secure browser-based Phonely voice calls to your application.
The Phonely Web SDK provides a TypeScript API for starting voice calls, controlling the microphone, listening for call events, and optionally receiving live transcript updates.
## Install the SDK
```bash theme={null}
npm install @phonely-ai/web
```
This guide describes version `0.0.8`.
## Keep authentication on your server
Your browser must not receive your Phonely API key. Instead:
1. The browser asks your application server to start a call.
2. Your server authenticates the user and confirms that they may access the requested agent.
3. Your server requests a short-lived web call session from Phonely using the API key.
4. Your server returns the session bundle to the browser.
5. The SDK uses that bundle to join the call.
Never include a Phonely API key in browser code, browser storage, URLs, screenshots, or client-visible logs.
Your server starts the short-lived session through Phonely:
```http theme={null}
POST https://db.phonely.ai/api/agents/{agent_id}/web-call-session
X-Authorization: YOUR_API_KEY
Content-Type: application/json
```
Send an empty JSON object, or include the optional call metadata:
```json theme={null}
{
"metadata": {}
}
```
The response contains the values the browser SDK needs:
```ts theme={null}
type WebCallStartResponse = {
callId: string;
webCallUrl: string;
meetingToken: string;
phonelyToken: string;
expiresAt?: string;
transcriptUrl?: string;
};
```
Return only this short-lived response to the browser. If Phonely provides an environment-specific API base URL for your account, use that URL instead.
## Configure the browser client
Set `webCallStartEndpoint` to a server route in your own application:
```ts theme={null}
import PhonelySDK, { PhonelyEvent } from "@phonely-ai/web";
const phonely = new PhonelySDK({
webCallStartEndpoint: "/api/web-call/start",
});
phonely.on(PhonelyEvent.CALL_JOINED, () => {
console.log("Call joined");
});
const callId = await phonely.call({ agentId: "YOUR_AGENT_ID" });
```
The SDK sends the following body to your route:
```ts theme={null}
{
agentId: string;
metadata?: Record;
}
```
Your route must return the short-lived session response produced by Phonely. If your application uses a custom authentication flow, provide `createWebCallStart` instead of `webCallStartEndpoint`.
## Pass runtime variables
If a flow uses runtime variables, pass their IDs and values through `metadata.callOverrides.liveVariables`:
```ts theme={null}
await phonely.call({
agentId: "YOUR_AGENT_ID",
metadata: {
callOverrides: {
liveVariables: [
{
uuid: "RUNTIME_VARIABLE_ID",
value: "VALUE_FOR_THIS_CALL",
},
],
},
},
});
```
The `uuid` must match the runtime variable ID configured in the flow.
## Use live transcripts
Enable transcript polling when the browser needs live caller and agent messages:
```ts theme={null}
const phonely = new PhonelySDK({
webCallStartEndpoint: "/api/web-call/start",
transcript: {
enabled: true,
autoStart: true,
includeRoles: ["user", "assistant"],
},
});
phonely.on(PhonelyEvent.TRANSCRIPT_MESSAGE, ({ message }) => {
console.log(message.content);
});
```
Transcript access uses the short-lived transcript URL and token returned for the call. `clearTranscript()` clears only the SDK's in-memory copy; it does not delete stored call data.
## Common methods
| Method | Purpose |
| -------------------------- | ---------------------------------------- |
| `call(options)` | Start a call and return its call ID |
| `endCall()` | End the active call |
| `setAudioEnabled(enabled)` | Mute or unmute local audio |
| `sendMessage(content)` | Send an application message to the call |
| `getParticipants()` | Read the current participants |
| `startTranscript()` | Start transcript polling |
| `stopTranscript()` | Stop transcript polling |
| `getTranscript()` | Read transcript messages held in memory |
| `clearTranscript()` | Clear transcript messages held in memory |
Use `on(event, handler)` and `off(event, handler)` to manage event listeners. The exported `PhonelyEvent` enum includes call lifecycle, participant, message, volume, speech, transcript, progress, and error events.
## End the call
```ts theme={null}
await phonely.endCall();
```
End the active call before starting another one with the same SDK instance.
# Account Settings
Source: https://docs.phonely.ai/billing-and-usage/account
Manage your profile, preferences, access details, and organization information.
Open **Settings > Account** to manage information associated with your user and the current organization.
## Profile
Update your profile photo, full name, and phone number. The email address associated with your account is shown but cannot be changed from this page.
## Preferences
| Setting | What it controls |
| ---------------------- | ----------------------------------------------------------------------------------------------------- |
| **Timezone** | The default timezone used for dates and time-based behavior in your account |
| **Marketing Emails** | Whether Phonely may send product and promotional emails |
| **Private Recordings** | Whether call recordings require authenticated access instead of being available through a direct link |
## Access
The Access section lets you reveal or copy your **API Key**, copy your **User ID** and **Organization ID**, and send a password-reset email.
Treat your API key as a secret. Do not put it in public code, screenshots, documentation, or Ask AI prompts.
## Organization information
The organization section shows information for the organization currently selected in Phonely. Available fields and whether you can edit them depend on your role. Users with viewer access do not see this section.
Organization changes save automatically after the values pass validation.
# Usage and Cost
Source: https://docs.phonely.ai/billing-and-usage/manage-agents-and-usage
Review and export organization usage across agents, channels, and time ranges.
Open **Settings > Usage & Cost** to analyze usage for the current organization.
## Review usage
Switch between **Usage** and **Cost** when cost estimates are available. The **Usage** view groups activity into channels such as AI minutes and transfer minutes. The **Cost** view groups charges into **AI Minutes** and a single **Telephony Cost** that combines transfer minutes, inbound and outbound telephony minutes, and phone-number charges; its details break out each billable metric's rate, quantity, and subtotal.
Use the controls above the chart to:
* include all agents or select specific agents;
* filter the usage types shown;
* group results by day, week, or month; and
* choose the current or previous billing cycle, a preset range, or a custom date range.
Rates, included quantities, and cost estimates appear only when the organization's billing data provides them. Treat displayed cost as an estimate unless your billing agreement states otherwise.
## Export the current view
Select **Export** to download the usage represented by the current date range, filters, grouping, and agent selection as CSV.
Use **Plan & Billing** for subscription status and invoices. Use **Notifications** to email recipients when monthly usage reaches selected thresholds.
# Plans and Billing
Source: https://docs.phonely.ai/billing-and-usage/plans-and-billing-history
Review your subscription, included minutes, payment information, and invoices.
Open **Settings > Plan & Billing** to review the subscription and billing records for the current organization.
## Current plan
The current-plan section shows your plan and subscription status, the minutes used in the current billing cycle, the remaining included minutes, and the renewal date when available.
Users with billing access can select:
* **Update Payment Info** to open the billing portal for the current subscription.
* **Manage Plan** to review the plans available to the organization.
The actions shown depend on your role and the organization's billing state.
## Billing history
Billing history lists recent invoices with their date, status, amount, and hosted invoice. Draft and voided invoices are not shown. You can open an individual invoice or export the available invoice usage reports as CSV.
Use [Usage and Cost](/billing-and-usage/manage-agents-and-usage) for current usage trends and a detailed breakdown by agent or usage type.
# Team Management and Roles
Source: https://docs.phonely.ai/billing-and-usage/teams
Invite teammates and assign the access they need in your Phonely organization.
Open **Settings > Team** to review members, invite teammates, and manage their roles. Team invitations require a plan that supports additional members.
## Invite a teammate
Enter the teammate's email address, choose a role, and select **Invite**. You can also create an invite link to share outside Phonely.
The roles available when inviting a teammate are **Admin**, **Member**, and **Viewer**.
## Choose a role
| Role | Access |
| --------------------- | -------------------------------------------------------------- |
| **Owner** | Full control, including billing and organization ownership |
| **Admin** | Full access to the organization |
| **Member** | Access to the organization but cannot manage members |
| **Viewer** | Read-only access to agents and call history |
| **Call history only** | Call history only; Ask AI, exports, and other pages are hidden |
Use the least-permissive role that still lets the teammate do their work.
## Manage members
Organization owners and admins can change member roles or remove members. The organization owner is identified separately and cannot be managed like a regular member.
Role changes affect what the user can see and change across the organization, not only on the Team page.
# Usage Notifications
Source: https://docs.phonely.ai/billing-and-usage/usage-notifications
Email selected recipients when organization usage reaches monthly thresholds.
Open **Settings > Notifications** to create and manage email alerts for the current organization's monthly usage.
## Create a notification
1. Select **Add Notification**.
2. Keep **Usage Alert** selected.
3. Choose one or more thresholds: **25%**, **50%**, **75%**, or **100%**.
4. Select **Next**, add at least one email recipient, and select **Create Notification**.
A notification can contain several thresholds and recipients. Each selected threshold represents a percentage of the organization's monthly usage limit.
## Manage notifications
Each notification card shows its thresholds and recipients. Use its actions to:
* review notification history;
* change the thresholds or recipients; or
* delete the notification.
Usage notifications provide visibility; they do not pause agents, stop calls, or change the organization's plan.
# API Request
Source: https://docs.phonely.ai/blocks/api-request
Send an HTTP request and use the response in later blocks.
Use **API Request** to read from or send data to an external service. The block can look up account information, create or update a record, or trigger another operation through an HTTP endpoint.
API Request supports `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`.
## Choose where it runs
Place the block at the stage when the request should run and after any variables it needs become available.
| Stage | Use it when |
| :------------ | :----------------------------------------------------------------------------- |
| **Pre-call** | The result is needed before the call starts |
| **Live call** | The result affects the active conversation or its routing |
| **Post-call** | The request should run after a call that reached the connected live-call block |
A request can use only variables available before it runs. For example, place a request that needs information collected during the conversation after the Talk or Collect block that collects it.
If the request is needed only after the call, place it in post-call so the caller does not wait for the external service.
## Configure the request
Select the HTTP method and enter the endpoint in **URL**. Use a publicly reachable HTTPS URL; local addresses and private network endpoints are blocked.
| Field | Purpose |
| :------------------- | :--------------------------------------------------------------------------- |
| **Headers** | Send values required by the endpoint, such as authentication or content type |
| **Query Parameters** | Add values to the URL as separate key-value pairs |
### Configure a request body
For `POST`, `PUT`, and `PATCH`, choose a body type:
| Body type | Use it when |
| :------------------------ | :----------------------------------- |
| **None** | The endpoint does not expect a body |
| **x-www-form-urlencoded** | The endpoint expects form fields |
| **JSON** | The endpoint expects structured JSON |
`GET` and `DELETE` do not include a request body.
For a JSON body, choose **Manual** to add typed fields or **Code** to edit the raw JSON. Manual fields support strings, numbers, booleans, arrays, objects, and nested values.
Follow the endpoint's documentation for its required field names, formats, and authentication.
### Import a cURL command
Select **Import from cURL** beside the URL to populate the supported method, URL, headers, query parameters, and body from a cURL command.
Import fills only the fields that the editor supports. Review the result, replace sample values with fixed values or variables, and confirm that the request matches the API documentation before testing.
## Use variables in the request
Focus a URL, header, query parameter, form, or JSON field, then select a value from **Available Variables**. The list includes only variables available before the block runs.
Variables inserted into the URL, headers, query parameters, and form fields are sent as text. In a JSON body, they can retain a number, boolean, object, or array type.
Use a [Custom Variable](/flow-editor/variables#use-custom-variables) for a fixed value reused across requests, such as an API key or account ID. Keep credentials out of examples, screenshots, and Ask AI prompts.
## Test and create response variables
Run **Send test request** before using the response in another block. The test sends a real request to the configured endpoint.
1. Enter safe sample values for the variables used by the request.
2. For a JSON-body variable, choose the same data type it will have when the flow runs.
3. Select **Show request** to inspect the resolved URL, headers, parameters, and body.
4. Send the request and inspect the response.
After a successful test, choose which parts of the response later blocks can use. The result panel shows the response as an expandable tree beside the complete raw JSON, with each value's type.
For example:
```json theme={null}
{
"customer": {
"id": "cus_123",
"active": true
}
}
```
You can select `response` for the complete object, or individual values such as `customer.id` and `customer.active`. Selecting a parent object includes the values nested inside it. Search by path or value when a response is large.
The first successful test on a new block selects the complete response for you. After that, your selection is what the block keeps: only what you select becomes a variable under the block's name, available to later blocks from **Available Variables**.
If the response structure changes, test the request again and review your selection along with any downstream fields that reference its variables. Reselecting outputs keeps existing references working, and a failed retest leaves your last successful selection in place.
Use a JSON response when later blocks need individual response fields. At runtime, a non-JSON response is stored as text in `response`.
A block test can create, update, send, charge, or delete real data. Use a test endpoint or records that are safe to change.
## Configure runtime behavior
Expand **Advanced Settings** to configure timeout, retries, and other options available for the block's stage.
### Timeout duration
**Timeout Duration** controls how long Phonely waits for the endpoint:
* Pre-call: 1 to 5 seconds
* Live call and post-call: 1 to 30 seconds
Keep live-call requests short. If the request regularly needs more time and can run after the call, move it to post-call.
### Retry on failure
Enable **Retry on Failure** when another attempt may succeed, then set **Max Attempts** from 1 to 10.
Retries can repeat the endpoint's side effects. Before enabling retry for a request that creates a booking, payment, ticket, message, or other record, confirm that the endpoint can safely prevent duplicates.
### Other advanced settings
Pre-call and live-call API Request blocks also support interim messages, error routes, and call outcome tagging. See [Common Block Settings](/blocks/common-settings) for how these options affect the caller, connections, and reporting.
Post-call API Request blocks provide timeout and retry settings, but not interim messages, error routes, or call outcome tagging.
## Verify the complete behavior
After the block test succeeds:
1. Confirm that request variables resolve to the intended values.
2. Test each flow route that can reach the block and confirm a successful response.
3. If **Error Handling** is enabled, test a controlled failure and its recovery route.
4. Confirm that downstream blocks receive the expected response fields.
5. Complete an end-to-end flow test before relying on the request.
During a Web Chat test, expand API Request in the action trace. After a phone call, open **Call Details**, select **Blocks**, and expand API Request. Review its status, request, response, and stored variables.
## Troubleshooting
Use a valid, publicly reachable HTTPS URL. For a block test, enter a sample value for every variable used by the request, then inspect **Show request** for an unresolved or malformed value.
Compare the resolved headers, parameters, and body with the endpoint's current documentation. Confirm that credentials are valid and that each field uses the required name, format, and data type.
API Request treats only `2xx` HTTP status codes as successful. Check the returned status code. If the failure is expected and **Error Handling** is available and enabled, connect the **Error** route; otherwise correct the request or endpoint behavior.
Run a successful test with a representative JSON response. If the response shape changed, test again and replace downstream references that no longer exist.
In the manual JSON body, choose the intended field type. For variables used in the JSON body test, select a matching test type. Values outside the JSON body are sent as text.
Reduce **Timeout Duration**, use a concise interim message, or move the request to post-call when it is needed only after the call.
Disable **Retry on Failure** until the endpoint can safely reject or deduplicate repeated requests. Retest with non-production data.
# Common Block Settings
Source: https://docs.phonely.ai/blocks/common-settings
Configure caller feedback, failure routes, and call outcome reporting on supported blocks.
Select a block and expand **Advanced Settings** to see any shared options it supports. These supplement the block's main configuration by controlling what the caller hears while it runs, how action failures are routed, or which outcome is recorded for reporting.
Available settings vary by block and execution stage.
| Setting | What it changes |
| :------------------------ | :----------------------------------------------------------------- |
| **Interim Message** | Tells the caller that an action is in progress |
| **Enable Error Handling** | Adds separate **Success** and **Error** routes to supported blocks |
| **Call Outcome Tagging** | Records an outcome for reporting when the call reaches the block |
## Interim messages
Use an **Interim Message** when a block may leave the caller waiting in silence. It tells the caller that Phonely is still working and does not affect routing.
Choose how the message is created:
| Mode | Behavior |
| :------------- | :------------------------------------------------------ |
| **Fixed** | Uses the exact message you enter |
| **Promptable** | Uses your instructions to generate a contextual message |
Keep the message short and neutral. It should acknowledge the wait without claiming that the action has already succeeded. For example:
> One moment while I check that for you.
Enable **Post Interim Message Delay** to pause briefly after the message before the flow continues. Set a delay of up to 60 seconds.
## Error handling
Enable **Error Handling** when the flow needs separate paths for success and failure. The block replaces its single continuation with two routes:
* **Success** runs when the action completes successfully.
* **Error** runs when the action fails.
Connect **Error** to a useful recovery path, such as trying another method, collecting details for follow-up, or explaining that the action could not be completed.
Switching this setting changes the block's source handles. Connections that no longer match are removed, so reconnect the routes shown on the block and review the [Flow Checklist](/workflow-checklist).
When **Error Handling** is disabled, the block uses one continuation.
## Call outcome tagging
Use **Call Outcome Tagging** when reaching a block represents a result worth tracking, such as `Appointment booked` or `Needs follow-up`. Choose an existing outcome or enter a new one.
Outcome tagging affects reporting, not routing. Use exit conditions, Filter cases, and connections to control what happens next.
If a call reaches multiple tagged blocks, the last tagged block determines its outcome. Tag stable business results rather than routine progress through the flow.
Use [**Focus blocks by call outcome**](/key-concepts/flow-canvas-controls#focus-blocks-by-call-outcome) on the canvas to highlight every block that uses a selected outcome in the current flow.
## Troubleshooting
Open **Advanced Settings** and confirm that **Interim Message** is enabled. For **Fixed**, enter the message to play. For **Promptable**, provide instructions for the message to generate. Then confirm that the call reaches the block.
Open **Advanced Settings** and enable **Error Handling**. The block updates automatically to show **Success** and **Error** source handles. Connect each handle to the appropriate next block.
Use [**Outcome Focus**](/key-concepts/flow-canvas-controls#focus-blocks-by-call-outcome) to find the configured blocks, then review the call path to see which ones ran. The last tagged block reached determines the outcome.
# Campaign
Source: https://docs.phonely.ai/blocks/communication-blocks/campaign
Queue an outbound campaign call after a call.
Use **Campaign** to queue an outbound call in a selected campaign after a call that reached the connected live-call block ends.
Use [Redial](/blocks/communication-blocks/redial) instead when a campaign call should schedule another attempt.
## Select a campaign
Choose the campaign that should receive the new call. Phonely then displays its configured **Campaign Fields**.
Enter a fixed value or select an available variable for each field the outbound call needs.
Provide a valid value for the destination flow's phone-number field. The block sends only the values configured under **Campaign Fields**.
The selected campaign must be **Active** or **Paused**, and its outbound flow must be turned on. Campaign queues the call but does not change those settings.
## Verify Campaign
Campaign does not have a block-level test. Use a phone number you control, then complete a test call that reaches the live-call block connected to Campaign.
Confirm:
1. A new call appears in the selected campaign.
2. Its phone number and other fields contain the expected values.
3. The campaign places the outbound call.
Testing this block can queue and place a real outbound call.
## Troubleshooting
Confirm that the completed call reached the live-call block connected to Campaign and that the selected campaign still exists.
Confirm that the campaign is **Active** or **Paused** and that its outbound flow is turned on. Check that **Campaign Fields** provide a valid phone number and any other input required by the outbound flow.
Review the values under **Campaign Fields** and confirm that their variables are available at the connected live-call block. If the campaign's fields changed, select the campaign again and reconfigure the displayed fields.
# Email & SMS Notification
Source: https://docs.phonely.ai/blocks/communication-blocks/email-sms-notification
Send a call summary by email, SMS, or both.
Use **Email & SMS Notification** to send a Phonely-generated report about a completed call. It runs after a call reaches the live-call block to which it is connected.
Use [Send Email](/blocks/communication-blocks/send-email) or [Send SMS](/blocks/communication-blocks/send-sms) when you need to control the message content.
## Configure recipients
Add recipients to either section:
| Section | What recipients receive |
| :------------------- | :------------------------------------------------------------------------------- |
| **Email Recipients** | A call report with the summary, call details, transcript, and a link to the call |
| **Phone Numbers** | An SMS containing the caller number, call summary, and a link to the call |
Enter fixed recipients or select values from **Available Variables**. Add as many email addresses and phone numbers as needed, and leave a section empty when you do not want to use that channel.
Each email variable must resolve to a valid email address. Each phone number variable must resolve to a valid number with its country code, such as `+12125551234`.
You configure only the recipients. Phonely controls the notification content and selects the sending address or phone number automatically.
## Verify the notifications
This block does not have a block-level test. Use recipients you control, then complete a test call that reaches the connected live-call block.
Confirm that each configured channel receives the notification and that variable recipients resolve to the intended addresses or numbers.
## Troubleshooting
Confirm that the call reached the live-call block connected to the notification. Then check that email addresses are valid, phone numbers include their country code, and recipient variables stored the expected values. For missing email, also check the recipient's spam or junk folder.
Email & SMS Notification uses Phonely's automatic call report and summary. Use [Send Email](/blocks/communication-blocks/send-email) or [Send SMS](/blocks/communication-blocks/send-sms) when you need to write the message yourself.
# Redial
Source: https://docs.phonely.ai/blocks/communication-blocks/redial
Schedule another campaign call after a delay.
Use **Redial** after an outbound campaign call to schedule another attempt in the same campaign or a different one. Redial requires campaign call data and does not schedule calls that originated outside a campaign.
## Configure the attempts
Add one or more attempts in the order Phonely should use them. For the same campaign and phone number, Phonely selects the next attempt based on how many calls the campaign has already made. When no configured attempt remains, the block stops scheduling calls.
For each attempt, choose an action and delay:
| Action | What it schedules |
| :------------------- | :------------------------------------------------------------ |
| **Retry After** | Another call in the current campaign with its original values |
| **Move to Campaign** | A call in a selected campaign with the configured values |
**Retry After** keeps the sequence in the current campaign. After **Move to Campaign**, the destination campaign's flow controls any later follow-up.
Set **Delay Duration** in minutes, hours, or days. Enter `0` to schedule the attempt immediately. You can also select an available variable that resolves to a non-negative whole number.
## Move to another campaign
Select the destination campaign, then enter a fixed value or select an available variable for each displayed **Campaign Field**.
Make sure the destination flow's phone-number field receives a valid number. Configure any other values that its outbound call needs.
## Override the voicemail message
By default, a redial attempt uses the voicemail message configured in the outbound flow's **Make Call** block.
Enable **Override Voicemail Message** on an attempt when it needs a different message. The override can include variables available at the Redial block.
## Verify Redial
Redial does not have a block-level test. Use a phone number you control, then complete a campaign call that reaches the live-call block connected to Redial.
Configure a short delay and confirm:
1. A new call appears in the campaign with the **Redial Scheduled** status.
2. The campaign places the call after the configured delay.
3. **Retry After** preserves the original values, or **Move to Campaign** sends the intended fields to the selected campaign.
4. If configured, the voicemail override plays when the call reaches voicemail.
Testing Redial can schedule and place real outbound calls.
## Troubleshooting
Confirm that the completed call originated from a campaign and reached the live-call block connected to Redial. Check that the block contains at least one unused attempt and that the selected campaign for **Move to Campaign** still exists.
Confirm that the campaign for the attempt is **Active** or **Paused** and that its outbound flow is turned on. For **Move to Campaign**, check that the configured fields provide the phone number and other values required by the destination flow.
Phonely selects an attempt according to how many calls that campaign has already made to the phone number. Review the campaign's call history and the order of the attempts. For **Move to Campaign**, also check the fixed or variable values entered for the destination campaign.
Confirm that **Override Voicemail Message** is enabled for the attempt and that its message and variables resolve correctly. The override plays only when the call reaches voicemail. When the setting is off, the attempt uses the voicemail message from **Make Call**.
# Send Email
Source: https://docs.phonely.ai/blocks/communication-blocks/send-email
Send an email to one or more recipients.
Use **Send Email** to send an email during or after a call. Enter recipient addresses or select them from **Available Variables**.
Use [Email & SMS Notification](/blocks/communication-blocks/email-sms-notification) when you want to send the conversation summary automatically after a call. Use [Gmail](/integrations/gmail) or [Microsoft Outlook](/integrations/microsoft-outlook) when the email should come from a connected provider account.
## Configure the email
| Field | Configuration |
| :---------- | :------------------------------------------------------------- |
| **To** | Add one or more recipients, using fixed addresses or variables |
| **Subject** | Write the subject and insert any values it should include |
| **Body** | Write the message and insert any values it should include |
**To**, **Subject**, and **Body** are required. These fields, along with **From Name**, support variables. Each recipient variable must resolve to a valid email address before the block runs.
Under **Advanced Settings**:
* **Body Type** controls whether the body is sent as **Plain Text** or **HTML**. Select HTML only when the body contains HTML markup.
* **From Name** changes the sender name shown in the recipient's inbox. If left blank, it defaults to **Phonely**.
Send Email uses `no-reply@phonely.ai` as the sender address. **From Name** does not change that address.
The block can use only variables available before it runs. For other supported options under **Advanced Settings**, see [Common Block Settings](/blocks/common-settings).
## Test the email
Send Email includes a block-level test that previews the resolved message and sends a real email.
1. Complete the **Configure** step and select **Continue**.
2. Enter sample values for any variables used by the block.
3. Review the resolved recipients, sender name, subject, and body in **Email Preview**.
4. Confirm that the recipients are addresses you control, then select **Test**.
A successful test confirms that Phonely accepted the request to send the email. Confirm that the message arrived and that its content and formatting are correct.
## Troubleshooting
Confirm that every fixed address and recipient variable resolves to a valid email address. Invalid recipients are omitted; the block fails if none of its recipients are valid. Check the recipient's spam or junk folder as well.
Confirm that the variable is available before the Send Email block runs and that its source block stored the expected value. In the block-level test, provide a representative sample value and review **Email Preview** before sending.
Set **Body Type** to **HTML** and review the markup for invalid or incomplete tags. Use **Plain Text** when the body does not require HTML formatting.
Send Email always uses `no-reply@phonely.ai`. **From Name** changes only the display name. Use [Gmail](/integrations/gmail) or [Microsoft Outlook](/integrations/microsoft-outlook) when the message must come from a connected email account.
# Send SMS
Source: https://docs.phonely.ai/blocks/communication-blocks/send-sms
Send a text message to a fixed phone number or one stored in a variable.
Use **Send SMS** to send a text message when the flow reaches the block. Enter a fixed recipient or select a phone number from **Available Variables**. The block can run at the pre-call, live-call, or post-call stage.
Use [Email & SMS Notification](/blocks/communication-blocks/email-sms-notification) instead when you want to send the conversation summary automatically after a call.
## Configure the recipient and message
| Field | Configuration |
| :--------------- | :----------------------------------------------------------------- |
| **Phone Number** | Enter a recipient or select a phone number available from the flow |
| **Content** | Write the message and insert any values it should include |
Both fields are required and support variables. For a fixed recipient, use international format, such as `+12125551234`. When using a variable, make sure its value includes the country code.
Keep the content concise. For example:
> Your appointment is confirmed for `appointment_time`.
Select `appointment_time` from **Available Variables** rather than typing the variable name as plain text.
Phonely selects the sending number automatically for the agent. It cannot be changed in the Send SMS block.
The block can use only variables available before it runs. For supported options under **Advanced Settings**, see [Common Block Settings](/blocks/common-settings).
## Verify delivery
Flow tests execute the block and can send a real SMS. Use a phone number you control and confirm that the recipient, fixed text, and variable values resolve correctly.
During a Web Chat test, expand **Send a text message** in the action trace. After a phone call, open **Call Details**, select **Blocks**, and expand **Send a text message**. Review the recipient, message content, and delivery status.
## Troubleshooting
Check the value selected in **Phone Number** and the value stored for that variable during the call. If the system caller number is not the intended recipient, collect or select the correct phone number earlier in the flow.
Confirm that **Phone Number** resolves to a valid number with its country code, then review the delivery status in **Call Details**. A message can be accepted for sending and later fail during delivery.
Confirm that the selected variable is available before the Send SMS block runs and that its source block stored the expected value. Test the route that produces that value again.
# Transfer Call
Source: https://docs.phonely.ai/blocks/communication-blocks/transfer-call
Transfer an active call to one or more phone destinations.
Use **Transfer Call** to send an active call to an external phone destination. Choose a cold transfer for a direct handoff or a warm transfer when Phonely should reach the recipient first and manage the connection.
Use [Transfer Flow](/blocks/flow-control-and-routing/transfer-flow) to continue the call in another inbound flow.
## Choose a transfer type
| Transfer type | What happens | Best for |
| :---------------- | :------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------- |
| **Cold Transfer** | Phonely plays the pre-transfer message, then sends the caller directly to the destination | Shared lines or destinations that do not need an introduction |
| **Warm Transfer** | Phonely calls the destination separately and manages the connection before handing off the caller | Handoffs that need an introduction, permission, or recovery route |
A cold transfer ends the Phonely flow when the handoff begins. A warm transfer can return through a recovery route when the connection is unsuccessful or a configured detection rule is met.
## Configure destinations
Add at least one **Transfer Destination**:
1. Enter the **Phone Number**, including its country code.
2. Set the **Pre Transfer Message** the caller hears before the handoff.
3. Add destinations when Phonely needs to choose between people or teams.
For message fields, choose **Fixed** to play the text you enter or **Promptable** to generate a message from your instructions and the conversation context.
With multiple destinations, enter a distinct **Transition Condition** for each one. Phonely compares the conversation with these conditions and may ask a clarifying question before selecting a destination.
| Destination | Transition condition |
| :---------- | :---------------------------------------------------------- |
| **Sales** | The caller wants pricing, a quote, or to purchase a service |
| **Support** | The caller needs help with an existing product or service |
Keep the conditions specific and distinguishable. Phone numbers and messages can use variables from earlier in the flow.
For a warm transfer, **Enable Failover** for a destination to try its backup numbers in order when the primary number cannot be connected.
## Configure a warm transfer
Warm transfer settings control what the caller experiences while Phonely reaches the destination and what happens before both parties are connected.
### While waiting for connection
Choose the caller's experience while Phonely calls the destination:
| Option | Caller experience |
| :---------------------- | :--------------------------------------------------------------------- |
| **On Hold Chat** | The agent continues the conversation using the **On Hold Chat Prompt** |
| **On Hold Music** | Hold music plays while the caller waits |
| **Both (Chat + Music)** | The agent can continue the conversation while hold music plays |
Use **Reminder Message** and **Reminder Frequency** to update the caller while the transfer is in progress. Keep reminders short and do not suggest that the recipient has answered.
### When connection is established
Warm transfer messages play at different points in the connection:
| Setting | Who hears it | When it plays |
| :---------------------------------------- | :----------- | :----------------------------------------------------------- |
| **Message to Caller (Inbound)** | Caller | After a person answers, before the connection |
| **Message to Recipient (Outbound)** | Recipient | After a person answers, before the connection |
| **Post Transfer Message** | Both parties | After they are connected, before the agent leaves |
| **Transfer Failed Message for Recipient** | Recipient | If the caller disconnects before the connection is completed |
Enable **Ask Outbound Leg for Permission** when the recipient must accept the transfer. Make **Message to Recipient (Outbound)** a clear yes-or-no question. If the recipient declines, the attempt fails and Phonely tries any configured failover numbers.
**Fast Transfer (Beta)** skips the messages to the caller and recipient and does not wait for recipient permission. After a person answers, Phonely connects both parties and plays only the **Post Transfer Message** before leaving.
### Adjust detection and attempt duration
**Detection Timeout** controls how much audio Phonely uses to determine whether a person, IVR system, or voicemail answered. A shorter value responds faster; a longer value provides more audio for classification.
In **Advanced Settings**, **Warm Transfer Attempt Duration** sets the maximum time Phonely can spend trying to complete the warm transfer.
## Configure warm transfer routing
The **Routing** step controls what happens when Phonely reaches an automated system instead of a person.
| Setting | Behavior | Flow route |
| :------------------------------ | :--------------------------------------------------- | :-------------------------- |
| **IVR Detection: None** | Applies no special IVR behavior | No IVR-specific route |
| **Transfer on IVR Detection** | Connects the caller to the detected automated system | Transfer completes |
| **Exit on IVR Detection** | Stops the attempt when an IVR is detected | **IVR Detected** |
| **Voicemail Detection: None** | Applies no special voicemail behavior | No voicemail-specific route |
| **Exit on Voicemail Detection** | Stops the attempt when voicemail is detected | **Voicemail Detected** |
Use **IVR Detection Prompt** and **Voicemail Detection Prompt** to give Phonely additional cues for classifying what answered. These prompts do not tell Phonely how to navigate an IVR menu.
A warm transfer uses **Transfer Failed** after an attempt cannot be completed and any configured failover numbers are exhausted. Connect every route shown on the block to a suitable fallback.
The block makes **Warm Transfer Attempt Duration** available to recovery routes for reporting or later decisions.
For reporting, see [Call Outcome Tagging](/blocks/common-settings#call-outcome-tagging). **Human Answered Call Outcome Tagging** can also apply when a person answers the destination.
## Test the transfer
Use phone numbers you control before relying on the block for live calls:
1. Confirm that each destination number and pre-transfer message are correct.
2. For multiple destinations, test a clear request for each condition and an ambiguous request that may require clarification.
3. For a warm transfer, test a human answer and every configured recovery route.
4. Confirm that the caller and recipient hear the intended messages at the right time.
5. Complete a real inbound or outbound call to verify the full handoff.
When testing failover, make the primary destination unavailable and confirm that the backup numbers are attempted in order.
## Troubleshooting
Compare the destinations' **Transition Conditions**. Make each condition specific and distinguishable, then test clear and ambiguous requests again.
Turn off **Fast Transfer**, enable **Ask Outbound Leg for Permission**, and make **Message to Recipient (Outbound)** a clear yes-or-no question.
Confirm that the corresponding IVR or voicemail option is set to **Exit**, then connect the named route shown on the block. **Transfer on IVR Detection** completes the transfer and does not use **IVR Detected**.
Confirm that the block uses **Warm Transfer** and that the destination has a valid failover number. Failover runs when the primary transfer fails; an IVR or voicemail set to **Exit** follows its named recovery route instead.
Review **Warm Transfer Attempt Duration** and the destination's availability. Increase the duration only when recipients reasonably need more time to answer.
Check which message field is intended for that participant and point in the connection sequence. Then test with separate caller and recipient phones so you can verify both sides.
# Collect
Source: https://docs.phonely.ai/blocks/conversation-blocks/collect
Ask for a defined set of information and use the caller's answers in later blocks.
Choose **Collect** when the agent needs a defined set of information, such as a caller's name, contact details, or appointment preferences. It asks for the information one item at a time and stores the answers as variables for later blocks.
Each **Question** guides what the agent should ask, but it is not a fixed script. The agent can phrase or rephrase the question naturally. Choose [Talk](/blocks/flow-blocks/talk) when the task needs a more open-ended conversation or different routes based on its outcome.
## Start the block
Configure the questions directly, or expand the **Generate with AI** strip at the top of the panel, describe what you want, and start a focused Ask AI task that proposes changes to this block alone. For example:
> Gather the caller's name, email address, phone number, and reason for calling.
Review the proposal on the canvas and apply it, then refine the block by asking again. The instruction is not saved onto the block, so the box starts empty each time and the request lives in the Ask AI conversation. Generation is offered only on an editable draft, not in version previews, comparisons, or to viewers.
## Configure the questions
Add one question for each value the block should collect. Collect requires at least one question, and every variable name must be unique within the block.
| Field | Purpose |
| :---------------- | :--------------------------------------------------------------------- |
| **Variable Name** | Name shown in **Available Variables**; must be unique within the block |
| **Type** | Expected format of the answer |
| **Question** | Question to ask; the agent may phrase it naturally during the call |
| **Required** | Collect the answer before leaving the block |
| **Confirm** | Ask the caller to confirm a required answer |
| **Spell Back** | Spell a confirmed answer character by character |
**Confirm** is available after **Required** is enabled, and **Spell Back** is available after **Confirm** is enabled.
Choose the type that matches the expected answer. See [Variables](/flow-editor/variables) for available types, formats, and downstream availability.
**Zipcode** and **Phone** expect the format of the agent's country, which Phonely derives from the timezone in **Settings**. A US timezone collects a 5-digit ZIP code, while an Australian timezone collects a 4-digit postcode. See [Timezone sets the expected country format](/flow-editor/variables#timezone-sets-the-expected-country-format).
### Completion and routing
Collect asks for missing information in a conversational style. It can move to the next block after all required answers have been collected and any enabled confirmations are complete.
Enable **Required** for every answer the flow depends on. A question without **Required** does not prevent Collect from continuing.
Collect has one live-call continuation and does not branch by answer. To route using a collected value, connect Collect to a [Filter](/blocks/flow-control-and-routing/filter) and create the cases there.
## Example: Collect caller details
| Variable | Type | Question |
| :------------------- | :---- | :-------------------------------- |
| `caller_name` | Name | What is your name? |
| `caller_email` | Email | What email address should we use? |
| `reason_for_calling` | Text | What can we help you with today? |
Enable **Required** for each answer the flow cannot continue without. For information that is easy to mishear, enable **Confirm** and, when useful, **Spell Back**.
Later blocks on the continuation route can use these answers as variables.
## Test Collect
Try complete, unclear, corrected, and missing answers. Confirm that Collect:
* requests missing information naturally, one question at a time;
* does not continue until every required answer is collected and any configured confirmation is complete;
* updates a stored value when the caller corrects it;
* spells back answers when configured; and
* makes the collected values available to later blocks.
Use **Web Call** to hear questions, confirmations, and spelled-back answers.
For an unexpected result, open **Call Details**, select **Blocks**, and expand Collect to review its conversation turns and stored variables.
## Troubleshooting
Enable **Required** for every answer the flow must collect before continuing. Leave it off only when later blocks can run without that value.
Check which required answer is still missing or waiting for confirmation. Make the corresponding **Question** clearer and confirm that its **Type** matches the expected response.
Collect asks questions conversationally and may rephrase them. Write the **Question** as a clear request for one value rather than relying on exact wording.
Check the agent's timezone in **Settings**. Phonely uses it to decide which country's format to ask for and validate against, so a timezone set to the wrong country makes the agent request a postcode your callers do not have. For a format the country defaults do not cover, set the question's **Type** to **Regex** or **Custom**.
Open **Call Details** and confirm that Collect stored the value. If later blocks always need it, enable **Required**. Otherwise, make sure those blocks can run without it.
# Code
Source: https://docs.phonely.ai/blocks/data-and-automation-blocks/code
Process data with Python and use the output in later blocks.
Use **Code** to transform, compare, or calculate data with Python. The block receives values from the flow and returns output that later blocks can use.
Use [Filter](/blocks/flow-control-and-routing/filter) for straightforward routing conditions. Use Code when the flow needs a calculation, data transformation, or business rule that is clearer to express in Python.
## Choose where it runs
Place the block where its inputs are available and where its output will be used.
| Stage | Use it when |
| :------------ | :------------------------------------------------------------------- |
| **Pre-call** | The output is needed before the call starts |
| **Live call** | The output affects the active conversation or its routing |
| **Post-call** | Process data after a call that reached the connected live-call block |
Inputs can use only variables available before Code runs. If the code needs information collected during the conversation, place it after the block that collects it.
If the output is needed only after the call, use post-call so the caller does not wait for the processing.
## Configure inputs
Under **Input Variables**, create a key for each value the function needs. Set its value using fixed text, a variable available at the block, or both.
Use **Manual** to configure inputs as key-value rows, or switch to **Code** to edit the same inputs as a JSON object. Phonely converts the current inputs when you switch views. Name every populated input before switching to Code, and fix invalid JSON before switching back to Manual.
| Field | Purpose |
| :---------------- | :----------------------------------------------- |
| **Variable name** | The key used to access the value in `input_dict` |
| **Set variables** | The value passed to that key |
Use short, unique names such as `subtotal`, `customer_tier`, or `appointment_date`. Lowercase names with underscores are easiest to read in the code.
When an input contains only a selected variable, it retains that variable's type, including text, number, boolean, array, or object. An empty resolved value is passed to the function as `None`. Handle missing or empty values in the code instead of assuming every input is present.
## Generate code with AI
Expand the **Generate with AI** strip at the top of the panel, describe what the code should do, and start a focused Ask AI task that proposes changes to this block alone. Ask AI can write the Python function, map its inputs, and define its expected outputs. Review the proposal on the canvas and apply it, then refine the block by asking again. Generation is offered only on an editable draft, not in version previews, comparisons, or to viewers.
Review the generated inputs, code, and outputs before continuing. You still need to validate the code and run a successful block test before its output variables can be used reliably by later blocks.
## Write the Python function
The editor provides the required function structure. Keep the function name and parameter unchanged, and return a dictionary:
```python theme={null}
def function(input_dict: dict) -> dict:
output_dict = {}
return output_dict
```
Read each configured input by its key and return the values that later blocks need. For example:
```python theme={null}
def function(input_dict: dict) -> dict:
subtotal = float(input_dict.get("subtotal") or 0)
tax_rate = float(input_dict.get("tax_rate") or 0)
total = round(subtotal * (1 + tax_rate), 2)
return {
"total": total
}
```
The keys in the returned dictionary define the block's outputs. A successful block test makes them available to later blocks. Keep output names stable once downstream blocks use them.
### Use supported libraries
Code runs in a restricted environment. You can import `math`, `datetime`, `json`, `random`, and `time`. Other libraries and dynamic imports with `__import__` are not supported.
Use [API Request](/blocks/api-request) or an integration block to communicate with an external service. Use Code to process the data those blocks return.
## Validate the code
Select **Validate** after configuring the inputs and writing the function. Validation checks the Python syntax, the required `function(input_dict)` signature, and whether its imports are supported.
Validation does not run the function or confirm its results. Continue to the Test step to verify the logic with sample inputs.
Editing the Python code clears its previous validation. Validate again before testing or publishing the flow.
## Test and create output variables
Run the block test before using its output in another block.
1. Enter representative sample values for each input.
2. Select **Test** and inspect `output`, `stdout`, and `stderr`.
3. Test any missing, empty, boundary, or unexpected values the flow may provide.
After a successful test, choose which parts of the returned dictionary later blocks can use. The result panel shows the output as an expandable tree beside the complete raw JSON, with each value's type.
For the example above, you can select the entire dictionary as `output` or select `total` on its own. Selecting a parent includes the values nested inside it, and you can search by path or value when the output is large.
The first successful test on a new block selects the complete output for you. After that, only what you select becomes a variable under the block's name, available to later blocks from **Available Variables**.
If the returned structure changes, test the block again and review your selection along with any downstream fields that use its variables. Reselecting outputs keeps existing references working, and a failed retest leaves your last successful selection in place.
`print()` output appears in `stdout` for debugging. It does not create a flow variable. Return a value from the function to use it in later blocks.
## Configure shared settings
Pre-call and live-call Code blocks support interim messages, Error Handling, and Call Outcome Tagging. See [Common Block Settings](/blocks/common-settings) for how these options affect the caller, connections, and reporting.
Post-call Code blocks do not provide these settings.
## Verify the flow behavior
After the block test succeeds:
1. Test each route that can reach the block using representative inputs.
2. If **Error Handling** is enabled, trigger a controlled error and confirm the **Error** route runs.
3. Confirm that downstream blocks receive the intended output values.
4. Complete an end-to-end flow test before using the flow for live calls.
During a Web Chat test, expand Code in the action trace. After a phone call, open **Call Details**, select **Blocks**, and expand Code. Review its inputs, output, stdout, stderr, and execution time.
## Troubleshooting
Read the validation message for the affected line or rule. Confirm that the code is valid Python, defines `function` with exactly one parameter named `input_dict`, and uses only permitted imports.
Validation checks the code structure, not every input or execution path. Review `stderr` and `stdout`, reproduce the failure with representative test values, and handle the affected type, missing value, or operation in the function.
Confirm that the input name matches the key read from `input_dict` and that **Set variables** contains the intended fixed value or an available variable. Test with the same data type the flow will provide, and handle missing or empty values in the function.
Return a dictionary containing that key, then run a successful test. If the output structure changed, test again and replace downstream references that no longer exist.
# Send Call Data
Source: https://docs.phonely.ai/blocks/data-and-automation-blocks/send-call-data
Send call data to an HTTP endpoint after a call.
Use **Send Call Data** to send data from a completed call to a webhook, CRM, analytics service, or automation endpoint.
Send Call Data runs only in post-call. It sends a `POST` request with a JSON body after a call reaches the live-call block to which it is connected.
Use [API Request](/blocks/api-request) in post-call when you need another HTTP method, custom headers or authentication, retries, or response variables.
## Configure the endpoint
Enter a publicly reachable HTTPS endpoint in **Webhook URL**. The endpoint must accept `POST` requests with a JSON body.
Send Call Data does not provide custom headers or authentication. If the endpoint requires them, use API Request instead.
## Choose the payload
Choose whether Phonely sends the full call payload or a custom JSON body:
| Mode | Use it when |
| :---------------------- | :------------------------------------------------------------------------------------ |
| **Send full call data** | The destination needs the available call record for storage, reporting, or automation |
| **Custom call data** | The destination needs only selected fields or expects a specific JSON structure |
The full payload can include phone numbers, transcripts and summaries, call timing and outcome, extracted insights, links, action history, and stored variables. Some fields may be empty when the corresponding data was not available for the call.
| Field | Content |
| :------------------------ | :----------------------------------------------- |
| `businessPhoneNumber` | The agent's phone number for the call |
| `customerPhoneNumber` | The customer's phone number |
| `agentId` | The ID of the agent that handled the call |
| `provider` | The voice provider used for the call |
| `agentName` | The agent's display name |
| `transcript` | The conversation messages |
| `transcriptText` | A plain-text version of the transcript |
| `summary` | A brief call summary |
| `longSummary` | A detailed call summary |
| `ai_success` | Whether the AI successfully handled the call |
| `sentiment` | The detected conversation sentiment |
| `topic` | The main topics discussed |
| `purpose` | The detected reason for the call |
| `keyPoints` | Important points extracted from the conversation |
| `mentionedDate` | A date mentioned during the call |
| `mentionedTime` | A time mentioned during the call |
| `mentionedEmail` | An email address mentioned during the call |
| `callerName` | The caller's name, when captured |
| `unansweredQuestions` | Questions that were not answered |
| `followUp` | Whether follow-up is needed |
| `followUpReason` | Why follow-up is needed |
| `actionItems` | Actions identified from the call |
| `callDirection` | Whether the call was inbound or outbound |
| `recordingUrl` | A link to the call recording, when available |
| `callStarted` | When the call started |
| `callEnded` | When the call ended |
| `callDate` | The call date in the agent's timezone |
| `dashboardUrl` | A link to the call in Phonely |
| `callId` | The call's identifier |
| `callDuration` | The call duration in seconds |
| `total_transfer_duration` | The total transfer hold duration in seconds |
| `endedReason` | Why the call ended |
| `callOutcome` | The call outcome |
| `lastBlock` | The last flow block reached during the call |
| `callTime` | The original call-start timestamp |
| `actionList` | Actions performed during the call |
| `workflowTriggered` | Whether a flow was triggered |
| `callTransferred` | Whether the call was transferred |
| `abTestId` | The A/B test ID, when applicable |
| `abTestName` | The A/B test name, when applicable |
| `abTestType` | The A/B test variant, when applicable |
| `storedVariables` | Variables stored while the call ran |
Full call data can contain personal information, conversation content, recording links, and stored variables. Send it only to a trusted endpoint authorized to receive this data.
### Configure a custom body
Turn off **Send full call data**, then choose how to build the JSON body:
| Mode | Use it when |
| :--------- | :-------------------------------------------- |
| **Manual** | Add typed fields using the visual JSON editor |
| **Code** | Write the complete JSON structure directly |
Manual fields support strings, numbers, booleans, arrays, objects, and nested values. Both modes support fixed values and variables available at the block.
Select a Manual field or place the cursor in the Code editor, then choose a value from **Available Variables**. Use variables for call details or information collected during the conversation, and fixed values for constants required by the destination.
For example, a custom body might resolve to:
```json theme={null}
{
"call_id": "550e8400-e29b-41d4-a716-446655440000",
"customer_phone": "+12125551234",
"outcome": "Appointment booked"
}
```
Match the field names, structure, and data types expected by the receiving endpoint.
## Test the request
Run the block test before relying on Send Call Data. The test sends a real `POST` request to the configured endpoint.
1. Enter safe sample values for each variable used in the custom body.
2. Review **Resolved Input** to confirm the URL and JSON body.
3. Run the test and inspect **Test Result**.
4. Confirm in the receiving system that the request arrived with the expected data.
When **Send full call data** is enabled, the test sends representative sample call data. A live call sends the actual data available for that call.
Testing can trigger real automation or create records in the receiving system. Use a test endpoint or data that is safe to process.
## Verify the live behavior
Complete a controlled call that reaches the live-call block connected to Send Call Data, then let the call end.
1. Confirm that the endpoint receives one request after the call.
2. Check that fixed values and variables resolve correctly.
3. For full call data, confirm that the fields needed by the destination are present.
4. For a custom body, confirm that its JSON structure matches the endpoint's requirements.
The endpoint must return HTTP `200` after accepting the live payload. In **Call Details**, expand Send Call Data to review its execution status.
## Troubleshooting
Confirm that the configured HTTPS URL is publicly reachable and accepts `POST` requests. The post-call block runs only when the call reaches the live-call block to which it is connected, so also confirm that the tested call followed that path.
Confirm that it accepts JSON with `Content-Type: application/json` and returns HTTP `200`. Send Call Data cannot add custom authorization headers; use a post-call API Request when the endpoint requires them.
Check that the variable is available at the block and enter a representative value for it during the block test. Review **Resolved Input**, then confirm that each manual field uses the required data type or that the raw JSON is valid.
Some fields depend on what occurred or was captured during the call. Complete a representative call and confirm that the source information exists in Call Details. Use a custom body when the destination needs a smaller, stable contract.
Full-payload tests use sample call data. Complete a controlled call to inspect the values produced by a live call.
# Vision
Source: https://docs.phonely.ai/blocks/data-and-automation-blocks/vision
Start a legacy webpage automation task during a call.
Vision is a legacy block and is not recommended for new flows. Website changes may cause its tasks to fail.
Use **Vision** to start an external webpage automation task during a live call in an inbound or outbound flow. Phonely sends the URL, objective, success criteria, and any additional information to the service.
The flow continues after the service accepts the task. It does not wait for completion, and later blocks cannot use the task result.
## Configure the task
| Field | Purpose |
| :------------------------- | :------------------------------------------------------------------ |
| **URL** | The webpage where the task should run |
| **Objective** | The specific action to attempt |
| **Success Criteria** | How the automation service should determine that the task succeeded |
| **Additional Information** | Optional key-value details the task may need |
Keep the objective focused on one task and make the success criteria observable. For example:
* **Objective:** Submit the contact form with the provided customer details
* **Success Criteria:** The website displays a confirmation that the form was submitted
The objective, success criteria, and additional information can use variables available at the block.
## Test the task
The **Test** tab uses separate test values and starts a real task on the specified webpage.
1. Use a webpage and account that are safe for testing.
2. Enter a test URL, objective, success criteria, and any additional information.
3. Select **Initiate Task**.
4. Review the task status, steps, and available screenshots.
You can cancel the task before it completes. Test again whenever the webpage or its interaction flow changes.
## Limitations
* Websites that require authentication, verification challenges, or unpredictable interactions may not work reliably.
* Ask AI does not create or configure Vision blocks.
* Prefer [API Request](/blocks/api-request) or an [integration](/integrations/overview) when the service provides a supported alternative.
## Troubleshooting
Confirm that the test URL, objective, and success criteria are present. The Test tab uses its own values rather than the values configured for the live flow.
Confirm that the webpage is still accessible and that its layout or interaction flow has not changed. Simplify the objective and success criteria, then run another controlled test.
# Webhook
Source: https://docs.phonely.ai/blocks/data-and-automation-blocks/webhook
Receive external data before an inbound call and use it in the flow.
Use **Webhook** to preload external data for an inbound call. For example, a CRM or routing service can send the caller's account status, preferred language, or support tier so the flow can personalize the greeting or choose a route without collecting the same information.
Webhook runs only in pre-call on inbound flows. Use [API Request](/blocks/api-request) when the flow should request data from an external service as it runs.
## How Webhook works
Your external system sends an authenticated `POST` request to the generated webhook URL. Phonely stores the payload for the specified agent and caller phone number.
When an incoming call matches that agent and phone number, the Webhook block loads the payload before the flow trigger runs. Fields discovered during a successful block test become variables for the trigger and later blocks.
Send the request before the call reaches Phonely whenever possible. If the request and call may arrive at nearly the same time, configure a short fallback wait.
## Send data to the webhook
Open the block's **Configure** step to copy its webhook URL, API key, or sample cURL command. Send a `POST` request with a JSON body and the API key in the `X-Authorization` header.
The request body requires:
| Field | Purpose |
| :------------ | :--------------------------------------------------- |
| `agentId` | Identifies the agent that should receive the payload |
| `phoneNumber` | Matches the payload to the incoming call |
Add each value you want to use in the flow as another top-level field:
```json theme={null}
{
"agentId": "your_agent_id",
"phoneNumber": "+12125551234",
"customer_name": "Jordan Lee",
"support_tier": "priority",
"account_verified": true
}
```
Use the caller's actual phone number, including its country code. Additional field values must be text, numbers, booleans, or `null`; nested objects and arrays are not accepted.
Keep the API key private. Do not include it in documentation examples, screenshots, shared logs, or Ask AI prompts.
## Test and create variables
The block test discovers the payload fields and creates variables for later blocks to use.
1. Open the **Test** step and select **Test**.
2. Within one minute, send a `POST` request to the webhook using representative field names and safe sample values.
3. Confirm that the fields appear under **Fields from the webhook**.
A successful test creates variables under the block's name. Later blocks can select them from **Available Variables**.
If the payload fields change, run the test again and review any downstream fields that reference the Webhook variables.
## Configure the fallback wait
Under **Advanced Settings**, **Time Wait Before Fallback** controls how long the block checks for data after the call begins:
* At `0` seconds, the block checks once and continues immediately if no matching payload is available.
* From `1` to `5` seconds, the block continues checking for the payload until the configured time expires.
Keep this value as short as possible because the caller waits before the flow trigger begins. If no matching payload arrives in time, the flow continues without values from that request.
## Verify the live behavior
Use a phone number you control:
1. Send the payload with the agent's ID and the phone number you will call from.
2. Place an inbound call to the agent from that number.
3. Confirm that the flow follows the expected route and that later blocks receive the Webhook values.
Test both a matching payload and a call with no matching payload, especially when the flow uses Webhook data for routing.
## Troubleshooting
Select **Test** before sending the request and send it within one minute. Confirm that the request uses `POST`, includes the copied API key in `X-Authorization`, and contains both `agentId` and `phoneNumber`.
Include the field in a successful block test. Use a top-level field with a text, number, boolean, or `null` value; nested objects and arrays are not accepted. If the field set changed, test again and update any affected references.
Confirm that `agentId` identifies the agent receiving the call and that `phoneNumber` matches the number used to place it. Send the payload before the call, or increase **Time Wait Before Fallback** slightly when the two events can occur at nearly the same time.
Reduce **Time Wait Before Fallback** or send the payload earlier. Use a nonzero wait only when the external system cannot reliably send the data before the call starts.
# Flow Triggers
Source: https://docs.phonely.ai/blocks/flow-blocks/start-flow
Configure the triggers that start the First Flow, other inbound flows, and outbound flows.
Every flow begins with one fixed trigger. Phonely adds the trigger when you create the flow; it cannot be added from the block picker, deleted, or moved on the canvas.
The trigger depends on the flow's direction and role:
| Trigger | Flow | How it starts |
| :------------- | :--------------------- | :--------------------------------------------- |
| **Greeting** | Inbound **First Flow** | Incoming call |
| **Start Flow** | Other inbound flow | Transfer Flow or Global Flow trigger condition |
| **Make Call** | Outbound flow | Places an outbound call |
## First Flow and its Greeting
The **First Flow** is the agent's default entry point for inbound calls. Each agent can have only one First Flow, and its trigger appears as **Greeting**.
Select Greeting to configure:
* **Greeting Message:** The first thing the agent says when it answers an inbound call.
* **Answers:** Up to six optional routes from the greeting. Expand **Advanced Settings** to add them, then connect each answer to the appropriate next block.
* **No engagement outcome:** The outcome recorded when the call ends before the caller engages with the agent. It defaults to **Greeting Hangup** and can be edited. This setting is under **Advanced Settings**.
### Change the First Flow
A flow must have at least one published version before you can make it the First Flow.
1. Publish the target flow first if it has no published version.
2. Select its **Start Flow** trigger and enable **Set as First Flow**.
3. Wait for the First Flow change to auto-save.
4. Review the **Greeting** and its paths, then publish draft changes before testing.
Making a flow the First Flow also turns it on and updates the agent's inbound entry point. It does not publish draft changes; publish any later edits separately.
If call recording is enabled, the editor reminds you to include an appropriate recording disclosure in the greeting. Make sure the wording meets the requirements that apply to your calls.
## Start Flow for other inbound flows
An inbound flow that is not the First Flow begins at **Start Flow**. It does not receive a new call or replay the First Flow's greeting. The active conversation enters it in one of two ways:
* **Transfer Flow:** A connected block routes the active call into the flow.
* **Global Flow:** Phonely enters the flow when its **Trigger Condition** matches in an enabled conversation type.
Connect the Start Flow output to the first block that should run after the conversation enters the flow.
Transfer Flow keeps the call active, but flow-specific variables do not carry automatically from the source flow to the target flow. Import a [Flow Input](/flow-editor/variables#use-flow-inputs) in the target flow to reuse a value the source flow collected, or design the target flow to collect or retrieve the data it needs.
### Configure a Global Flow
A **Global Flow** is available from across a conversation instead of only through a connected Transfer Flow block. Use one when a distinct intent should be reachable from multiple parts of the agent.
To configure it:
1. Open another inbound flow and select **Start Flow**.
2. Enable **Set as Global Flow**.
3. In **Trigger Condition**, describe when to enter the flow.
4. Select at least one conversation type: **Inbound**, **Outbound**, or **SMS**.
5. Turn on the flow, then test conversations that should and should not enter it.
![Start Flow settings for an Appointment Booking Global Flow, including its trigger condition and enabled conversation types]()
Write the Trigger Condition as a clear intent, not a list of exact phrases. Keep it specific and distinct from other Global Flow trigger conditions so the agent can choose the intended flow.
A Global Flow is considered throughout each selected conversation type, not only at a fixed point in the current flow. Use it only when its intent should remain broadly available.
If **Set as Global Flow** is off, the flow can still be entered through a connected Transfer Flow block. Turning the flow off removes it from normal Global Flow routing.
## Make Call for outbound flows
Every outbound flow begins with **Make Call**. Select the trigger to configure:
* **Phone Number:** The destination to call. Insert a variable when the number is supplied at runtime.
* **Voice Mail Message:** The message Phonely leaves when voicemail is detected.
* **Provide Call Screening Details:** Optional caller identity and reason for calling. When an automated call screener answers, Phonely provides this information so the recipient knows who is calling and why. **Caller Name** and **Reason for Calling** can use variables available before the call begins. When it is enabled, you can also set a **Call screening AI hangup outcome**, recorded when the agent ends a call after reaching an automated screener; it defaults to **Call Screening AI Hangup**.
* **No engagement outcome:** The outcome recorded when the call ends before the recipient engages with the agent. It defaults to **Greeting Hangup** and can be edited.
* **Voicemail Call Outcome Tagging:** Outcome tags recorded for calls that reach voicemail. This setting is under **Advanced Settings**.
Make Call provides two outputs:
* **Answered:** Continue the live call path when someone answers.
* **Voicemail:** Start an optional post-call path for voicemail handling.
Connect **Answered** to the first block the agent should run after someone answers. Use the **Voicemail** connection when that outcome needs follow-up work after the call.
Pre-call blocks are optional. Add one from the connection above **Greeting** or **Make Call** to run it before the agent greets an inbound caller or dials an outbound number.
Use pre-call blocks to prepare or validate data, set variables for later blocks, end an inbound call before the greeting, or prevent an outbound call from being placed.
A failed request does not stop the call automatically. Route the relevant failure result to a pre-call **End Call** block when **Greeting** or **Make Call** should not run.
**Start Flow** does not support pre-call blocks because the conversation is already active when another inbound flow begins.
Understand flow stages, drafts, versions, and the complete editing process.
Connect trigger outputs, branches, transfers, and fallback paths.
Find missing trigger settings and connections before publishing.
Test the right version and release reviewed changes safely.
# Talk
Source: https://docs.phonely.ai/blocks/flow-blocks/talk
Handle a multi-turn conversation, collect information, and route the call by outcome.
Choose **Talk** when the agent needs to adapt over several turns, such as answering questions, understanding an issue, or qualifying a caller. It stays active until an exit condition is met and can collect values along the way.
Choose [Collect](/blocks/conversation-blocks/collect) for the more focused task of gathering a defined set of fields.
## Start the block
Configure the block directly, or expand the **Generate with AI** strip at the top of the panel, describe what you want, and start a focused Ask AI task that proposes changes to this block alone. For example:
> Answer the caller's questions using the knowledge base. If an answer is unavailable, offer to collect their contact details for follow-up.
Review the proposal on the canvas and apply it, then refine the block by asking again. The instruction is not saved onto the block, so the box starts empty each time and the request lives in the Ask AI conversation. Generation is offered only on an editable draft, not in version previews, comparisons, or to viewers.
## Configure the conversation
### Prompt
The **Prompt** tells the agent how to handle the conversation while Talk is active. Write directions rather than a script. Include the objective, relevant context or boundaries, and what the agent should do when it cannot complete the task.
Type `@` and select an available variable or knowledge base source when the prompt needs that information. Adding its name as plain text does not insert the source.
### Exit Conditions
Each **Exit Condition** describes a conversational result that ends the Talk block and creates a source handle. Connect that handle to the block that should run next.
Write conditions as completed, observable outcomes. For example:
* `The caller's question has been answered and they have no more questions`
* `The caller wants to leave their contact details`
* `The caller asks to speak with a person`
A Talk block requires at least one exit condition and supports up to ten. Conditions must be non-empty and unique.
Exit conditions decide when Talk ends and can override instructions in the Prompt. If the block advances too early or takes the wrong route, make the relevant condition more specific before adding more prompt instructions.
When several conditions lead to the same block, combine them into one outcome-focused condition for clearer routing.
### Variables
Add a variable when the Talk block should extract information from the conversation for later blocks.
| Field | Purpose |
| :-------------- | :--------------------------------------------------------------------- |
| **Name** | Name shown in **Available Variables**; must be unique within the block |
| **Type** | Expected format of the value |
| **Description** | Information the agent should collect |
| **Required** | Collect the value before leaving the block |
| **Confirm** | Ask the caller to confirm a required value |
| **Spell Back** | Spell a confirmed value character by character |
**Confirm** is available after **Required** is enabled, and **Spell Back** is available after **Confirm** is enabled.
Collected values appear in **Available Variables** for later blocks on that route. See [Variables](/flow-editor/variables) for types, availability, and troubleshooting.
## Example: Answer business questions
* **Prompt:** Use the knowledge base to answer questions about the business. Keep answers concise. If the answer is unavailable, explain that a team member can follow up and offer to collect the caller's details.
* **Exit conditions:**
* The caller's questions have been answered and they have no more questions
* The caller wants to leave their information for follow-up
* **Variable:** `unanswered_question` — the caller's unanswered question
Connect the answered route to [End Call](/blocks/flow-control-and-routing/end-call) and the follow-up route to [Collect](/blocks/conversation-blocks/collect). This keeps the completed and follow-up paths explicit on the canvas.
## Test Talk
Test the expected outcome and each meaningful alternative. Confirm that Talk:
* remains active while its conversational objective is incomplete;
* handles different phrasing for the same intent consistently;
* selects the intended exit condition and route for each outcome; and
* stores and confirms variables as configured.
Use **Web Call** when voice behavior matters, such as pacing and interruptions.
For an unexpected result, open **Call Details**, select **Blocks**, and expand Talk to review its conversation turns, selected route, and stored variables.
## Troubleshooting
Confirm that at least one exit condition can become true from the conversation guided by the **Prompt**. If needed, rewrite the condition as a clear result the agent can recognize.
Give the Talk block one conversational objective with clear completion points. Move structured collection, actions, or later decisions into connected blocks.
Open **Call Details** and confirm that the call passed through Talk and stored the value. If later blocks always need it, enable **Required**. Otherwise, make sure those blocks can run without it.
# Delay
Source: https://docs.phonely.ai/blocks/flow-control-and-routing/delay
Wait before running connected post-call blocks.
Use **Delay** to wait before running the connected post-call blocks. It schedules the rest of that path for later; it does not pause the live conversation.
## Configure the delay
1. Connect the post-call path to Delay.
2. In **Time Delayed For**, enter a whole number or select an available variable that resolves to one.
3. Choose **Minutes**, **Hours**, or **Days**. The duration must be at least one minute.
4. Connect Delay to every post-call block that should run after the wait.
The wait starts when the post-call path reaches Delay. If Delay is the first post-call block, its duration is counted from the end of the call.
## Build the delayed path
The delayed path retains the call's available variables, so later blocks can use information collected during the call. For example, place Delay before [Send SMS](/blocks/communication-blocks/send-sms) to send a follow-up message the next day.
Two Delay blocks cannot connect directly to each other. Set one Delay to the total wait required before its connected blocks run.
# End Call
Source: https://docs.phonely.ai/blocks/flow-control-and-routing/end-call
Play a final message and end the call.
Use **End Call** when the agent should play a final message and end the call. It is terminal for the live conversation, so the flow does not continue to another live-call block.
## Configure the closing message
Choose how End Call creates the final message:
| Mode | Behavior |
| :------------- | :---------------------------------------------------------------------- |
| **Fixed** | Says the text you enter exactly |
| **Promptable** | Generates a closing from your instructions and the conversation context |
With **Fixed**, enter the wording in **End Call Message**. With **Promptable**, use **End Call Message Prompt** to describe the closing the agent should generate.
Select values from **Available Variables** when the message or prompt needs information from earlier blocks. Keep the closing concise and do not invite another response—the call ends after the message.
Use End Call's message instead of adding another block only to say goodbye.
## Reject an inbound call before the conversation
Place End Call on a pre-call rejection path when an inbound call should not reach the **Greeting**. It plays a **Fixed** message and ends the call. For example, connect it after a pre-call [Filter](/blocks/flow-control-and-routing/filter) or data check that identifies a blocked, ineligible, or unsupported caller.
Promptable mode is not available for a pre-call End Call block.
## Run post-call blocks
A live-call End Call block can connect to post-call blocks. Those blocks run after calls that reach that End Call block; they do not continue the live conversation.
To record why the call ended, use [Call Outcome Tagging](/blocks/common-settings#call-outcome-tagging).
# Filter
Source: https://docs.phonely.ai/blocks/flow-control-and-routing/filter
Route a flow by evaluating ordered cases against available data.
Use **Filter** to route the flow using data available when the block runs, such as caller information, collected answers, or results from earlier API Request, Code, and integration blocks.
Filter can run pre-call, live call, or post-call. Use [Talk exit conditions](/blocks/flow-blocks/talk#exit-conditions) for conversational outcomes and [Time Filter](/blocks/flow-control-and-routing/time-filter) for recurring weekly availability.
## How Filter routes
A Filter contains one or more ordered **Cases** and an **Else** fallback. It evaluates the cases from top to bottom and follows the first case whose conditions match. If no case matches, it follows Else.
Case order matters. Put narrow or high-priority cases before broader cases that could match the same data.
## Configure Filter
Filter starts with **Case 1**. Select **Add Case** to create another route. Every case requires at least one condition.
### Define a condition
Each condition uses **Field** and **Operator**. Operators that compare values also show **Type** and a comparison value:
| Field | Purpose |
| :---------------------------- | :----------------------------------------------------------------------- |
| **Field** | Value or AI condition to evaluate |
| **Operator** | Rule used to evaluate the field |
| **Type and comparison value** | How to interpret the comparison value and what to compare with the field |
Select the field from **Available Variables** when the condition depends on dynamic data. Typing a variable name as plain text does not insert its value. Only variables available before Filter on the current route can be selected. See [Variables](/flow-editor/variables) for how the editor determines availability.
Choose a type that matches the data:
| Type | Use it for |
| :---------- | :----------------------------------------------- |
| **String** | Text, categories, identifiers, and statuses |
| **Number** | Amounts, counts, scores, and numeric comparisons |
| **Boolean** | `true` or `false` values |
The available operators depend on the selected type:
* **exists** and **doesn't exist:** Check whether **Field** has a value or is empty.
* **is equal to** and **is not equal to:** Compare **Field** with a specific value.
* **Number comparisons:** Compare a numeric **Field** with a specific value using greater than, greater than or equal to, less than, or less than or equal to.
* **is an array containing:** Check whether an array contains a specific item.
* **matches condition (AI)** and **does not match condition (AI):** Evaluate a natural-language condition against the conversation context.
**exists**, **doesn't exist**, and the AI operators do not use a comparison value. For an AI operator, enter the condition to evaluate in **Field**. Use AI matching only after the relevant conversation has occurred, and prefer another operator whenever structured data can express the rule.
### Combine conditions
Select **Add Condition** to add another rule to a case. When a case has multiple conditions, choose how they work together:
* **AND** requires every condition in the case to match.
* **OR** requires at least one condition in the case to match.
AND or OR applies only within that case. Filter still evaluates the cases in order and stops at the first match.
### Connect the routes
Each case and Else appears as a separate route on the canvas. Connect each **Case** route to the path that should run when it matches, and connect **Else** to a safe fallback for data that is missing, unexpected, or not covered by a case.
Deleting a case also removes its route connection. Review the canvas after changing the case list.
## Example: Route by risk and customer tier
Suppose a pre-call API request returns `risk_score` and `customer_tier`. Configure the cases in this order:
| Route | Match | Destination |
| :--------- | :-------------------------------------------- | :---------------- |
| **Case 1** | `risk_score` is greater than or equal to `80` | Verification path |
| **Case 2** | `customer_tier` is equal to `enterprise` | Priority support |
| **Else** | No case matched | Standard support |
If an enterprise caller also has a risk score of 90, Case 1 wins because it appears first.
## Troubleshooting
Open **Call Details**, select **Blocks**, and expand Filter to review the selected route and each condition's result. Check whether an earlier case also matched, then confirm the case's AND or OR setting, value type, operator, and comparison value. Move more specific cases above broader ones.
Confirm that the expected variables are available before Filter on the current route and were inserted from **Available Variables**. Then check for missing values or a type mismatch.
Run Filter only after the relevant conversation exists, and write one clear condition that can be judged from that context. Use a deterministic operator instead when structured data can express the rule.
# Time Filter
Source: https://docs.phonely.ai/blocks/flow-control-and-routing/time-filter
Route calls using the agent's recurring weekly availability.
Use **Time Filter** to route calls according to a recurring weekly schedule. It is useful for business hours, split shifts, and other availability that repeats each week.
Use [Filter](/blocks/flow-control-and-routing/filter) when the route should depend on data instead of time.
## How Time Filter routes
Time Filter uses the agent's timezone to compare the call's start day and time with the configured schedule:
* **Available** runs when the call starts within an enabled time range.
* **Unavailable** runs when the call starts outside every range or the day is disabled.
Connect both routes so the call has a defined path during and outside the schedule.
## Configure available times
Under **Available Times**, enable each day when the agent is available and set its time ranges.
* Select **+** to add another range to the same day, such as separate morning and afternoon hours.
* Select the remove icon beside a range to delete it.
* Disable a day when the agent is unavailable all day.
Time ranges on the same day cannot overlap. Split overnight availability across two days. For example, represent Sunday 10:00 PM through Monday 2:00 AM with a late Sunday range and an early Monday range.
The schedule repeats weekly. It does not include date-specific exceptions such as holidays.
## Example: Route during support hours
For support hours of 9:00 AM–12:00 PM and 1:00 PM–5:00 PM, Monday through Friday:
1. Enable Monday through Friday and add both ranges to each day.
2. Disable Saturday and Sunday.
3. Connect **Available** to the live support path.
4. Connect **Unavailable** to an after-hours message or follow-up path.
## Troubleshooting
Confirm that the call's start day is enabled, has at least one time range, and includes the call's start time. Then check the agent's timezone.
Split the range across two days. Configure the first range through the end of the starting day and the second from the beginning of the next day.
Remove overlapping time ranges from the same day.
# Transfer Flow
Source: https://docs.phonely.ai/blocks/flow-control-and-routing/transfer-flow
Continue an active call in another inbound flow for the same agent.
Use **Transfer Flow** to continue an active call in another inbound flow for the same agent. The call stays connected, and the target flow begins at its **Start Flow** trigger.
Use [Transfer Call](/blocks/communication-blocks/transfer-call) instead when the call should leave Phonely for a phone destination. Use a [Global Flow](/blocks/flow-blocks/start-flow#configure-a-global-flow) when an intent should be reachable throughout the conversation rather than from a specific Transfer Flow block.
## How Transfer Flow routes
Transfer Flow requires at least one destination:
* With **one destination**, the call enters that flow directly.
* With **multiple destinations**, Phonely uses each target flow's **Transition Condition** to choose a destination and may ask clarifying questions.
The source flow does not continue after Transfer Flow. The call continues from the selected target flow instead.
A Transition Condition belongs to the target flow. Editing it updates every place that uses the same flow for intent-based routing.
## Configure destinations
Under **Available Sub-Flows**, select the inbound flow the call should enter.
Select **Add Flow Destination** to add another target. When the block has multiple destinations, enter a distinct **Transition Condition** for each one. Describe the caller need that should route to the flow, not what the flow does after the transfer.
For example:
| Target flow | Transition condition |
| :---------- | :------------------------------------------------------------- |
| **Sales** | The caller wants pricing, a quote, or to purchase a service |
| **Support** | The caller needs help with an existing product or service |
| **Billing** | The caller has a question about an invoice, charge, or payment |
Avoid conditions that overlap without explaining the difference. Select **View flow** to open the target flow on the canvas.
## Prepare the target flow
The target flow controls the conversation after the transfer. Review its **Start Flow** connection, flow settings, and downstream routes before using it as a destination. Turn on the target flow so it is available during normal calls.
Set a [**Switch Message**](/flow-editor/flow-settings#switch-message) when the agent should acknowledge the transition as the call enters the target flow.
Transfer Flow keeps the call active, but flow-specific variables do not carry automatically from the source flow to the target flow. Import a [Flow Input](/flow-editor/variables#use-flow-inputs) in the target flow to reuse a value the source flow collected, or design the target flow to collect or retrieve the data it needs.
For caller feedback during the transfer and outcome reporting, see [Common Block Settings](/blocks/common-settings).
## Test the routing
Publish changes to the source and target flows, then test every destination from the source flow. For an inbound source, **Web Chat** is the quickest way to try clear and ambiguous requests. For an outbound source, use **Place Phone Call**.
Confirm that Phonely enters the intended flow or asks an appropriate clarifying question. Use **Web Call** or **Place Phone Call** when you need to hear the transition and **Switch Message**. After the test, open **Call Details**, select **Blocks**, and expand Transfer Flow to confirm the target flow.
## Troubleshooting
Compare the destinations' **Transition Conditions**. Make each condition specific and mutually distinguishable, then retest clear and ambiguous requests.
Confirm that the target flow is turned on and still selected in Transfer Flow. Publish changes to both flows, then test again from the source flow.
Transfer Flow lists inbound flows for the same agent. Confirm that the flow belongs to the agent and was created as an inbound flow.
Variables created in the source flow are not carried automatically into the target flow. Import a [Flow Input](/flow-editor/variables#use-flow-inputs) for the value in the target flow, or collect or retrieve it again within the target flow.
# Overview
Source: https://docs.phonely.ai/blocks/overview
Find the Phonely block that matches your task and see where it can run in a flow.
Blocks are reusable capabilities that handle individual steps in a flow, such as speaking, collecting information, making a decision, sending a request, or processing data. Use this page to compare blocks and see where each can run.
Some blocks also share settings for caller feedback, failure routes, and reporting. See [Common Block Settings](/blocks/common-settings) to configure those options.
The **Available in** column shows where a block can run. **All stages** means pre-call, live call, and post-call. The block picker filters by the flow direction and stage where you open it.
Blocks that connect to external services have one canonical guide under [Integrations](/integrations/overview). Each guide covers both connection setup and using the integration in a flow.
Greeting, Start Flow, and Make Call are [flow triggers](/blocks/flow-blocks/start-flow), not reusable blocks. Phonely adds the appropriate trigger when you create a flow.
## Conversation
| Block | Use it to | Available in |
| :--------------------------------------------- | :--------------------------------------------------------------------------- | :----------- |
| [Talk](/blocks/flow-blocks/talk) | Handle a multi-turn conversation, collect information, and branch by outcome | Live call |
| [Collect](/blocks/conversation-blocks/collect) | Collect specific information from the caller in a structured format | Live call |
## Flow control and routing
| Block | Use it to | Available in |
| :-------------------------------------------------------------- | :--------------------------------------------------- | :------------------ |
| [Filter](/blocks/flow-control-and-routing/filter) | Route the flow using available data | All stages |
| [Time Filter](/blocks/flow-control-and-routing/time-filter) | Route the flow based on a weekly schedule | Live call |
| [Transfer Flow](/blocks/flow-control-and-routing/transfer-flow) | Continue the call in another flow for the same agent | Live call |
| [End Call](/blocks/flow-control-and-routing/end-call) | End the call with a final message | Pre-call, live call |
| [Delay](/blocks/flow-control-and-routing/delay) | Wait before running connected post-call blocks | Post-call |
Use [Talk exit conditions](/blocks/flow-blocks/talk#exit-conditions) for conversational outcomes and Filter for data-based routing. Transfer Flow stays within the agent, while [Transfer Call](/blocks/communication-blocks/transfer-call) sends the call to a phone destination.
## Calls and messaging
| Block | Use it to | Available in |
| :------------------------------------------------------------------------------ | :-------------------------------------------- | :------------------- |
| [Transfer Call](/blocks/communication-blocks/transfer-call) | Transfer a call to one or more phone numbers | Live call |
| [Send SMS](/blocks/communication-blocks/send-sms) | Send a text message to a phone number | All stages |
| [Send Email](/blocks/communication-blocks/send-email) | Send an email to one or more recipients | Live call, post-call |
| [Email & SMS Notification](/blocks/communication-blocks/email-sms-notification) | Send a call summary by email, SMS, or both | Post-call |
| [Redial](/blocks/communication-blocks/redial) | Schedule one or more follow-up call attempts | Post-call |
| [Campaign](/blocks/communication-blocks/campaign) | Queue an outbound call in a selected campaign | Post-call |
Use Send SMS or Send Email when you control the message content. Use Email & SMS Notification to deliver the conversation summary automatically after the call.
## Data and automation
| Block | Use it to | Available in |
| :------------------------------------------------------------------ | :------------------------------------------ | :--------------------- |
| [API Request](/blocks/api-request) | Send an API request and use the response | All stages |
| [Code](/blocks/data-and-automation-blocks/code) | Process data with Python and use the output | All stages |
| [Webhook](/blocks/data-and-automation-blocks/webhook) | Receive data from an external service | Pre-call, inbound only |
| [Send Call Data](/blocks/data-and-automation-blocks/send-call-data) | Send call data to an endpoint | Post-call |
| [Vision](/blocks/data-and-automation-blocks/vision) | Start a legacy webpage automation task | Live call |
## Integrations
Provider-connected blocks and branded webhook automations are documented under [Integrations](/integrations/overview). Use that section to compare their actions and configure accounts, webhooks, inputs, variables, and tests.
The picker shows where a block can run, but it does not confirm that the block is fully configured. Complete its required settings and resolve any errors in the [Flow Checklist](/workflow-checklist) before publishing.
# Call Events
Source: https://docs.phonely.ai/call-events
Inspect event-level execution for an agent's calls.
Call Events is a technical view of the events recorded before, during, and after calls. Use it when Call History shows the conversation but you need more detail about execution.
## Find the relevant events
Select an agent, then filter the event table by fields such as:
* date;
* call ID;
* event status or HTTP status code;
* event type or name;
* execution stage; and
* execution time.
Use **Refresh** to load newer events. Select an event to open its details; the fields shown depend on the event type.
## Investigate a call
1. Copy the call ID from Call History or Call Details.
2. Filter Call Events by that ID.
3. Order the events by time and identify the first unexpected status or result.
4. Open that event and inspect its available request, response, timing, or telephony details.
5. Compare the event with the corresponding block in Call Details.
Focus on the earliest event that differs from the expected behavior. Later failures can be consequences of an earlier missing value, rejected request, or telephony event.
## Handle event data carefully
Event details can contain phone numbers, request data, returned values, and other call context. Share only the fields needed for the investigation, and do not copy credentials or sensitive customer data into public channels.
Event names and fields are technical execution data and may vary by event type. Use the product-facing block name and behavior when writing customer documentation or support guidance.
Use [Call History](/call-history-ai-analytics/call-history-ai-analytics) for the transcript and block trace, [Call Paths](/call-path) for route patterns across calls, and Call Events for the underlying execution timeline.
# Call History
Source: https://docs.phonely.ai/call-history-ai-analytics/call-history-ai-analytics
Find calls and review their transcript, recording, highlights, and block execution.
Call History is the record of an agent's phone and web conversations. Use it to find a call, understand what happened, and inspect how the flow ran.
## Find a call
Search by phone number or words from the call, or filter the list by fields such as:
* date and duration;
* call type and mode;
* status and end reason;
* outcome, topic, and sentiment; and
* prompt version.
Unanswered outbound dials show their specific telephony result instead of a generic failure: **No Answer**, **Busy**, and **Failed to Connect** appear as end reasons in the list and in a call's details, and you can filter for them alongside **Voicemail**.
The list groups calls by date and shows current calls as they progress. Select a call to open **Call Details**.
## Review Call Details
Call Details keeps the transcript beside two review tabs:
| Tab | Use it for |
| -------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Highlights** | Summary, sentiment, caller and end details, topics, outcome, actions, and time spent in blocks |
| **Blocks** | The ordered blocks and actions recorded while the call ran, including stored variables and available execution details |
For a completed call, use the audio player to hear the conversation while following the transcript. Transcript event separators identify non-conversational events where available.
Select a block or duration segment to move to the corresponding part of the transcript. This is useful when one Talk block contains several caller and agent turns.
## Correct call classifications
In **Highlights**, you can correct the detected sentiment and add or remove configured topics. These changes update the call record used by filters and reporting.
If call review is enabled for your role, mark the call as a success or error after reviewing it. Calls flagged for review also show their review reasons and status.
## Analyze a call with Ask AI
Use **Analyze with AI** when you want Ask AI to inspect calls. With no selection, it defaults to every call the current list matches and narrows to your selection once you make one. It can combine the transcript with block execution and underlying call details, including events that are not practical to review manually in the standard interface.
A deliberate selection is analyzed exactly, up to 500 calls; above that, Analyze with AI asks you to narrow the selection. Without a selection, it uses a recent sample instead of the whole list. Analyze with AI tells you when it hands the assistant a sample rather than every call, and it distinguishes loaded, remaining, and unavailable calls so a partial view is never mistaken for the whole.
Ask a specific question, such as:
* `Can you look into this call in detail?`
* `Why did the call take this route?`
* `Did the API request return the expected data?`
Treat the answer as an investigation aid. Confirm important operational conclusions against the transcript, block trace, and [Call Events](/call-events).
## Choose the right surface
* Use **Call History** for a conversation, recording, and flow trace.
* Use [Call Paths](/call-path) to compare routes across many calls.
* Use [Performance](/performance) for aggregate trends.
* Use [Agent Review](/agent-review) to manage issues reported by your team.
* Use [Call Events](/call-events) for event-level debugging.
# Call Paths
Source: https://docs.phonely.ai/call-path
See how calls moved through a flow and inspect volume at each route.
Call Paths overlays call activity on a flow so you can see which blocks and routes callers reached.
Use it to investigate questions such as where calls leave a flow, which route is used most often, or whether behavior changed between published flow versions.
## Choose the calls to analyze
Select the agent and flow, then set:
* a date range;
* one or more published flow versions; and
* any additional call filters.
The canvas and its metrics use only calls that match this scope. Select a single version when you need the diagram and configuration from one release of a flow.
## Read the canvas
The canvas uses the familiar flow structure and adds call-volume information. Select a block to open **Node Details**.
The details panel can show:
| Area | What it contains |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| **Details** | The block configuration available for the selected flow version |
| **Metrics** | Calls that reached the block, **% from start**, **% from last**, **Calls ended here**, turns, and exit-path usage |
Select a metric or route with associated calls to inspect those conversations. If the selected block's configuration is unavailable for an older version, use its metrics and call drilldown rather than the current flow editor as evidence of the old configuration.
## Follow routes across flows
Select a route or transferred flow to continue tracing the call path. Use the back control to return to the previous flow.
The flow version filter is important when tracing across flows: calls are analyzed against the published versions they used, not the agent's current draft.
## Investigate a path
1. Start with a date range and one flow version.
2. Find the first block where volume changes unexpectedly.
3. Compare **% from start**, **% from last**, and **Calls ended here**.
4. Inspect the relevant exit path and its calls.
5. Open individual calls to review their transcript and block execution.
Call Paths shows where calls went. Use [Call History](/call-history-ai-analytics/call-history-ai-analytics) to understand what happened in a specific conversation, and [Call Events](/call-events) for lower-level execution details.
# Call Sentiment
Source: https://docs.phonely.ai/call-sentiments
Define and review positive, neutral, and negative call sentiment.
Phonely classifies completed calls as **Positive**, **Neutral**, or **Negative**. A call whose sentiment could not be determined is shown as **Unknown**. Sentiment helps you find conversations that may need attention and compare the caller experience over time.
## Define sentiment for an agent
Open the agent's **Settings**, select **Analytics**, then edit the three **Sentiment Definitions**.
Describe what each label means for your business. Keep the definitions distinct and focus on evidence in the conversation. For example:
| Sentiment | Example definition |
| ------------ | --------------------------------------------------------------------------- |
| **Positive** | The caller expresses satisfaction, appreciation, or a successful result |
| **Neutral** | The conversation is factual without a clear positive or negative signal |
| **Negative** | The caller expresses frustration, dissatisfaction, or an unresolved concern |
Changes affect how future calls are classified; they do not automatically reprocess earlier calls.
## Review and correct sentiment
Sentiment appears in [Call History](/call-history-ai-analytics/call-history-ai-analytics), [Call Details](/call-history-ai-analytics/call-history-ai-analytics#review-call-details), [Performance](/performance) filters, and [Data Tables](/data-tables). In a completed call's **Highlights**, you can change the sentiment when the detected label does not represent the conversation accurately.
Use the same definitions when comparing agents or time periods. Different definitions can make similar conversations appear different in reporting.
# Call Topics
Source: https://docs.phonely.ai/call-topics
Define the topics used to classify completed calls.
Call topics classify what a completed conversation was about. Use them to organize Call History and compare common reasons for calls in Performance.
## Define topics
Open the agent's **Settings** and select **Analytics**. On agents that already use call topics, they appear as a built-in multi-category item within **Analytics Fields**; add each topic with a name and description. Agents that have never configured topics manage classification through Analytics Fields instead and do not create new topic configuration.
* Use the **name** as the stable reporting label.
* Use the **description** to explain when the topic applies.
* Keep topics distinct enough that the same conversation is not routinely ambiguous.
For example, prefer separate topics such as `New appointment`, `Reschedule appointment`, and `Cancel appointment` when those categories lead to different operational decisions.
Phonely analyzes completed calls against the agent's configured topics. A call can contain more than one topic. In reporting, two spellings that differ only by letter case are treated as the same topic.
## Review and use topics
Topics appear in [Call History](/call-history-ai-analytics/call-history-ai-analytics), [Call Details](/call-history-ai-analytics/call-history-ai-analytics#review-call-details), [Performance](/performance) filters and charts, and [Data Tables](/data-tables). In a completed call's **Highlights**, you can add or remove topics when the classification needs correction.
When you rename or remove a configured topic, earlier calls can still contain the previous value. Review saved Performance and Data Table views that refer to it.
Topics describe what the call was about. Use [Call Outcome Tagging](/blocks/common-settings#call-outcome-tagging) for a result recorded by the flow, and [Post-Call Outcomes](/post-call-outcomes) for a result added later through the API.
# Data Tables
Source: https://docs.phonely.ai/data-tables
Build tables that group calls and calculate the metrics you need.
A data table groups calls into rows and calculates the metrics you need. Use one when a chart does not answer the question you have.
Data tables are cards on the [Performance](/performance) board. Open **Performance**, choose an agent and view, then select **Add widget** and **Build a widget manually**.
Data Tables used to be its own tab. Your existing tables were moved onto the board, and a one-time note on the page tells you which view received them. Saved links that pointed at the old tab still open the right table.
## Build a table
In Explore, build the question, choose **Table** as its chart type, then save it to the board.
Each table defines:
| Part | Purpose |
| ---------------- | ----------------------------------------------------------------------------- |
| **Breakdown by** | Determines what each row represents, such as a time period or call attribute |
| **Metrics** | Calculates counts, totals, averages, percentages, or other supported formulas |
| **Filters** | Limits which calls contribute to the table |
Review the groupings, formulas, and filters before saving. Keep one table per stable reporting question instead of combining unrelated metrics in one card.
A table shares the board's date range and filters. Resize, reorder, or remove it like any other card. Select **Edit in Explore** (the pencil) to change its question or presentation.
## Use metrics and formulas
The metric editor lists the variables supported by the selected agent and table. These can include general call fields, topics, outcomes, custom call outcomes, and flow blocks, as well as a campaign's outbound variables and each inbound Webhook block's status and payload fields. A metric you expect to reuse can be saved and referenced from other cards.
A **Unique count** aggregation deduplicates by customer phone number within each row. When a table breaks calls down by time or another field, each row calculates its own unique customers. A customer can therefore be counted once in more than one row, so the row values do not add up to an overall unique-customer total.
Select variables from the editor rather than typing their internal form. This keeps formulas aligned with the available data.
A formula describes how to calculate a metric. It does not change any call record or flow behavior.
## Inspect the calls behind a value
Select a metric cell to open the calls that contributed to it. Use this drilldown to verify that the grouping, filters, and formula represent the intended population.
If a table looks unexpected:
1. Confirm the board's date range and the table's own filters.
2. Inspect a cell's underlying calls.
3. Check the grouping and formula variables.
4. Review whether topic, outcome, or block names changed for the agent.
## Keep the table current
Refresh the board to load current results. If the agent's topics, outcomes, or flow structure changes, review tables that refer to those values.
Export a table from its **More options** menu when you need the data outside Phonely. The export reflects the card and the board's current scope.
# Resolve Remote Flow Updates
Source: https://docs.phonely.ai/flow-editor/collaboration
Compare remote flow updates with your local draft and choose whether to preserve local work.
When the same flow changes elsewhere while you have it open, Phonely protects both copies instead of silently overwriting one. Compare the drafts, then choose how to load the remote update.
Phonely does not merge the two drafts automatically. **Save Local & Load Latest** backs up the local draft before loading the remote draft, but you must manually reapply any changes you still need.
## When the banner appears
The **New remote updates available** banner appears when a newer shared draft cannot be applied to your open canvas automatically. When available, the banner identifies the other editor.
![New remote updates available banner with Review Changes, Apply Latest, and Save Local and Load Latest actions]()
This can happen when a teammate, another browser tab, or another editing session changes the same flow. While the update is unresolved:
* auto-save is paused;
* publishing and version restoration are blocked; and
* the canvas continues to show your local draft.
Stop editing and resolve the update before continuing.
## Review the changes
Select **Review Changes** in the banner. The canvas switches to a read-only preview of the remote draft:
* changed blocks and connections are highlighted;
* select a changed block to inspect its updated settings; and
* select **Fit changes** to bring the affected parts of the flow into view.
The preview does not change either draft. Select **Back to Local** when you are ready to return to your draft and choose a resolution from the banner.
## Choose a resolution
| Action | What happens | Use when |
| :--------------------------- | :-------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| **Apply Latest** | Loads the remote draft and discards local differences | You no longer need the local changes, or they already exist in the remote draft |
| **Save Local & Load Latest** | Creates a **Draft Backup** version, then loads the remote draft | You may need to recover or reapply local changes |
A **Draft Backup** is an unpublished version saved in **Version History**. It is not merged into the remote draft; preview it later and manually reapply any changes you need.
## After loading the remote draft
If you created a **Draft Backup**, reapply any required local changes, then wait for auto-save to finish. Open the [Flow Checklist](/workflow-checklist) and resolve any block errors. Test the affected paths, and publish only after reviewing the updated draft.
To reduce conflicts, coordinate changes to shared flows and avoid editing the same flow in multiple tabs. Let Ask AI finish applying a change before editing the affected blocks.
## Troubleshooting
Return to the canvas and resolve the **New remote updates available** banner. **Review Changes** only compares the drafts; you must select **Apply Latest** or **Save Local & Load Latest** to resolve the update.
If you selected **Save Local & Load Latest**, open [Flow Versions](/flow-editor/versions), preview the **Draft Backup**, and manually reapply the changes you need.
If you selected **Apply Latest**, the discarded local differences were not saved as a version.
See [Flow Versions](/flow-editor/versions) for backups and restoration, and [Test and Publish](/flow-editor/test-and-publish) for validating the resolved draft.
# Connections and Routing
Source: https://docs.phonely.ai/flow-editor/connections-and-routing
Connect blocks across pre-call, live call, and post-call stages and give every result a deliberate path.
Connections control which block can run next. A connection leaves the current block through a **source handle** and enters the next block through a **target handle**. The selected source handle determines which result follows the route.
## Connect blocks on the canvas
1. Hover over a source handle to see what it represents.
2. Drag from the source handle toward the block you want to run next.
3. Drop the connection on a compatible target handle.
While you drag, the editor dims and disables incompatible handles, leaving valid target handles active.
Select the **+** beside a source handle to add and connect a compatible block in one step. Use **Add block** in the canvas toolbar to place a block without connecting it.
A live call continuation or named source handle accepts one destination. Create separate named routes to branch. A post-call source handle can connect to multiple post-call blocks.
## Follow the execution stages
Connections follow the three stages in which a call runs.
**Pre-call:** Runs before **Greeting** starts an inbound call or **Make Call** places an outbound call. Connect pre-call blocks to each other, then connect the final route to the trigger's target handle. **Start Flow** does not support pre-call.
**Live call:** Begins at the trigger and continues through the active conversation until the call ends or transfers.
**Post-call:** Runs after the live conversation. Connect only to post-call target handles; the route cannot return to the conversation.
Where a post-call route begins determines which calls trigger it:
* Attach it to the trigger or an early live call block when it should run for every call that reaches that point.
* Attach it later when it should run only for calls that reach a specific part of the conversation.
* Connect independent post-call actions directly; chain them when one must follow another.
## Choose a route
* **Continuation:** Run the next block after the current block completes without a named result.
* **Conversation outcome:** Route from a Talk exit condition that describes a distinct, observable result. Avoid overlapping conditions or instructions for what the agent should ask next.
* **Data or time result:** Route from a Filter case or Time Filter result when a defined business rule should decide the path.
* **Action result:** Route from results such as [**Success** and **Error**](/blocks/common-settings#error-handling), or another block-specific outcome. Connect every result that requires follow-up or a fallback.
* **Transfer:** Use **Transfer Flow** to move the active conversation to another flow in the same agent, or **Transfer Call** to hand the call to a phone destination.
Transfer Flow keeps the call active, but flow-specific variables from the source flow are not available automatically in the target flow. Import a [Flow Input](/flow-editor/variables#use-flow-inputs) in the target flow to reuse a value the source flow collected, or collect or retrieve required data in the target flow.
## Routing and variable availability
Routing determines which block variables are available downstream. During pre-call and live call, a block can use values created by earlier blocks on a route that reaches it. Values created later or on unrelated routes are unavailable.
When routes rejoin, a variable created on only one branch may be empty for calls that took another branch. Keep the block that uses it on the same branch, create the value on every incoming branch, or handle an empty value.
Post-call blocks use **Post Call Variables** instead of **Call Variables**. They can also reference block variables, but a value may be empty when the call did not pass through the block that created it.
Across a Transfer Flow, an inbound target flow can import a [Flow Input](/flow-editor/variables#use-flow-inputs) to reuse a value the source flow collected earlier in the same call.
Use the variable picker in the destination block to see what can be referenced, then confirm that its incoming routes supply every required value. See [Variables](/flow-editor/variables) for the complete availability model.
## Change a route safely
When restructuring a flow:
1. Remove the current live call connection.
2. Connect the source handle to the new target handle.
3. Confirm required routes and fallbacks remain connected and downstream variables remain available.
Resolve [Flow Checklist](/workflow-checklist) errors and test every affected route before publishing.
Renaming an exit condition normally keeps its connection. Deleting an exit condition or Filter case also deletes the connection from that source handle, so recheck the affected routes after either change.
## Troubleshooting
Start from a source handle and use a target handle that remains active while you drag. If the intended target is dim, the connection is incompatible or that live call source handle already has a destination.
Confirm that its condition can become true, its source handle is connected, and an earlier block does not end or transfer the call first. For Talk, test several natural ways a caller might express the intended outcome.
Make conversation exit conditions or Filter cases more distinct, then confirm that the connection leaves the intended source handle.
Check which live call block its route begins from. Connect a general action to the trigger or an earlier block, but keep a conditional action connected after the event it depends on.
The destination may no longer be downstream from the block that creates the value. Restore the required route, move the dependent block, or use a value available on every incoming route.
# Flow Settings
Source: https://docs.phonely.ai/flow-editor/flow-settings
Configure the shared context, Guidelines, knowledge sources, and switch message for one flow.
Flow Settings control the context and resources shared across one flow. Use them to define the flow's purpose, decide whether it follows the agent's Guidelines, and choose which knowledge sources it can use.
In the Flow Editor, select the flow you want to configure, then select **Flow Settings** (the gear icon) in the top bar.
Changes are saved to the current draft when the dialog closes. They do not affect the live version until you publish the flow.
![Inbound Flow Settings dialog with appointment context, Include Guidelines enabled, all documents and websites selected, and a switch message]()
## Available settings
| Setting | Purpose |
| :---------------------------- | :-------------------------------------------------------------------- |
| **Flow Specific Information** | Context for an inbound flow or call instructions for an outbound flow |
| **Include Guidelines** | Whether the flow uses the agent's Guidelines |
| **Documents** | Uploaded documents the flow can reference |
| **Websites** | Added websites the flow can reference |
| **Switch Message** | Message played when an active call enters an inbound flow |
### Flow Specific Information
Use this field for context that applies throughout the current flow:
* For an **inbound flow**, describe what the flow handles, its limits, and when to route the caller elsewhere.
* For an **outbound flow**, describe the purpose of the call, who the agent is calling, and the desired outcome. Phonely uses this as the call instructions.
Keep agent-wide behavior in Guidelines. Put instructions for a single step in the block that performs it.
For example, an inbound billing flow could include:
> This flow handles billing and subscription questions. Use the billing policy sources selected for this flow. Route refund exceptions to the billing escalation flow.
Avoid copying reference material into this field. Select the relevant documents and websites in Flow Settings instead so the content remains easier to maintain.
### Include Guidelines
Keep **Include Guidelines** enabled to apply the agent's shared behavior, tone, and response rules to this flow. It is enabled by default.
Turn it off only when the flow should operate without those shared instructions. This affects only the current flow; it does not change the agent's Guidelines or other flows. Add any replacement context to **Flow Specific Information** or the relevant blocks.
### Documents and Websites
Documents and Websites determine which existing Knowledge Base sources the flow can reference. Add or update the source in the Knowledge Base, then select it here.
Choose the appropriate scope for each source type:
* Select **All Documents** or **All Websites** to include existing sources and sources added later.
* Select individual sources when the flow should use only a specific set. New sources are not added automatically.
* Clear every selection when the flow should not use that source type.
For a specialized flow, select only relevant sources to reduce unrelated context and make conflicting information easier to identify.
If the list is empty, add a source to the agent's Knowledge Base first, then return to Flow Settings.
### Switch Message
**Switch Message** is a short transition spoken when an active call enters an inbound flow through **Transfer Flow** or a matching **Global Flow** trigger condition. It is not used when the First Flow begins the call; the **Greeting** is used instead.
Keep the message brief and tell the caller what is happening. For example:
> One moment while I pull up our scheduling information.
Switch Message is not available for outbound flows because an outbound flow starts the call instead of receiving a transfer from an active call.
After publishing, use Web Call and enter the flow through **Transfer Flow** or its **Global Flow** trigger condition to hear the message.
## Choose the right level
Place settings and instructions at the narrowest level where they should apply:
| Level | Use it for |
| :-------- | :---------------------------------------------------------------- |
| **Agent** | Behavior shared across all flows, such as tone and response style |
| **Flow** | Context and knowledge sources shared throughout one flow |
| **Block** | The instructions or action for one step in the call |
This avoids duplicated instructions and keeps future changes in one place.
# Test and Publish
Source: https://docs.phonely.ai/flow-editor/test-and-publish
Test focused changes, publish a reviewed flow, and verify the version callers will use.
Test the current draft while editing, then publish and switch the test to the live version. This separates fast feedback on unpublished changes from verification of the version callers will use.
## Understand drafts and versions
| State | What it means |
| :-------------------- | :------------------------------------------------------------------- |
| **Current draft** | Your latest auto-saved edits; does not replace the published version |
| **Saved version** | An optional checkpoint; does not replace the published version |
| **Published version** | The version used by live calls and tests targeting **Live** |
The auto-save message at the bottom of the editor confirms when the current draft was saved. Auto-save does not create or publish a version.
If a flow has no published version, Phonely falls back to its current draft. After the first publish, the latest published version is used until you publish again.
Turning a flow on or off is separate from publishing its current draft. Publishing creates a version and turns the flow on. Turning it off does not delete its draft or published version, and turning it on again does not publish newer draft edits.
## Recommended release process
Make a focused change and wait for auto-save to finish.
Start Web Chat or Web Call from the Flow Editor and exercise the affected paths. The test starts with **Draft** selected. Run a block-level test or **Test from here** when you need more focused feedback.
Resolve every reachable block error in the **Flow Checklist**, then review the affected routes, variables, and Flow Settings.
Select **Publish**. Review any advisory AI findings and fix the ones that apply, or choose **Publish anyway** when the draft is ready. Publishing creates the version used by live calls.
Switch the Test Call panel to **Live** and repeat the important path. For an outbound flow, use **Place Phone Call**.
When a change depends on phone-specific data or behavior, finish with a phone call: use **Place Phone Call** for an outbound flow or call the agent's phone number for an inbound flow.
Tests can trigger connected actions, including messages and external requests. Use test recipients, safe endpoints, and non-production records whenever a tested block or route has side effects.
## Test focused draft changes
Use focused tests for faster feedback while editing. They do not confirm that the flow can be published or that the complete published path works.
| Test | What it tests | Best for |
| :------------------- | :------------------------------------------------------- | :---------------------------------------------------------- |
| **Block-level test** | One supported block using its current configuration | Checking the block's inputs and result with sample values |
| **Test from here** | The current draft from a selected live-call block onward | Checking a downstream path without replaying earlier blocks |
### Test a block in isolation
Some blocks include a **Test** section in their configuration panel. Enter safe sample values for the variables used by the block, run the test, and inspect the resolved input and result.
Some blocks determine their output variables from the test result. For these blocks, run a successful test before using returned values in downstream blocks, and test again whenever the output structure changes.
A block-level test does not run the block's incoming or outgoing connections.
### Test from a selected block
**Test from here** is useful when the changed block is deep inside a long inbound flow.
1. Select the play icon on the live-call block where the test should begin.
2. Choose **Voice** or **Chat**.
3. Enter representative values for the available variables the test needs.
4. Select **Start test**.
5. Continue in the **Test Call** side panel and verify the downstream route.
The dialog shows only variables that can be available before the selected block. Blank values are not passed into the test. If no earlier values are needed, it displays **No variables needed for this block**.
Test from here applies the draft override to the selected flow. If the route enters another flow, that flow uses its latest published version, or its draft if it has never been published.
A successful partial test does not confirm that blocks before the starting point produce the expected values, that alternate routes work, or that the draft has been published. Always complete the normal release process.
## Review and publish
Open the [Flow Checklist](/workflow-checklist) and resolve every error on a block reachable from the flow's entry point. Unconnected blocks parked on the canvas are not part of the executable flow and do not block publishing. Then review the affected routes, variable references, and [Flow Settings](/flow-editor/flow-settings).
Publishing can be unavailable when the flow has block errors, a block is not included in the current plan, your role cannot edit the flow, or a newer collaboration update must be resolved.
Select the main **Publish** button to run a quick AI review. Its findings are advisory: inspect them in the Flow Checklist, ask Ask AI to help, or choose **Publish anyway** after deciding the draft is ready. If the review is unavailable, publishing continues without it. Deterministic block errors still prevent publishing.
Publishing creates a version from the current draft and makes it live. The adjacent menu provides related version actions:
* **Save as Version** creates a checkpoint without changing the published version.
* **Version History** opens saved and published versions for review or restoration.
The **Publish** button is disabled when the current draft matches the published version. After publishing, switch the browser test to **Live** or run the appropriate phone test so you are checking the version callers will use.
See [Flow Versions](/flow-editor/versions) for checkpoints and restoration, and [Resolve Remote Flow Updates](/flow-editor/collaboration) for resolving newer remote updates before publishing.
## Test the complete flow
Web Chat and Web Call begin at the agent's First Flow unless a selected flow or block provides a draft override. Choose the test based on the behavior you need to verify.
| Test | How it runs | Best for |
| :--------------------- | :--------------------------- | :-------------------------------------------------------------------------------- |
| **Web Chat** | In-browser chat | Quickly verify prompts, variables, routing, and connected actions across the flow |
| **Web Call** | In-browser voice | Verify the same flow behavior plus voice, tone, pacing, and interruptions |
| **Place Phone Call** | Phonely calls a test number | Verify outbound delivery, telephony behavior, and phone-derived data |
| **Inbound phone call** | A test phone calls the agent | Verify caller data, transfers, and end-to-end telephony behavior |
### Web Chat and Web Call
Use Web Chat for a quick functional pass through the flow. Use Web Call when you also need to evaluate the voice, tone, pacing, and interruption behavior.
For an inbound flow, select the chat icon on the right side of **Test agent** to start Web Chat. Select the main area of the same button to start Web Call. Both open in the **Test Call** tab of the side panel.
When started from the Flow Editor, both tests begin with **Draft** selected and use the current draft of the selected flow. Use the **Draft / Live** control in the Test Call panel to switch targets; switching restarts the test. **Live** uses the published version real callers receive. If the flow has never been published, Phonely falls back to its draft.
The **Ask AI** tab can inspect and help change the agent, but it is separate from the tests in **Test Call**.
Browser-based tests do not always reproduce phone-network data or behavior, such as a real caller number or transfer timing. Use a phone call when the tested behavior depends on that information.
### Run a phone test
**Outbound:** Open the outbound flow and select **Place Phone Call** in the top bar. Enter representative input values, including a destination number you control, then run the test. This uses the latest published version, falling back to the draft only when the flow has never been published.
**Inbound:** From a phone you control, call the number assigned to the agent. Start at the greeting and exercise the affected path.
# Variables
Source: https://docs.phonely.ai/flow-editor/variables
Use fixed and changing values to make a flow respond to each call.
Variables are named values that a flow can use. Some stay fixed, while others change with the caller, the route, or a block's result. They let the flow carry information forward and respond to the current call without entering the same data again.
For example, a Talk block can collect the caller's name, and a later block can use that name in a message or an API request.
## Use a variable
1. Open a block and focus a field that supports variables. The **Available Variables** panel opens with the list already filtered for that block.
2. Select a variable from the list. Phonely adds it to the field.
![Booking Failed block with its message field focused and the Available Variables panel showing call, custom, Auto-Gather, and earlier block variable groups]()
When the block runs, it uses the current value of the variable. Typing the variable's name as normal text does not use its value.
In supported text fields, you can also type `@` and select a variable from the matching results.
If two variables have similar names, check the group they appear under to make sure you select the intended value.
## Where variables come from
The **Available Variables** panel groups variables by their source:
* **A block's variables** appear under its name and contain information that block collected or returned.
* **Call Variables** contain information about the current call, such as phone numbers and call metadata.
* **Custom Variables** contain reusable values you define for the flow.
* **Post Call Variables** contain finalized information such as the transcript, summary, outcome, recording link, and call duration.
* **Outbound Variables** contain values supplied when an outbound call starts.
* **Auto-Gather Variables** provide a shorter way for supported actions to collect information from the caller.
* **Flow Inputs** contain values collected earlier in the same call that you import from another flow for reuse after a transfer.
Some fields also show knowledge-base content when you type `@`. Knowledge-base content gives the agent information to reference; it does not store a value that moves through the flow.
## Use variables from blocks
Blocks are the main source of values that change while a flow runs. Their variables are created in three ways:
* **Defined by the configuration:** In Talk and Collect, you name the information the block should collect. Google Sheets uses the selected sheet's columns for its Search a Row variables.
* **Provided by the action:** Some actions have known results. For example, Google Calendar's Check Availability action provides **Available Appointment Slots**.
* **Discovered from test data:** API Request and Code create variables from a successful test result. Webhook creates variables from the fields in a received test payload.
In each case, the variables appear under the block's name and can be selected in blocks that run later.
Tests can also fill variables whose names are already known. A Google Sheets Search a Row test adds the matched row values to its column variables. A Google Calendar availability test fills **Available Appointment Slots**.
### Open a variable's source block
To inspect where a value comes from, click its variable chip in an editor text field. For a valid variable produced by an upstream block on the current canvas, Phonely moves to that block and opens its settings. You can also focus the chip with the keyboard and press `Enter` or `Space`.
This shortcut is for block-produced variables. Custom Variables, Auto-Gather Variables, knowledge-base references, and Flow Inputs do not navigate to a source block. An invalid variable opens the replacement dialog instead. Source-block navigation is unavailable in a proposal preview.
### Collect information from the caller
Add a variable to a Talk or Collect block when the block should ask the caller for information. Give the variable a clear name, choose its type, and describe what the agent should collect.
* Enable **Required** when the block must collect the value before it finishes.
* Enable **Confirm** when the caller should verify a required value.
* Enable **Spell Back** when the agent should read a confirmed value character by character.
Confirmation is useful for information where a mistake matters, such as an email address or reference number. Using it for every value can make the conversation repetitive.
### Create variables from test data
For API Request and Code:
1. Configure the block with safe sample data.
2. Run its block-level test.
3. Check the result.
4. Open a later block and select the result you need from **Available Variables**.
For Webhook, start its test and send a sample payload to the displayed webhook URL. Phonely creates variables from the fields it receives.
These variables match the structure of the successful test data. If that structure changes, test the block again and check the later blocks that use its variables.
See [API Request](/blocks/api-request) for request-specific configuration and testing.
## Use Auto-Gather Variables
An **Auto-Gather Variable** is a shortcut for collecting information without adding a separate Talk or Collect block. When a supported action needs the value, the agent asks the caller for it before the action runs.
Use it for a simple value needed mainly by that action. Prefer a Talk or Collect block when collecting the information should be a clear part of the conversation or when several later blocks need the value.
## Use Custom Variables
A **Custom Variable** stores a fixed value with the flow so you can use it in several places. It is useful for repeated configuration such as an API key, account ID, webhook URL, or business constant.
For example, place an API key in a Custom Variable and select it wherever an API Request needs that key. If the key changes, update the Custom Variable instead of editing every request.
Select **+** beside **Custom Variables**, choose **Custom Variable**, then enter its name and value.
Enter API keys and other secrets directly in the **Add Custom Variable** dialog. Do not include secret values in an Ask AI prompt.
### Advanced input sources
The **Add Custom Variable** dialog also supports these specialized inputs:
A Runtime Variable receives its value when a Phonely Web SDK call starts. After creating it, copy the generated Runtime Variable ID and use that ID as the input key in the Web SDK call.
Runtime Variables are currently available only for Phonely Web SDK calls. Their definitions cannot be edited after creation; delete and recreate one if its setup is incorrect.
A SIP Header variable reads a custom header sent with an incoming SIP call. Enter the header name used by the caller's SIP provider. It must begin with `x-`, such as `x-customer-id`.
Phonely reads the matching value from the call metadata. SIP Header definitions cannot be edited after creation; delete and recreate one if its setup is incorrect.
## Use Outbound Variables
In an outbound flow, select **+** beside **Outbound Variables** to add values that will be supplied when a call starts. Create them before using them in later blocks, and give them clear names that are easy to map from the call source.
## Use Flow Inputs
A **Flow Input** reuses a value collected earlier in the same call after the conversation transfers into another flow. A transfer keeps the call active but does not automatically carry a source flow's variables into the target flow, so a Flow Input lets the target flow reference a value the earlier flow already collected.
Flow Inputs are available in inbound flows. Select **+** beside **Flow Inputs** and choose the source variable to import, searching by flow, block, or variable. The imported value is available to later blocks in the target flow.
A Flow Input reflects the value collected earlier in the same call. If the call did not pass through the block that collects it, the value is empty. Design the target flow to handle a missing value, or collect it again when it is required.
## When variables are available
The **Available Variables** panel already filters the list for the selected block. These rules explain why a variable may not appear or may have no value:
* A value created by a block can be used only after that block runs.
* If a call takes a different route and skips the block that creates a value, a later shared block may receive no value.
* Outbound Variables appear only in outbound flows.
* Post-call blocks use **Post Call Variables** for finalized call information.
* Transfer Flow keeps the call active, but variables created in the source flow are not automatically available in the target flow. Import a **Flow Input** in the target flow to reuse a value the source flow collected.
If a later block needs a value on every route, collect or create it on every route before that block, or make the block handle a missing value.
See [Connections and Routing](/flow-editor/connections-and-routing) when availability depends on how blocks are connected.
## Variable types
Phonely uses two kinds of type information. One guides how the agent collects information; the other records whether a variable's value is text, a number, a boolean, or structured data.
### Types for collected information
When you add a variable to Talk or Collect, or create an Auto-Gather Variable, choose the type of information the agent should collect. The type helps the agent interpret, format, and check the caller's answer.
Use **Text** for an open-ended answer. When the format matters, choose a more specific type such as **Number**, **Age**, **Date**, **Time**, **Name**, **Email**, **Phone**, **URL**, **Address**, **Zipcode**, **Currency**, **Percentage**, or **Duration**.
Use these options when the built-in formats are not enough:
| Type | Use it when |
| :--------- | :--------------------------------------------------------------- |
| **Regex** | The value must match a specific pattern. |
| **Enum** | The value must be one of a defined set of options. |
| **Custom** | The expected format is best explained with a written definition. |
Choose the type that best describes the expected answer. When the format matters, test valid, invalid, and corrected answers.
These collection types describe the meaning and expected format of an answer. They are separate from the data types used for block results.
### Timezone sets the expected country format
**Zipcode** and **Phone** do not use one fixed format. Phonely derives the agent's country from the timezone in **Settings**, then tells the agent which national format to expect and to check the answer against.
An agent set to a US timezone asks for and validates a 5-digit ZIP code. An agent set to `Australia/Sydney` asks for a 4-digit postcode instead. This applies even when the caller is in a different country than the agent.
| Country from timezone | Zipcode | Phone |
| :-------------------------------- | :------------------------------------------------------------------------- | :------------------------------------------------- |
| United States (also the fallback) | 5-digit ZIP code, such as `90210` | 10 digits, such as `4123456789` |
| Australia | 4-digit postcode, such as `3000` | 10 digits starting with `0`, such as `0412345678` |
| Canada | 6-character postal code alternating letter and digit, such as `K1A 0B4` | 10 digits, such as `4123456789` |
| United Kingdom | Postcode with area, district, and a 3-character ending, such as `SW1A 1AA` | 11 digits starting with `0`, such as `07123456789` |
Any timezone outside these countries falls back to the US formats.
If an agent asks for the wrong kind of postcode or rejects a valid one, check the agent's timezone first. A timezone set to the wrong country is the most common cause, and it looks like the agent inventing a format. Open **Settings** and confirm the timezone matches the country your callers are in.
When you need a format that these country defaults do not produce, use **Regex** or **Custom** to define the expected pattern yourself.
### Data types for variable values
System-defined variables and values returned by blocks can have a data type of `string`, `number`, `boolean`, `object`, `array`, or `null`. Phonely determines the data type from the variable's definition or a successful block test; you do not select it manually. For example, **Live Call Duration (s)** is a number, **AI Success** is a boolean, and **Topics** is an array. The **Available Variables** panel displays the type beside non-string values.
The data type matters when you pass a value to another system. For example, an API Request or Webhook JSON body can keep `42` as a number, `false` as a boolean, or a complete object or array as structured data instead of converting it to text.
Use an object or array as the complete value of a compatible JSON field, or select one of its nested values. Objects and arrays cannot be mixed into a text sentence, URL, header, or query parameter.
During a block-level test, enter test values that match the type shown for each variable. This lets the test reproduce how the values will be passed when the flow runs.
## Resolve invalid variables
A variable becomes invalid when its value is no longer available to a block. This can happen after you delete the block that created it, change a connection, remove a result field, or delete the variable.
For an isolated reference, open the affected block, remove the invalid variable, and select the intended variable from **Available Variables**. If the intended variable is missing, check the route or recreate the value before selecting a replacement.
When the same invalid reference appears in several fields or blocks, select **Replace Invalid Variables** from the canvas toolbar. The dialog lists the affected blocks and replaces every use of that reference at once. Choose a replacement only when it has the same meaning and is available to every affected block.
## Test and inspect variables
When testing a flow, confirm that:
* the call takes the route that creates the value;
* the agent collects the expected information;
* later blocks receive the correct value; and
* routes that do not create the value still behave safely.
In Web Call or Web Chat, hover over or focus the variable chip below an assistant response to see the values stored during that turn. This is useful for a quick check while testing.
After a completed test or live call, open **Call Details**, select **Blocks**, and expand the relevant block or response. The **Stored Variables** section shows the most recent value recorded for each variable at that point in the execution, making this the clearer view when you need to trace a variable to a block.
Web Call and Web Chat do not always provide information that exists only on a real phone call. Complete a phone test when the flow depends on telephony data such as a caller number or transfer timing.
## Troubleshooting
Confirm that the block creating it runs earlier on a route that reaches the selected block. Outbound Variables appear only in outbound flows, and Post Call Variables appear only in post-call blocks.
Check whether those calls passed through the block that creates the value. Create the value on every relevant route, move the block that uses it, or handle the missing value.
Choose a more suitable type and make the description more precise. For strict formats, use Regex, Enum, or Custom, then test valid, invalid, and corrected answers.
Check whether a connection or the block that created it changed. Repair the route when appropriate. Otherwise, remove the invalid reference and select an available variable. Use **Replace Invalid Variables** when the same reference needs to be updated in several blocks.
Browser tests do not always have real telephony information. Provide a test value where supported and verify the final behavior with a phone call.
# Flow Versions
Source: https://docs.phonely.ai/flow-editor/versions
Save checkpoints, inspect earlier flow configurations, and safely restore a version.
A version is a read-only snapshot of a flow. Use versions to preserve meaningful checkpoints, compare earlier configurations, and restore a known design without changing the published version.
## Create a version
| Action | Result | Live effect |
| :------------------ | :---------------------------------------- | :------------------------- |
| **Auto-save** | Updates the current draft | None |
| **Save as Version** | Creates a numbered checkpoint | None |
| **Publish** | Creates a numbered version from the draft | Makes the new version live |
Select the main **Publish** button to publish the current draft. To create a checkpoint without changing the published version, open the adjacent menu and select **Save as Version**.
Each version receives a number and an initial name such as `Version 4`. Phonely also adds initial release notes; when it can compare the draft with the published version, those notes summarize the detected changes. Review the name and notes when the version marks an important release or decision.
Save a checkpoint when you may need to explain or return to the current design, such as:
* before restructuring a large route;
* after a reviewed milestone; or
* before restoring a version or applying remote updates when the current draft must be preserved.
Avoid creating a version for every minor edit. Auto-save already saves the current draft.
## Preview an earlier version
Open the menu beside **Publish** and select **Version History**. The side panel lists **Current Draft** and every numbered version. Each version shows its name, notes, author, and time; a **Published** badge marks the current published version. **Current Draft** is the latest auto-saved flow and is not numbered.
Version History puts the editor into read-only review mode. Select a version to preview its saved canvas, then select a block to inspect its saved configuration. Previewing never changes the current draft.
Select **Current Draft** to view the draft while keeping Version History open, or close the panel to resume editing.
While previewing a version, you can select one or more of its blocks and copy them, then paste the copied blocks into the current draft. The preview stays read-only, so the version itself is never changed.
### Compare two versions
Open a version's menu and select **Compare** to enter comparison mode. Use the **From** and **To** selectors to choose the two versions to compare; each selector is searchable, and the current draft is available alongside the numbered versions. Comparison mode is read-only and highlights the field-level differences between the two selected snapshots without changing the current draft.
Compare routes, block settings, variables, and Flow Settings—not only block names or canvas layout. A configuration change can alter behavior without moving a block.
## Review the changelog
Select **View Full Changelog** in Version History to review all numbered versions. Each entry shows its name, release notes, author, time, and published status.
If you can manage the flow, select a version name or its release notes to edit them. Use a descriptive name, and review automatically generated notes before relying on them for an important change.
## Restore an earlier version
Restoring replaces the current draft with the selected snapshot. It does not change the published version until you publish the restored draft.
This cannot be undone. Save the current draft as a version first if you may need it later.
1. Preview the version and inspect its routes, variables, and settings.
2. Select **Restore** from the version menu or preview banner and confirm.
3. Review and test the restored draft. Publish it only when ready.
Resolve newer remote updates from the collaboration banner before restoring.
## Rename or delete a version
Open a version's menu in Version History to:
* **Rename** its name and update its release notes; or
* **Delete** an unneeded version.
You can also edit names and release notes directly in the full changelog. These actions require permission to manage the flow; other team members can still preview versions and read the changelog.
The current published version cannot be deleted. Deleting another version is permanent and does not change the current draft or published version.
See [Test and Publish](/flow-editor/test-and-publish) for validating a restored draft, and [Resolve Remote Flow Updates](/flow-editor/collaboration) for preserving work when newer remote updates are available.
# Home
Source: https://docs.phonely.ai/get-started/home-overview
Use Home to ask Ask AI for help and review call activity across selected agents and dates.
Home combines two starting points: an Ask AI prompt for product or agent work, and an overview of recent call activity. Use it when you want to begin with a question or check activity across several agents without opening each agent first.
![Home with the Ask AI prompt and the beginning of the call activity overview]()
## Ask AI from Home
The prompt under **What can Phonely do for you?** opens **Ask AI** in the app side panel and sends your request. You can type a request, attach one supported file, or begin with one of the suggested prompts.
Ask AI can help with different kinds of work, so make the requested outcome explicit. For example, ask it to investigate a call pattern, explain a product concept, or help change an agent. Review proposed changes before relying on them in a live call experience.
## Set the overview scope
The overview uses date and agent filters. A change to either filter updates the metrics, recent calls, active calls, and call-volume chart.
Home starts with **Last 7 days** and all agents you can access selected. If you have access to agents across multiple organizations, narrow the selection before interpreting the totals.
### Choose a date range
Select **Today**, **Last 7 days**, **Last 14 days**, **Last 30 days**, or **Last 90 days**. You can also choose a custom range.
### Choose agents
Use the agent selector to include one or more agents. You can search by organization, agent name, or business phone number, then select or deselect all agents in the displayed results. The overview shows zeroed or empty states when no agent is selected.
## Read the summary metrics
Home displays these summary cards for the selected scope:
| Card | What it summarizes | Where it leads |
| :----------------- | :----------------------------------------------- | :---------------- |
| **Calls Answered** | Answered-call count | Call History |
| **Minutes** | Total call minutes | Performance |
| **Cost Saved** | Estimated savings based on selected call minutes | Plan and Billing |
| **Resolved** | Calls matching the outcomes selected as resolved | Outcome selection |
**Cost Saved** is an estimate for the selected scope. Use **Plan and Billing** for actual billing information.
Select **Resolved** to choose which observed call outcomes count toward that card. This changes the Home summary for the current view; it does not rename or reconfigure outcomes on your agents. If no outcomes are selected, the card prompts you to set them instead of showing a resolved total.
## Review recent and active calls
**Recent Calls** lists recent calls in the selected scope with their direction, phone number, outcome, sentiment indicator, duration, and relative time. Select a call to open its details, or select **View all** to open Call History.
The active-calls control groups calls currently in progress by agent and identifies calls in conversation or warm transfer. Select a call to inspect its details without leaving Home.
## Compare call volume
**Call Volume** plots inbound and outbound calls over the selected period. Use **View analytics** when you need the deeper Performance view.
![Home overview metrics, recent calls, and call volume for the selected date range and agents]()
# Introduction
Source: https://docs.phonely.ai/get-started/introduction
Learn what you can do with Phonely and where to begin.
## What is Phonely?
![Agent Design overview showing Voice, Guidelines, Knowledge Base, and the starter call flow]()
Phonely is a platform for building voice AI agents that handle phone calls. You can design conversations visually, connect business tools, test the experience, and review calls without writing the whole system from scratch.
* Build inbound and outbound call experiences
* Route calls and transfer callers based on the rules you define
* Connect the agent to calendars, CRMs, and APIs
* Review calls and performance after your agents begin handling conversations
Want to jump right in? [Get started with Quick Start](/get-started/quick-start).
## What you can do
Design what the agent should say and do, including decisions, integrations, transfers, and call endings.
Test agent changes and compare alternatives before deciding what should handle production calls.
Reach customers for reminders, follow-ups, confirmations, and other repeatable call tasks.
Inspect completed calls and use performance views to decide what to improve next.
## Popular use cases
Answer common questions and route callers to the right person when human help is needed.
Collect lead information, qualify requests, and transfer appropriate callers to your team.
Connect a scheduling tool so callers can book or manage appointments during a conversation.
Create outbound call experiences for reminders, confirmations, and follow-up tasks.
## About Phonely
Phonely is built by a team of AI researchers and audio engineers. Phonely is backed by Y Combinator. [See open roles](https://www.ycombinator.com/companies/phonely/jobs).
![The Phonely team]()
Customize and test the first agent created during onboarding.
## Frequently asked questions
You can design calls visually without code. For advanced use cases, a flow can also connect to APIs and other business tools.
Add reference material to the agent's knowledge base, and use guidelines to define behavior that should apply across its conversations.
Yes. Create an outbound campaign and connect it to the call experience you want the agent to use. See [Outbound Campaigns](/outboundcalling/createaoutboundcallingcampaign).
Use [Call History](/call-history-ai-analytics/call-history-ai-analytics) to inspect completed calls, then use the performance views when you need broader trends.
# Navigation and Search
Source: https://docs.phonely.ai/get-started/navigation-and-shortcuts
Find pages, agents, and support actions, then keep regular destinations in the sidebar.
Use the sidebar for destinations you open regularly. Use global search when you need another page or want to switch agents without navigating back through the app.
## Search Phonely
Press `Command + K` on macOS or `Ctrl + K` on Windows to open global search. Depending on the page, it appears beneath the Ask AI field or in a centered search window.
Use the keyboard shortcut or select the available search field.
Enter a page name, related keyword, agent name, organization name, or agent phone number.
Select a result with the pointer, or use the arrow keys and press `Enter`.
![Global search showing Ask AI, page, and agent results]()
Page results are grouped by tasks such as building, optimizing, and reviewing your agent. Search also includes destinations hidden from your sidebar and support actions such as **Report issue**.
The first result can send the text to Ask AI instead. Choose a page or agent result when you know where you want to go; choose **Ask AI about...** when you want Phonely to interpret a question or task. See [Ask AI](/key-concepts/ask-ai) for how context and changes are handled.
When you need to report a problem or share an idea, search for the issue and select **Report issue**. Phonely can use the search text to start the report. See [Report Issues and Ideas](/get-started/report-issues-and-ideas) for what to include.
Use the arrow keys to move through results, `Enter` to open the selected result, and `Escape` to close search.
## Switch agents
Search can return agents as well as pages. Select an agent result to switch the active agent. When you open a page result, Phonely keeps the current agent context where that page applies to an agent.
For browsing agents directly, open the agent switcher in the app bar. You can search by agent name, organization, or phone number, and select **Create Agent** at the bottom of the list when you need another agent.
## Customize the sidebar
Open **Customize Sidebar** from global search, or select the pencil-and-ruler control in the sidebar footer.
The customization window groups available items into **Build**, **Optimize**, **Review**, and **Shortcuts**. Availability can vary with role and workspace context.
Search for **Customize Sidebar** or use the pencil-and-ruler control in the sidebar footer.
Enable the destinations you want pinned and disable the ones you do not need in regular navigation.
Select **Save** to apply the draft. Select **Cancel** to discard it.
Hiding a destination from the sidebar does not remove it from the product. Use global search to reach it later.
## Add an external shortcut
External shortcuts keep frequently used tools or team resources beside your Phonely pages.
Scroll to the **Shortcuts** group and select **Add custom shortcut**.
Enter a shortcut name and a full URL beginning with `https://`, then select **Add**.
Confirm that the new shortcut is enabled, then select **Save**.
The saved destination opens as an external link. Only add URLs you trust.
## Keyboard shortcuts
| Action | macOS | Windows |
| ----------------------- | ------------- | ---------- |
| Open global search | `Command + K` | `Ctrl + K` |
| Open Ask AI | `Command + /` | `Ctrl + /` |
| Report an issue or idea | `Command + B` | `Ctrl + B` |
# Quick Start
Source: https://docs.phonely.ai/get-started/quick-start
Customize the agent and starter flow created during onboarding, then test and improve your first call experience.
Onboarding creates your organization, first agent, and a starter flow, then gives you a chance to call and customize that agent. Quick Start begins from that existing setup: your next job is to make the starter agent accurate for your business and reliable for one useful call experience.
## Understand the starting point
Your first agent includes a flow that can:
* Answer business questions using connected knowledge
* Collect the caller's name, phone number, and reason for calling when follow-up is needed
* End the call after the caller has no more questions
* Send a post-call email notification to the email used during onboarding
Treat this as a working starting point, not a finished production agent. Review every instruction, destination, and fallback before using it with customers.
You do not need to create another agent just to follow this guide. If you are joining an existing workspace, select the agent you want to configure before continuing.
## Learn the parts of an agent
Phonely combines several systems during a call:
Choose the agent's voice and define the behavior, goals, and limits that apply across calls.
Add focused, up-to-date business information the agent can use to answer customer questions.
Design preparation, conversation steps, decisions, integrations, transfers, and follow-up actions for each call.
The separation matters: guidelines control reusable behavior, the knowledge base supplies business facts, and flows coordinate what happens before, during, and after a call.
## 1. Decide what the first call should accomplish
Choose one outcome that matters to your business, such as answering common questions, qualifying a lead, booking an appointment, taking a message, or routing a caller.
Write down:
* What the caller needs
* What the agent must know or collect
* What a successful ending looks like
* What should happen when the agent cannot complete the request
Use [Plan your Phonely agent](/key-concepts/plan-your-agent) when you need help mapping the call before editing the flow.
## 2. Add accurate business knowledge
Review anything added to the knowledge base during onboarding, then add the documents, written information, or website pages needed for the first call goal. Remove irrelevant or outdated sources so the agent is not expected to choose between conflicting information.
![Knowledge Base showing an active demo document, source filters, and add-source controls]()
Put business facts in the knowledge base rather than copying them into every flow block. Put tone, objectives, and restrictions in guidelines.
## 3. Review the agent's voice and Guidelines
Listen to the agent's current voice and confirm it fits the callers and situation you expect. Then review the agent's Guidelines for:
* The role the agent should perform
* How it should communicate
* What it must or must not do
* When it should transfer, take a message, or use another fallback
Keep shared behavior here. Instructions that apply only at one point in a call belong in that flow block instead.
## 4. Customize the starter flow
Open **Call Flows**, select the starter flow, and trace it from the incoming-call trigger to each ending. Update the smallest complete path for your first call goal before adding more branches.
For each block, confirm:
1. Its purpose is clear.
2. Its instructions use the correct knowledge and variables.
3. Every possible result has a useful next step.
4. Failure and fallback paths are explicit.
5. The call ends or transfers deliberately.
Ask AI can help explain or change the active flow. Describe the intended caller experience and review proposed edits before relying on them.
### Optional: test part of a complex flow
For a long or complex flow, use **Test from here** on a block when repeatedly starting from the trigger would slow down iteration. It exercises the current draft from that point without changing the published version handling live calls. Supply representative test values for any variables the block needs, then run the partial path in chat or talk mode.
This is a focused debugging tool rather than the main release test. It does not prove that the full flow can be published or that the experience matches a real phone call. See [Test and Publish](/flow-editor/test-and-publish#test-from-a-selected-block) for the full procedure.
## 5. Test the draft
Your edits are saved as a draft while you work. Start Web Call or Web Chat from the Flow Editor to test that draft before publishing it. If the app side panel is already open, select **Test Call** and choose **Talk** or **Chat**.
Use Web Chat for a quick functional pass through prompts, variables, routes, and connected actions. Use Web Call when you also need to evaluate voice, tone, pacing, and interruptions.
## 6. Publish and verify the live version
Resolve reachable block errors in the **Flow Checklist**, then select **Publish**. Review any advisory findings and publish the draft when it is ready to become the version used by callers.
In the Test Call panel, switch from **Draft** to **Live** and repeat the important path. Switching targets restarts the test. If a flow has never been published, Phonely falls back to its draft. **Ask AI** shares the side panel with Test Call but is a separate tool.
Begin with the expected successful conversation, then try important variations:
* The caller asks a question the knowledge base does not answer.
* Required information is missing or unclear.
* The caller changes direction midway through the call.
* An integration returns no useful result.
* The call needs to transfer or end early.
Browser-based tests are useful for conversation flow, branches, prompts, and many live actions. Use a real inbound or outbound phone test when the behavior depends on the phone network, audio, transfers, or phone-derived call information.
## 7. Review and improve
After test or real calls are available, use [Call History](/call-history-ai-analytics/call-history-ai-analytics) to compare what happened with the outcome you planned. Check the conversation, path, collected information, and final result.
Change the correct layer:
* Update the knowledge base when the agent lacked or used incorrect business information.
* Update Guidelines when its general behavior was wrong.
* Update the flow when the sequence, decision, integration, transfer, or ending was wrong.
Make one meaningful change at a time and test the affected path again.
## Continue building
Learn how blocks, connections, versions, and call paths work together.
Review the voice, Guidelines, knowledge, and shared settings that shape the agent.
Use call outcomes and trends to decide what to improve after your first experience is reliable.
# Report Issues and Ideas
Source: https://docs.phonely.ai/get-started/report-issues-and-ideas
Send product feedback with the context Phonely needs to investigate it.
Use **Report issue** to tell Phonely about a product problem, confusing behavior, performance concern, billing issue, or idea. Reports include useful context from the part of the app where you open them.
## Open a report
You can open **Report an issue or idea** in several ways:
* Select **Report issue** from the app sidebar or profile menu.
* Open [global search](/get-started/navigation-and-shortcuts), search for the problem or reporting action, and select **Report issue**.
* Press `Command + B` on macOS or `Ctrl + B` on Windows.
* Select **Report issue** from an application error screen when the option is available.
* Report an Ask AI conversation or response from the assistant panel.
## Describe the issue or idea
Choose the type that best matches your report:
| Type | Use it for |
| ---------------------- | -------------------------------------------- |
| **Bug** | Product behavior that is broken or incorrect |
| **Platform idea** | A product improvement or new capability |
| **Confusing behavior** | An experience that works but is unclear |
| **Performance** | Slow, delayed, or unresponsive behavior |
| **Billing** | A billing-related question or problem |
| **Other** | Feedback that does not fit another type |
Select **Low**, **Medium**, or **High** based on the impact on your work, then describe what happened or what you would like to improve. The description is required.
For a problem, open **Add details for investigation** when steps to reproduce, the expected behavior, or the actual result would help explain it. For an idea, describe the improvement and why it would be useful.
## Attach supporting media
You can browse for files, drag them into the report, or paste a screenshot. A report can include up to three attachments:
* PNG, JPEG, WebP, or GIF images up to 25 MB each
* MP4, MOV, or WebM videos up to 100 MB each
Wait for each upload to finish before sending the report. Remove any attachment that fails to upload.
Remove credentials and customer information that is not needed to investigate the report before attaching or entering it.
## Understand the included context
Phonely includes the current page and basic device context with the report. Reports opened from a supported feature can also include diagnostic context for that feature, helping the team investigate without requiring you to copy technical identifiers manually.
This context supplements your description. Include the visible symptom, the outcome you expected, and any timing or scope that would help reproduce the problem.
## Report an Ask AI issue
Open **More Ask AI options** and select **Report Ask AI issue** to report the current conversation. To report one response, point to the response and select the bug icon beneath it. Phonely includes the relevant conversation diagnostics with either report.
If the support team asks for identifiers separately, open **More Ask AI options** and select **Copy diagnostic details**. See [Ask AI](/key-concepts/ask-ai) for more about assistant conversations and context.
## After you send the report
A successful submission shows a report number. The Phonely team reviews the submitted details and may follow up when more information is needed.
# Gmail
Source: https://docs.phonely.ai/integrations/gmail
Send email from a connected Gmail account during or after a call.
Use [Send Email](/blocks/communication-blocks/send-email) for Phonely's built-in email action. Use [Email & SMS Notification](/blocks/communication-blocks/email-sms-notification) when you want Phonely's call summary sent automatically after a call.
## Connect Gmail
Open the block's **Setup** step:
1. Select an existing Gmail account under **Connection**, or select **Add Connection** and authorize another account.
2. Continue to **Configure**.
The selected account sends the email. Its connection belongs to the agent and can be reused across flows. Other agents need their own connection.
## Configure the email
| Setting | Purpose |
| :---------- | :----------------------------- |
| **To** | One or more primary recipients |
| **Subject** | The email subject |
| **Body** | The email message |
All three fields are required. To, Subject, and Body can use values from [Available Variables](/flow-editor/variables). Each recipient must resolve to a valid email address when the block runs.
### Advanced settings
| Setting | Purpose |
| :------------ | :------------------------------------------------------------ |
| **Body Type** | Send the body as **Plain Text** or **HTML** |
| **Cc** | Add recipients visible to everyone receiving the email |
| **Bcc** | Add recipients hidden from the other recipients |
| **From Name** | Change the sender name shown with the connected Gmail address |
| **Reply To** | Send replies to a different email address |
Cc, Bcc, From Name, and Reply To can also use variables available before the block runs. **From Name** does not change the Gmail address that sends the message. Choose HTML only when the Body contains HTML markup.
## Choose when to send it
| Stage | When it runs |
| :------------ | :----------------------------------------------------------- |
| **Live call** | When the active call reaches the block |
| **Post-call** | After a call that reached the connected live-call block ends |
Place Gmail after the blocks that provide any recipient addresses or content values it uses. Use post-call when the email is not needed during the conversation, so the caller does not wait for it to send.
In **Live Call**, Gmail also supports interim messages and call outcome tagging. See [Common Block Settings](/blocks/common-settings).
## Test Gmail
The block test resolves the configured fields and shows the email in **Email Preview** before sending it from the selected Gmail account:
1. Open **Test** and enter safe sample values for any variables.
2. Review the recipients, Reply To, subject, Body Type, and body in **Email Preview**.
3. Select **Test**.
4. Confirm that the email arrives with the expected sender, content, and formatting.
Then test the complete flow and confirm that its variables resolve correctly. Review Gmail in the action trace or **Call Details** to confirm its execution.
Testing Gmail sends a real email from the selected account. Use recipients and content that are safe for testing.
## Troubleshooting
Confirm that the intended account is selected under **Connection** and reconnect it if its access changed. Review **Email Preview** for valid recipients, then check the recipient's spam folder and the connected account's sent mail. Provider restrictions or sending limits can also prevent delivery.
Return to **Setup** and select the intended Gmail connection. **From Name** changes only the displayed sender name; it does not change the connected Gmail address. Clear or correct **Reply To** if replies should return to the sending account.
Confirm that the variable is available before the Gmail block runs. Test the upstream path that creates it, then review its resolved value in **Email Preview** before testing again.
Set **Body Type** to **HTML** and confirm that the Body contains valid HTML. Use **Plain Text** when the body should not be interpreted as markup.
# Google Calendar
Source: https://docs.phonely.ai/integrations/google-calendar
Check availability and create appointments during a live call.
| Action | Use it to | Result |
| :------------------------------------- | :------------------------------------------------------------- | :-------------------------------------------------------- |
| **Check Availability** | Find open slots that fit your calendar and configured schedule | Provides **Available Appointment Slots** for later blocks |
| Create an Appointment | Add an event at a known start and end time | Creates the event and sends an invitation to the attendee |
Use Check Availability before Create an Appointment when the caller needs to choose from open times. If another block already provides the start and end time, use Create an Appointment directly.
## Connect Google Calendar
Add Google Calendar in the **Live Call** stage, then open **Setup**:
1. Select **Check Availability** or **Create an Appointment**.
2. Select **Connect to Google Calendar** and authorize the account.
3. Continue to **Configure**.
The connection belongs to the agent and can be reused across its flows. Other agents need their own connection.
## Check availability
Check Availability reads events from the selected calendar, excludes conflicts, and returns open slots within the schedule you configure.
| Setting | Purpose |
| :----------------------- | :----------------------------------------------------------------------------------------------- |
| **Calendar ID** | The calendar to check |
| **Start Time** | When Phonely should begin looking for slots; use the clock button to start from the current time |
| **Duration** | The length of each slot, such as `30m`, `1h`, or `1h 30m` |
| **Available Times** | The days and time ranges when appointments may be offered |
| **Search Period** | How many days ahead to search; the default is `7` |
| **Available Time Slots** | The maximum number of slots to return; the default is `3` |
**Search Period** and **Available Time Slots** are under **Advanced Settings**. Start Time, Duration, Search Period, and Available Time Slots can use values from [Available Variables](/flow-editor/variables).
Enter a fixed Start Time in ISO format with a timezone offset. Available Times use the agent's timezone, so confirm it before testing the schedule.
### Use the available slots
Check Availability provides **Available Appointment Slots**, an array containing the start and end of each returned slot. Later blocks can select it from **Available Variables** to present options, make a decision, or create an appointment after the caller chooses a time.
## Create an appointment
Create an Appointment adds an event to the selected calendar and sends a Google Calendar invitation to the configured email address.
| Setting | Purpose |
| :-------------------------- | :---------------------------------------------------------- |
| **Calendar ID** | The calendar where the event should be created |
| **Start Time** | When the event begins, in ISO format with a timezone offset |
| **End Time** | When the event ends, in ISO format with a timezone offset |
| **Email** | The attendee who receives the calendar invitation |
| **Appointment Name** | The event title |
| **Appointment Description** | Additional information included in the event |
Appointment Name and Appointment Description are optional. All fields except Calendar ID can use variables available before the block runs. Include a timezone offset in both Start Time and End Time, and make sure End Time is later.
## Route the result
Google Calendar provides **Success** and **Error** routes:
* **Success** runs when the selected calendar action completes. For Check Availability, this includes a successful check that finds no open slots.
* **Error** runs when Phonely cannot complete the request to Google Calendar.
Both actions support interim messages and call outcome tagging. These are covered in [Common Block Settings](/blocks/common-settings).
## Test Google Calendar
The block test uses the selected account and calendar:
* **Check Availability** reads real events and shows the slots it finds. It does not change the calendar.
* **Create an Appointment** creates a real event and sends a real invitation to the configured email address.
For Check Availability, use representative dates, availability windows, and appointment durations. Confirm that busy events are excluded and that **Available Appointment Slots** contains the expected slots for later blocks.
For Create an Appointment, use a calendar and attendee email that are safe for testing. Confirm the event details in Google Calendar and remove the test event when it is no longer needed.
After the block test, test the complete flow, including what should happen if the calendar request fails.
Testing **Create an Appointment** creates a real calendar event and may send an invitation. Use test details that will not affect customers or production schedules.
## Troubleshooting
Confirm that the connected Google account can access the calendar, then use the refresh button beside **Calendar ID**. If the account or its permissions changed, return to **Setup** and reconnect it.
Confirm the Start Time, Duration, Search Period, and Available Times. Check that the agent's timezone matches the schedule and that existing or all-day events do not occupy the requested window. A check with no open slots follows **Success**, so handle the empty result in the next block.
Confirm the agent's timezone and the timezone offset in Start Time. Review the configured Available Times, then run the block test again with a known date and calendar event.
Check whether the flow followed the **Error** route, then review the selected calendar, attendee email, start and end times, and timezone offsets. Reconnect the account if its permissions changed. After a successful test, verify the event and invitation in Google Calendar.
# Google Drive
Source: https://docs.phonely.ai/integrations/google-drive
Upload a call recording to Google Drive after a call.
Google Drive is a post-call integration. It uploads the recording after a call reaches the connected live-call block and ends.
## Connect Google Drive
Open the block's **Setup** step:
1. Select **Upload Call Recording**.
2. Select **Connect to Google Drive** and authorize the account.
3. Continue to **Configure**.
The connection belongs to the agent and can be reused across its flows. Other agents need their own connection.
## Configure the upload
| Setting | Purpose |
| :------------ | :----------------------------------------------------------------- |
| **Folder** | The destination folder; leave it unselected to use the root folder |
| **File Name** | The name of the uploaded recording |
**File Name** is required and can use values from [Available Variables](/flow-editor/variables). Use a unique value such as `call.id`, and include the `.mp3` extension.
## Route the result
Google Drive provides **Success** and **Error** routes:
* **Success** runs after the recording is uploaded.
* **Error** runs when Phonely cannot complete the upload.
The block retries temporary upload failures before using the Error route. Connect Error to a recovery action that records the failure or notifies your team.
## Test Google Drive
The block test uploads a sample call recording to the selected Google Drive folder:
1. Open **Test** and enter safe sample values for any variables in the file name.
2. Review the folder, resolved file name, and sample file in **Google Drive Preview**.
3. Select **Test**.
4. Confirm that the sample recording appears in the intended folder with the expected name.
Then complete a controlled call that reaches the live-call block connected to Google Drive. After the call ends, confirm that its recording appears in the selected folder and that the expected result route runs.
Testing Google Drive uploads a real sample recording. Use a folder and file name that are safe for testing, then remove the file when it is no longer needed.
## Troubleshooting
Confirm that the intended Google account is connected and can access the folder. Reconnect the account if its permissions changed. Select no folder to upload to the root folder instead.
Confirm that the call reached the live-call block connected to Google Drive and then ended. Check that the selected account can add files to the destination folder, review the Error route, and reconnect the account if its access changed.
Review the resolved folder and file name in **Google Drive Preview**. Confirm that each file-name variable is available to the Google Drive block. If no folder is selected, the recording is uploaded to the root folder.
# Google Sheets
Source: https://docs.phonely.ai/integrations/google-sheets
Search spreadsheet data or add a row during or after a call.
| Action | Use it to | Result |
| :--------------- | :-------------------------------------------- | :----------------------------------------------------- |
| **Search a Row** | Find a row that matches configured conditions | Makes the first matching row available to later blocks |
| **Add a Row** | Append values to selected spreadsheet columns | Adds one row to the selected tab |
## Connect Google Sheets
Open the block's **Setup** step:
1. Select **Search a Row** or **Add a Row**.
2. If the agent is not connected, select **Connect to Google Sheets** and authorize the account. Use **Reconnect** if its access has changed.
3. Continue to **Configure**.
The connection belongs to the agent and can be reused across its flows. Other agents need their own connection.
## Select the spreadsheet and tab
Choose the **Spreadsheet** and **Tab** the block should use, then select **Sync Column Names**. Phonely reads the first row as column names and uses them to configure search conditions or row values. For **Search a Row**, these names also define the block's output variables.
Keep column names non-empty and unique. Sync again after adding, renaming, or removing columns, then review any fields and downstream variables that depend on them.
## Search for a row
**Search a Row** checks spreadsheet rows against the conditions you configure. For each condition, select a column, comparison, and value. The value can be fixed or selected from [Available Variables](/flow-editor/variables).
Every condition must match the same row. If you add no conditions, the first data row is returned. When several rows match, the first matching row supplies the block's output variables.
After syncing the column names, later blocks can select the returned fields from **Available Variables**. For example, a search by `order_number` can provide `order_status` and `shipping_date` to the next block.
Enable **Include all data in agent context** when the conversation needs information from every matching row. This adds all matches to the agent's context; the block's output variables still use the first matching row.
## Add a row
**Add a Row** shows one field for each synced column. Map a fixed value or available variable to each column that should receive data. Leave a field empty only when the corresponding spreadsheet column may be empty.
## Route the result
Google Sheets provides **Success** and **Error** routes:
* **Success** runs when **Search a Row** finds a match or **Add a Row** adds the row.
* **Error** runs when no row matches or Phonely cannot complete the spreadsheet action.
Connect **Error** to an appropriate recovery path, such as checking the value again, collecting details for follow-up, or explaining that the action is unavailable.
## Choose when it runs
| Stage | Use it when |
| :------------ | :---------------------------------------------------------------------------------------- |
| **Live call** | The spreadsheet action must run during the active conversation |
| **Post-call** | The spreadsheet action should run after a call that reached the connected live-call block |
Place the block after the blocks that provide any values it uses. When the spreadsheet result is not needed during the conversation, prefer post-call so the caller does not wait for the request.
In **Live Call**, use an interim message when the action may create noticeable silence. For this and call outcome tagging, see [Common Block Settings](/blocks/common-settings).
## Test Google Sheets
The block test uses the selected account, spreadsheet, and tab:
* **Search a Row** reads real spreadsheet data and shows the first matching row. It does not change the spreadsheet.
* **Add a Row** adds a real row to the selected tab.
1. Open **Test** and enter safe sample values for any variables.
2. Review the resolved action, spreadsheet, tab, and search conditions or row data in **Google Sheets Preview**.
3. Select **Test** and inspect the result.
4. For Search a Row, confirm that the expected row and output values are returned. For Add a Row, confirm the new row in Google Sheets.
Then test the complete flow and both result routes. Review Google Sheets in the action trace or **Call Details** to confirm its execution and any stored variables.
Testing Add a Row changes the selected spreadsheet. Use a test sheet or values that are safe to add, and remove the test row when it is no longer needed.
## Troubleshooting
Confirm that the intended Google account is connected and has access to the spreadsheet. Refresh the spreadsheet or tab list, or reconnect the account if its permissions changed.
Confirm that the first row contains the expected column names and that every condition can match the same row. Review the resolved condition values in **Google Sheets Preview**, including capitalization, spacing, and numerical values, then test again.
Select **Sync Column Names** and confirm that the column appears in the block. Test Search a Row with a matching row, then review downstream fields that reference the Google Sheets variables.
Confirm that the intended spreadsheet and tab are selected. Sync the column names, review each resolved field in **Google Sheets Preview**, and verify that the connected account can edit the spreadsheet.
# Make
Source: https://docs.phonely.ai/integrations/make
Send post-call data to a Make webhook.
For new flows, prefer [Send Call Data](/blocks/data-and-automation-blocks/send-call-data). Make uses the same webhook configuration and execution behavior; this block remains available for existing flows.
Use Make to send a completed call's data to a Make webhook. It runs only in post-call, after a call reaches the live-call block to which it is connected.
## Configure Make
1. Copy the webhook URL from Make.
2. Enter it in **Webhook URL**.
3. Keep **Send full call data to Make** enabled for the available call record, or turn it off to build a custom JSON body.
Make does not create an agent-level provider connection. The webhook URL and payload configuration belong to this block.
The block sends a JSON `POST` request and provides the same full-payload fields, custom-body modes, variable support, and endpoint requirements as Send Call Data. See [Send Call Data](/blocks/data-and-automation-blocks/send-call-data) for the canonical configuration and payload reference.
## Test Make
The block test sends a real request to the configured webhook. Use a Make scenario and data that are safe for testing, review **Resolved Input**, then confirm in Make that the request arrived with the expected payload.
After the block test, complete a controlled call that reaches the connected live-call block and confirm that the scenario receives one request after the call ends. For shared verification steps and troubleshooting, see [Test the request](/blocks/data-and-automation-blocks/send-call-data#test-the-request) and [Troubleshooting](/blocks/data-and-automation-blocks/send-call-data#troubleshooting).
# Microsoft Outlook
Source: https://docs.phonely.ai/integrations/microsoft-outlook
Send email from a connected Microsoft Outlook account during or after a call.
Use [Send Email](/blocks/communication-blocks/send-email) for Phonely's built-in email action. Use [Email & SMS Notification](/blocks/communication-blocks/email-sms-notification) when you want Phonely's call summary sent automatically after a call.
## Connect Microsoft Outlook
Open the block's **Setup** step:
1. Select an existing Microsoft Outlook account under **Connection**, or select **Add Connection** and authorize another account.
2. Continue to **Configure**.
The selected account sends the email. Its connection belongs to the agent and can be reused across flows. Other agents need their own connection.
## Configure the email
| Setting | Purpose |
| :---------- | :----------------------------- |
| **To** | One or more primary recipients |
| **Subject** | The email subject |
| **Body** | The email message |
All three fields are required. To, Subject, and Body can use values from [Available Variables](/flow-editor/variables). Each recipient must resolve to a valid email address when the block runs.
### Advanced settings
| Setting | Purpose |
| :------------ | :----------------------------------------------------- |
| **Body Type** | Send the body as **Plain Text** or **HTML** |
| **Cc** | Add recipients visible to everyone receiving the email |
| **Bcc** | Add recipients hidden from the other recipients |
| **Reply To** | Send replies to a different email address |
Cc, Bcc, and Reply To can also use variables available before the block runs. Reply To must resolve to a valid email address. Choose HTML only when the Body contains HTML markup.
## Choose when to send it
| Stage | When it runs |
| :------------ | :----------------------------------------------------------- |
| **Live call** | When the active call reaches the block |
| **Post-call** | After a call that reached the connected live-call block ends |
Place Microsoft Outlook after the blocks that provide any recipient addresses or content values it uses. Use post-call when the email is not needed during the conversation, so the caller does not wait for it to send.
In **Live Call**, Microsoft Outlook also supports interim messages and call outcome tagging. See [Common Block Settings](/blocks/common-settings).
## Test Microsoft Outlook
The block test resolves the configured fields and shows the email in **Email Preview** before sending it from the selected Microsoft Outlook account:
1. Open **Test** and enter safe sample values for any variables.
2. Review the recipients, Reply To, subject, Body Type, and body in **Email Preview**.
3. Select **Test**.
4. Confirm that the email arrives with the expected sender, content, and formatting.
Then test the complete flow and confirm that its variables resolve correctly. Review Microsoft Outlook in the action trace or **Call Details** to confirm its execution.
Testing Microsoft Outlook sends a real email from the selected account. Use recipients and content that are safe for testing.
## Troubleshooting
Confirm that the intended account is selected under **Connection** and reconnect it if its access changed. Review **Email Preview** for valid recipients, then check the recipient's spam folder and the connected account's sent mail. Provider restrictions or sending limits can also prevent delivery.
Return to **Setup** and select the intended Microsoft Outlook connection. The connected account determines the sender address. Clear or correct **Reply To** if replies should return to that account.
Confirm that the variable is available before the Microsoft Outlook block runs. Test the upstream path that creates it, then review its resolved value in **Email Preview** before testing again.
Set **Body Type** to **HTML** and confirm that the Body contains valid HTML. Use **Plain Text** when the body should not be interpreted as markup.
# Overview
Source: https://docs.phonely.ai/integrations/overview
Compare available integrations and see where they can run in a flow.
Integration blocks let a flow use an external service, such as checking a calendar, sending an email from a provider account, updating a spreadsheet, or triggering an automation.
Use [Block Reference](/blocks/overview) for capabilities that do not depend on a specific provider, such as Talk, Filter, API Request, or Code.
## Connected integrations
| Integration | Use it to | Available in |
| :--------------------------------------------------- | :--------------------------------------------- | :------------------- |
| [Google Calendar](/integrations/google-calendar) | Check availability or create an appointment | Live call |
| [Gmail](/integrations/gmail) | Send an email from a connected Gmail account | Live call, post-call |
| [Google Sheets](/integrations/google-sheets) | Search for or add a spreadsheet row | Live call, post-call |
| [Google Drive](/integrations/google-drive) | Upload the current call recording | Post-call |
| [Microsoft Outlook](/integrations/microsoft-outlook) | Send an email from a connected Outlook account | Live call, post-call |
| [Slack](/integrations/slack) | Send a message to a Slack channel | Live call, post-call |
Use Gmail or Microsoft Outlook when the email should come from a connected provider account. Use [Send Email](/blocks/communication-blocks/send-email) for Phonely's built-in email action.
## Webhook automations
| Integration | Use it to | Available in |
| :----------------------------- | :--------------------------------- | :----------- |
| [Make](/integrations/make) | Send call data to a Make webhook | Post-call |
| [Zapier](/integrations/zapier) | Send call data to a Zapier webhook | Post-call |
Make and Zapier use the same webhook configuration and execution behavior as [Send Call Data](/blocks/data-and-automation-blocks/send-call-data). They remain in Integrations to match the block picker, but do not create provider connections. For new flows, prefer Send Call Data.
## Connect an account
Google Calendar, Gmail, Google Sheets, Google Drive, Microsoft Outlook, and Slack use connected provider accounts. These connections belong to the agent, not an individual flow. Once connected, an account is available to integration blocks across that agent's flows. Other agents must connect their own accounts.
In the block's **Setup** step, choose an action when more than one is available, then connect or select the account the block should use. The block's action and configuration remain specific to the flow.
If a provider connection expires or its permissions change, reconnect it before testing the flow again.
## Configure and test an integration
1. Add the integration at the stage where it should run.
2. Complete its connection or webhook setup.
3. Enter the required values in **Configure**. Focus a supported field to select a value from **Available Variables**.
4. Run the block test when available, then verify the result in the external service.
5. Test the complete flow before using the integration in live calls.
An integration can use only variables available before it runs. Tests for some integrations create output variables that later blocks can use. Each provider guide explains its inputs, outputs, and test behavior.
Integration tests can send messages, create appointments or rows, upload files, or trigger automations. Use accounts and data that are safe for testing.
# Slack
Source: https://docs.phonely.ai/integrations/slack
Send a message to a connected Slack workspace during or after a call.
Use Slack to send fixed text and values from the flow to a workspace channel.
## Connect Slack
Open the block's **Setup** step:
1. Select **Send Channel Message**.
2. Select **Connect to Slack** and authorize the workspace. Use **Reconnect** if the connection's access has changed.
3. Continue to **Configure**.
The connection belongs to the agent and can be reused by Slack blocks across its flows. Other agents need their own connection.
## Configure the message
| Setting | Purpose |
| :---------- | :---------------------------------------------- |
| **Channel** | The workspace channel that receives the message |
| **Message** | The text to send |
Both fields are required. **Channel** shows the non-archived public and private channels available to the Slack connection. Select the channel in the editor; it cannot use a variable or be chosen by Ask AI.
**Message** can combine fixed text with values from [Available Variables](/flow-editor/variables). Place the Slack block after any blocks that provide the values it uses.
For example:
> New appointment request from `caller_name` for `appointment_time`.
Select each value from **Available Variables** rather than typing its variable name as plain text.
## Choose when to send it
| Stage | When it runs |
| :------------ | :----------------------------------------------------------- |
| **Live call** | When the active call reaches the block |
| **Post-call** | After a call that reached the connected live-call block ends |
Use live call when the message is needed while the conversation is active. Use post-call when it can wait until the call ends, so the caller does not wait for Slack.
In **Live Call**, Slack also supports interim messages and call outcome tagging. See [Common Block Settings](/blocks/common-settings).
## Test Slack
The block test resolves the configured message and shows it with the selected channel in **Slack Preview** before sending it:
1. Open **Test** and enter safe sample values for any variables.
2. Review the channel and resolved message in **Slack Preview**.
3. Select **Test**.
4. Confirm that the message appears in the intended Slack channel.
Then test the complete flow and confirm that its variables resolve correctly. During a Web Chat test, expand Slack in the action trace. After a phone call, open **Call Details**, select **Blocks**, and expand Slack to confirm its execution.
Testing Slack sends a real message to the selected channel. Use a channel and content that are safe for testing, then remove the message if it is no longer needed.
## Troubleshooting
Return to **Setup** and select **Connect to Slack**. If Slack was already connected, select **Reconnect** to refresh its access, then open **Configure** again.
Confirm that the channel is not archived and is available to the Slack connection. Reconnect Slack if its channel access changed. Private channels appear only when the connection can access them.
Review the selected channel in **Slack Preview** and confirm that the Slack connection can post there. Return to **Configure** to select the intended channel, then test again.
Confirm that the variable is available before the Slack block runs. Test the upstream path that creates it, then review its resolved value in **Slack Preview** before testing again.
# Zapier
Source: https://docs.phonely.ai/integrations/zapier
Send post-call data to a Zapier webhook.
For new flows, prefer [Send Call Data](/blocks/data-and-automation-blocks/send-call-data). Zapier uses the same webhook configuration and execution behavior; this block remains available for existing flows.
Use Zapier to send a completed call's data to a Zapier webhook. It runs only in post-call, after a call reaches the live-call block to which it is connected.
## Configure Zapier
1. Copy the webhook URL from Zapier.
2. Enter it in **Webhook URL**.
3. Keep **Send full call data to Zapier** enabled for the available call record, or turn it off to build a custom JSON body.
Zapier does not create an agent-level provider connection. The webhook URL and payload configuration belong to this block.
The block sends a JSON `POST` request and provides the same full-payload fields, custom-body modes, variable support, and endpoint requirements as Send Call Data. See [Send Call Data](/blocks/data-and-automation-blocks/send-call-data) for the canonical configuration and payload reference.
## Test Zapier
The block test sends a real request to the configured webhook. Use a Zap and data that are safe for testing, review **Resolved Input**, then confirm in Zapier that the request arrived with the expected payload.
After the block test, complete a controlled call that reaches the connected live-call block and confirm that the Zap receives one request after the call ends. For shared verification steps and troubleshooting, see [Test the request](/blocks/data-and-automation-blocks/send-call-data#test-the-request) and [Troubleshooting](/blocks/data-and-automation-blocks/send-call-data#troubleshooting).
# Ask AI
Source: https://docs.phonely.ai/key-concepts/ask-ai
Use Ask AI with the context of your current Phonely page.
Ask AI is Phonely's in-product assistant. It opens in the app side panel and works alongside the page you are using.
Use Ask AI to ask product questions, investigate agent or call behavior, navigate to the right place, and help with supported agent configuration. Its available information and actions depend on the current page, agent, selection, your access, and the capabilities available there.
## Open Ask AI
Ask AI has several entry points:
* On **Home**, enter a request under **What can Phonely do for you?**
* On other supported pages, use the **Ask AI** input in the top app bar.
* Press `Command-/` on macOS or `Ctrl-/` on Windows to open or close Ask AI.
* Press `Command-K` or `Ctrl-K` to search Phonely first. If search does not provide the answer, send the request to Ask AI.
The top-bar input also shows navigation and agent results, recent Ask AI chats, and an attachment control when open.
## Give Ask AI a clear task
Good requests state the outcome and relevant scope:
* "Explain the difference between guidelines and the knowledge base."
* "Open the flow for this agent."
* "Can you look into this call in detail?"
* "Why did these selected calls end without an outcome?"
* "Add a fallback path when the appointment lookup returns no result."
* "Update the selected guideline section to keep responses concise."
If a request could apply to several agents, flows, or calls, name the intended scope. Ask for evidence or the relevant documentation when a product answer needs verification.
## Investigate a call in detail
From **Call Details**, select **Ask AI** to open a new chat focused on that call. After a Test Call, **Improve with AI** provides a similar handoff so you can explain what you observed and ask Ask AI to investigate.
For a detailed call investigation, Ask AI can bring together the transcript, path through the flow, captured variables, block-level events, and available runtime events. This is useful when the visible call summary shows the result but not enough evidence to explain why it happened, or when manually correlating events would be difficult.
Start with a request such as "Can you look into this call in detail?" Then add the symptom you observed, expected behavior, or question you want answered. Review the cited evidence and current flow configuration before making a change; some call evidence may be unavailable or incomplete.
## Understand page context
Ask AI follows your navigation context. Depending on the current surface, that context can include the current agent, active flow, selected guideline section, or selected calls. This is why requests such as "explain this flow" or "review these calls" can work without repeating every identifier.
The conversation can continue as you navigate, while the page context updates to the new surface. Check the current page and selection before using an implicit reference such as "this" or "these."
## Continue or start a chat
Opening Ask AI from the top bar continues the active conversation. Use **New chat** when you want a clean context for an unrelated task.
Use **Chat history** to restore a recent Ask AI session. Removing a chat hides it from that history. Recent chats can also appear in the open top-bar input.
## Reference a flow block
When a flow is open, you can point Ask AI at an exact block instead of describing it. Type `@` in either the top-bar Ask AI input or the Ask AI side-panel composer, then pick a block from the list or keep typing to match one by name. Use the arrow keys and `Enter` to choose a result with the keyboard; `Escape` dismisses the list.
You can also open an editable block's **More options** menu and select **Ask AI about this block** when that action is available. Ask AI opens with the block reference in the composer. Add your question or instruction, then send it.
The reference stays in place while you write, edit, or continue the conversation, and asks Ask AI to re-read that block before it acts.
Block references only work while their flow is open. If you reference a block and then leave its flow, open the flow again or remove the reference before sending.
## Add supporting material
You can attach one supported audio recording, document, or CSV file to a request. Ask AI reads a CSV's contents, so you can hand it data such as a zip-code-to-region mapping. Wait for the file to finish processing before sending, and explain what you want Ask AI to do with it.
Attachments supplement the current page context; they do not change which agents or organization data you are allowed to access.
## Report an Ask AI issue
Open **More Ask AI options** and select **Report Ask AI issue** to report the current conversation. To report a specific response, point to it and select the bug icon beneath it. Phonely includes the relevant conversation diagnostics to help investigate the issue.
If you are asked to share identifiers separately, select **Copy diagnostic details** from **More Ask AI options**. See [Report Issues and Ideas](/get-started/report-issues-and-ideas) for attachment limits, included context, and guidance on writing a useful report.
## Review changes before relying on them
Treat Ask AI as a collaborator rather than an automatic approval step:
1. State the intended caller or business outcome.
2. Review the proposed flow on the canvas. Added, removed, and changed blocks are highlighted; select a block to inspect its proposed settings.
3. For a focused proposal started from a block's **Generate with AI** strip, inspect the highlighted fields and select **Apply changes**. If you reject an individual change, the proposal returns to per-change review: accept or reject the changes, then select **Submit changes**. Other flow proposals use this per-change review directly. The draft does not change until you apply or submit the proposal.
4. Check the affected configuration and test the important paths before relying on the result with callers.
Accepted flow changes are applied together to the current draft. If the draft changes before you submit, the proposal can become outdated and must be prepared again. Draft auto-save does not publish the changes.
On **Performance**, Ask AI can propose changes to cards, views, and saved metrics or filters. Those proposals have their own review and apply actions; see [Edit Performance with Ask AI](/performance#edit-performance-with-ask-ai).
## Ask AI and Test Call
**Test Call** is a separate tool that shares the app side panel with Ask AI. It appears when the current page has an agent to test; it is not available on Home or other pages without agent context.
Use the main **Test agent** action for **Web Call** in **Talk** mode. Use the chat icon on the right side of the same button for **Web Chat** in **Chat** mode.
When started from the Flow Editor, Web Call and Web Chat test the selected flow's current draft. Use the **Draft / Live** control in the Test Call panel to switch between the latest draft and the published version; switching restarts the test. If a flow has never been published, its draft is used as the fallback.
**Place Phone Call** for an outbound flow uses the published version, falling back to the draft only when the flow has never been published. See [Test and Publish](/flow-editor/test-and-publish) for the recommended release process and [Test from a selected block](/flow-editor/test-and-publish#test-from-a-selected-block) when you need to isolate part of a complex draft.
## Ask AI and documentation
Ask AI can retrieve Phonely documentation for general product knowledge. When an answer depends on an agent, organization, call, or current selection, it can use the live context and capabilities available on that surface instead.
Documentation explains the product generally; your current Phonely configuration remains the source of truth for your setup.
# Flow Canvas Controls
Source: https://docs.phonely.ai/key-concepts/flow-canvas-controls
Use the flow canvas to add and arrange blocks, resolve invalid variables, focus outcomes, and review edits.
The flow canvas includes a vertical toolbar for adding, arranging, and reviewing content. **Undo**, **Redo**, and **Change History** appear separately in the bottom-left of the editor.
Editing controls update the draft without publishing it. View-only controls, such as **Outcome Focus** and **Keyboard shortcuts**, do not change the flow.
## Canvas toolbar
Controls that modify the draft are unavailable when the current view is read-only.
### Add blocks
Select **Add block** to add an unconnected block to the canvas. The picker separates **Live Call** and **Post Call** blocks and only shows blocks supported by the flow's inbound or outbound direction.
To add a block already connected to a path, select an available connection handle on an existing block instead.
Add pre-call blocks from the pre-call connection above **Greeting** or **Make Call**. **Start Flow** does not support pre-call blocks.
### Add sticky notes
Select **Add Sticky Note** to document design intent, assumptions, ownership, or follow-up work directly on the canvas. You can format the note's content, change its color, and resize it.
Sticky notes do not connect to other blocks, run during a call, or provide instructions to the agent.
### Organize blocks
Select **Organize blocks** to reposition the current flow without changing block settings or connections. The new layout is recorded as one undoable edit.
Use it after adding or reconnecting several blocks. Review the result and select **Undo** if the previous layout was clearer.
### Collapse or expand blocks
Select **Collapse all blocks** to hide the detailed exit-condition sections on blocks that support them. Select **Expand all blocks** to show those sections again.
This changes only how the canvas is displayed. It does not remove exit conditions, connections, or other block settings.
### Replace invalid variables
For an isolated invalid reference, open the affected block, remove the reference, and select the intended variable again. Select **Replace Invalid Variables** when the same invalid reference appears in several fields or blocks and you want to update every affected use at once.
See [Resolve invalid variables](/flow-editor/variables#resolve-invalid-variables) for guidance on checking the cause and choosing a safe replacement.
### Focus blocks by call outcome
Select **Focus blocks by call outcome** to open **Outcome Focus**. Choose one or more call outcomes to highlight the blocks that use them and dim unrelated blocks. The number beside each outcome is the number of matching blocks in the current flow.
Outcome Focus only changes how the canvas is displayed. Clear the selection to return to the normal view.
### Keyboard shortcuts
Select **Keyboard shortcuts** in the canvas toolbar to see the shortcuts for your device.
| Task | Windows | macOS |
| :------------------------- | :---------------------- | :------------------------ |
| Undo | `Ctrl` + `Z` | `Command` + `Z` |
| Redo | `Ctrl` + `Shift` + `Z` | `Command` + `Shift` + `Z` |
| Copy selected blocks | `Ctrl` + `C` | `Command` + `C` |
| Paste blocks | `Ctrl` + `V` | `Command` + `V` |
| Delete selected blocks | `Delete` or `Backspace` | `Delete` or `Backspace` |
| Select more than one block | `Ctrl` + click | `Command` + click |
| Box select | `Shift` + drag | `Shift` + drag |
| Zoom | Mouse wheel | Mouse wheel |
| Pan | Drag the canvas | Drag the canvas |
Copying a selection preserves connections between the selected blocks. Connections to blocks outside the selection are not copied. You can paste copied blocks into another open Phonely flow, but review their variables and connections because the destination flow may provide different context.
When the cursor is in a text field, standard text-editing shortcuts take precedence over canvas shortcuts.
## Undo, redo, and Change History
Use **Undo** and **Redo** in the bottom-left of the editor to move through recent draft changes in the current editing session. **Change History** lists the changes recorded during that session.
Change History is not a durable flow checkpoint and does not restore an edit by itself. Use [Flow Versions](/flow-editor/versions) to save, review, or restore named versions over time.
# Call Flows
Source: https://docs.phonely.ai/key-concepts/flows
Understand how flows, blocks, connections, stages, drafts, and published versions work in Phonely.
A flow defines what your agent does before, during, and after a call. On the canvas, you connect blocks to create the conversation path, collect information, make decisions, call other systems, and handle the result of the call.
## How a flow is structured
Every flow starts with a trigger and can contain three execution stages.
| Stage | When it runs | Common uses |
| :------------ | :------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------ |
| **Pre-call** | Before the agent greets the caller or places an outbound call | Look up caller data, apply a filter, prepare variables, or stop the flow before the conversation begins |
| **Live call** | While the caller and agent are speaking | Talk, collect information, route the conversation, send messages, call an API, or transfer the call |
| **Post-call** | After the call ends | Notify a team, update another system, store call data, or start a follow-up action |
The block picker only shows blocks that are supported for the selected stage and the flow's direction. Some blocks can run in more than one stage; their configuration and available variables can differ by stage.
![Flow Editor showing a Greeting trigger, connected blocks during the call, an End Call block, and a post-call notification]()
### Triggers
The trigger is the entry point of a flow:
* **Greeting** starts the agent's **First Flow**, the default entry point for inbound calls.
* **Start Flow** is the entry point for another inbound flow. The agent enters that flow when its **Global Flow** trigger condition matches or another flow routes to it with **Transfer Flow**.
* **Make Call** starts an outbound flow.
Transfer Flow keeps the call active, but flow-specific variables do not carry from the source flow to the target flow. Design the target flow to collect or retrieve the data it needs.
Pre-call blocks connect before the trigger. The path during the call continues from the trigger, and post-call blocks attach to a block's post-call output.
### Blocks and connections
Each block handles one step, such as speaking, collecting information, making a decision, exchanging data with an external system, or transforming data.
Connections determine how the flow moves between blocks:
* **Pre-call:** Run preparation blocks before the flow trigger.
* **Continuation:** Move to the next block during the call.
* **Named route:** Follow an exit condition, branch, or action result.
* **Post-call:** A post-call block runs after the call if the call reached the live call block it is connected to.
## Create and manage flows
Your agent's flows appear in the left sidebar of the editor. Select **+** beside the flow list, then choose how to create the flow:
* **Start from Scratch** creates a new flow for you to build in the editor.
* **Create with AI** creates a new flow, opens it in the editor, and opens Ask AI so you can describe what you want to build.
* **Use Template** creates a flow from a pre-built template that you can customize.
When you choose **Use Template**, search or filter the template library, then open a template to review its description, integrations, and read-only flow preview. Select **Use template** to create an editable flow from it, then review the configuration before testing or publishing.
Use a flow's menu to turn it on or off, rename, duplicate, or delete it. The **First Flow** cannot be turned off or deleted while it is the agent's active entry point for inbound calls.
### Flow availability and published versions
Turning a flow on or off controls whether the agent can use it during normal calls:
* When a flow is **on**, the agent can enter it through a connected route or a matching Global Flow trigger condition.
* When a flow is **off**, it is excluded from normal calls and cannot be entered by a matching Global Flow trigger condition.
Turning a flow off does not delete its draft or version history.
Publishing a version is separate from turning a flow on or off:
* **Publish** in the editor's top bar creates a version from the current draft, makes that version live, and turns the flow on.
* Turning a flow on or off from its menu changes only whether the flow is available. It does not create a version.
A flow can be on while it has unpublished draft changes. If the top-bar **Publish** button is enabled, the current draft differs from the live version.
## Add and configure blocks
Choose how to add a block based on whether you already know where it belongs:
1. Hover over an available connection point and select **+** to add a compatible block and connect it in one step. The connection determines its stage and route.
2. Select **Add block** in the canvas toolbar to place an unconnected block from the **Live Call** or **Post Call** category, then connect it where it belongs.
Pre-call blocks are added from the connection above the flow trigger where pre-call actions are supported, not from the canvas toolbar.
After you add a block, the block configuration panel opens. Available fields, outputs, variables, and test options depend on the block and its execution stage. Changes are auto-saved to the current draft.
Use the [Block Reference](/blocks/overview) to choose a capability and review its supported stages, required settings, outputs, and routing behavior.
## Work with variables
Variables carry information into and through a flow, including call information, flow-defined values, and outputs from earlier blocks. A block can use a variable only if the value is available before that block runs on the path that reaches it.
Type `@` in a supported field to open **Available Variables**. Select a value from the picker so Phonely adds it to the field.
If a referenced value is removed or is no longer available on that path, Phonely marks the reference as invalid so you can replace it.
See [Variables](/flow-editor/variables) for variable sources, scope, availability, and invalid-reference handling.
## Draft, validate, and publish
Edits are auto-saved to the current draft. Auto-save does not create a version or make the draft live.
Before publishing, open the **Flow Checklist** to find reachable blocks with missing or invalid settings. A missing published version is a warning; a validation error on a block the flow can reach must be resolved before you can publish. Unconnected blocks parked on the canvas are excluded until they become part of the flow.
Select the main **Publish** button to run a quick AI review. If the review finds concerns, inspect them in the Flow Checklist, ask Ask AI to help, or choose **Publish anyway** after deciding they are acceptable. This review is advisory; deterministic block errors still prevent publishing.
Publishing creates a version from the current draft and makes it live. For version-related actions, open the adjacent menu:
* **Save as Version** creates a numbered checkpoint without changing the live version.
* **Version History** lets you inspect saved and published versions. Restoring a version replaces the current draft but does not change the live version until you publish it.
See [Test and Publish](/flow-editor/test-and-publish) for the complete release process and which version each test uses. See [Flow Versions](/flow-editor/versions) before restoring a snapshot and [Resolve Remote Flow Updates](/flow-editor/collaboration) when newer remote changes need to be resolved.
## Test changes safely
The recommended release loop is:
1. Edit the draft and wait for auto-save to finish.
2. If the changed block provides its own test, run it with safe sample data.
3. Test the draft from its normal entry point with Web Chat or Web Call. Use Web Call when the change affects spoken behavior.
4. Resolve every reachable block error in the **Flow Checklist**.
5. Publish the reviewed draft and address any relevant advisory review findings.
6. Switch the test to **Live** and verify the version callers will use.
Web Call and Web Chat started from the Flow Editor use the selected flow's current draft by default. The **Draft / Live** control in the Test Call panel switches between the current draft and published version and restarts the test. **Place Phone Call** for an outbound flow uses its published version, falling back to the draft only when the flow has never been published.
Some blocks provide a test in their configuration panel. A block-level test checks that block in isolation with sample inputs and lets you inspect its result. It does not verify the block's connections or the complete conversation.
For focused troubleshooting in a long or complex flow, **Test from here** starts the current draft at a selected block that runs during the call. It checks part of the draft without changing the published version, but it is not a required release step and does not replace a complete test of the published agent.
Tests can run connected actions, including messages and external requests. Use test recipients, safe endpoints, and non-production records when a tested route has side effects.
See [Test and Publish](/flow-editor/test-and-publish) for Web Call, Web Chat, Test from here, and the recommended release loop.
## Keep flows maintainable
* Give each flow and block a name that describes its purpose.
* Use each block for one clear step and give its exit conditions descriptive names.
* Use sticky notes to explain non-obvious design decisions, not runtime instructions.
* Use **Organize blocks** after structural changes to make paths easier to review.
* Publish small, reviewed changes and save versions at meaningful checkpoints.
* Test each route that can end a call, transfer it, handle a failure, or trigger a post-call action.
Navigate, organize, annotate, and inspect a flow.
Design branches, flow transfers, call transfers, and fallbacks.
Capture data and use it safely across stages and blocks.
Configure flow-level context, Guidelines, and knowledge sources.
Find validation errors before you publish.
Check draft changes and release a reviewed version safely.
# Plan Your Phonely Agent
Source: https://docs.phonely.ai/key-concepts/plan-your-agent
Plan the main call goal, required knowledge, integrations, and fallback paths before building your agent.
## Save yourself hours in a few minutes
An agent improves through planning, testing, and iteration. Before building, write down what a successful call should accomplish and what information the agent needs to get there.
Start with one important call experience instead of trying to handle every possible request immediately. Give less common requests a clear fallback, such as transferring the caller or collecting information for follow-up.
## Define your main use case
Think about the most common reasons customers call. Choose one goal, such as scheduling an appointment, qualifying a lead, answering a recurring question, or routing a caller to the right team.
Write down:
* The questions your staff normally ask
* The information required from the caller
* The steps that complete the task
* The decisions that create different paths
* The limits or situations that require a human
* What should happen when the task cannot be completed
## Plan tools and data
List the tools the agent needs before or during the call and the actions that should happen afterward. For each integration, record what information it needs, what result the flow expects back, and what should happen if it fails.
If a flow needs to connect to a service through an API, see the [API Request block](/blocks/api-request).
## Gather your knowledge base
Collect the business information the agent needs to answer customer questions. You can add documents, written information, or website content to the knowledge base.
Keep each type of information in the right place:
* Put shared tone, objectives, and behavioral restrictions in agent guidelines.
* Put business facts and reference material in the knowledge base.
* Put ordered conversation steps, decisions, integrations, transfers, and endings in flows.
When connecting a website, include only the pages that contain useful and current information for the agent.
## Think about call routing
Decide how callers reach the agent and when the flow should transfer them to a person or another call experience. Include routing and fallback behavior in your test plan.
## Start simple, nail one use case, and scale from there
Build the shortest complete path first and test it. Then add branches and integrations one at a time. This makes it easier to identify whether an issue comes from the conversation design, business knowledge, or an external service.
## Next steps
Start from the initial agent setup or duplicate an existing agent that already matches part of your use case.
Add the main conversation path, required information, integrations, and fallback behavior.
Test the successful path, missing information, important branches, integration failures, transfers, and early call endings before using the flow with callers.
## Common questions
You can build the main conversation in the visual flow editor. API-based integrations may require technical details from the service you are connecting.
Add reference information to the knowledge base, then use agent guidelines for behavior that should apply across flows.
Design an explicit fallback path, such as transferring the caller or collecting information for follow-up, and include that path in testing.
# Manage and Delete Agents
Source: https://docs.phonely.ai/manage-account-and-organization-settings/delete-agents
Review organization agents, export their usage, or permanently delete selected agents.
Open **Settings > Agents** to review the agents in the current organization. The table includes identifying and operational details such as the agent name, phone number, agent ID, monthly call minutes, and last update time. Some columns depend on your access level and table settings.
## Export agent usage
Use **Export Usage** to download usage data for the agents in the table. For interactive charts and filters, use [Usage and Cost](/billing-and-usage/manage-agents-and-usage).
## Delete agents
1. Select the checkbox beside each agent you want to remove.
2. Select **Delete agents** in the selection toolbar.
3. Review the selected agents and confirm **Delete agents**.
Deleting an agent is permanent. Confirm that you no longer need its configuration or associated resources before continuing.
# Settings Overview
Source: https://docs.phonely.ai/manage-account-and-organization-settings/manage-account-and-organization-settings
Find the account, workspace, billing, usage, and communication settings available in Phonely.
Open **Settings** from your profile menu to manage your account and the current organization.
## Settings pages
| Page | Use it for |
| ------------------ | ----------------------------------------------------------------------------------- |
| **Account** | Profile, preferences, account identifiers, API access, and organization information |
| **Team** | Members, invitations, and roles |
| **Plan & Billing** | Subscription, included usage, payment information, and invoices |
| **Usage & Cost** | Usage and estimated cost trends by date, agent, and usage type |
| **Notifications** | Email alerts for monthly usage thresholds |
| **Agents** | Organization-wide agent inventory, usage export, and agent deletion |
| **Numbers** | Phone numbers and the organization do-not-call list |
| **Messaging** | Messaging configuration for the organization |
The pages and controls you can use depend on your role, plan, and organization configuration. Users with viewer access see only **Account**.
## Personal and organization settings
Changes under **Account** apply to your user unless the field is in the organization section. Team membership, billing, notifications, agents, numbers, and messaging are organization-level settings.
Check the organization switcher before changing organization-level settings when you belong to more than one organization.
# Campaign Phone Numbers
Source: https://docs.phonely.ai/outboundcalling/addingphonenumber
Choose outbound phone numbers and configure how a campaign selects them.
Every outbound campaign needs at least one enabled phone number. In **Add Phone Numbers**, choose from numbers already assigned to the agent or unassigned numbers available to the workspace.
If the required number is not listed, select **Import numbers from Twilio** and complete the connection flow.
## Choose a routing method
The routing method controls which enabled number places each call:
| Method | How Phonely selects a number |
| --------------------- | ----------------------------------------------------------------------------------- |
| Weight Routing | Selects numbers according to their assigned weights; active weights must total 100% |
| State-Based Routing | Uses an enabled number in the contact's state when one is available |
| Country-Based Routing | Uses an enabled number in the contact's country when one is available |
State- and country-based routing fall back to a random number from the enabled pool when no regional match is available.
## Map the dial-out number when needed
A campaign source can provide a specific dial-out number. Map **Dial-out Number** to the relevant source field only when each contact should determine which campaign number places the call.
A non-empty mapped value overrides Weight, State, and Country routing. The value must match an enabled number in the campaign; otherwise, that contact fails instead of using another number. An empty or unmapped value uses the campaign's configured routing method.
## Verify the numbers
Before launching the campaign:
1. Confirm that every intended number is enabled.
2. For Weight Routing, confirm that the weights total 100%.
3. For regional routing, test a matching contact and a contact that requires the fallback pool.
4. Place a controlled outbound call and verify the number shown to the recipient.
# Outbound Compliance
Source: https://docs.phonely.ai/outboundcalling/avoidmarkedasspamlikely
Prepare an outbound campaign responsibly and reduce avoidable delivery problems.
Carrier labeling and call delivery depend on factors outside Phonely, so no configuration can guarantee that a call will be answered or avoid a spam label. Use the campaign controls to remove preventable problems before launch.
## Before launching
1. Call only contacts you are permitted to contact.
2. Remove contacts who have opted out or must not be called.
3. Use an appropriate enabled number and routing method for the audience.
4. Configure calling hours in the contact's scheduling timezone.
5. Set a calls-per-hour limit appropriate for the campaign, and add any do-not-dial days such as holidays.
6. Test the flow, source mappings, routing, and voicemail behavior with numbers you control.
Phonely warns when calling hours extend outside 8:00 AM–9:00 PM, but you remain responsible for the rules that apply to each contact and jurisdiction.
## Review campaign behavior
Start with a controlled audience and monitor the campaign's queued and completed calls. Investigate unexpected delivery failures, answer patterns, outcomes, or opt-out requests before increasing volume.
Pause the campaign while correcting its contact source, calling hours, phone-number configuration, or flow behavior.
Phonely's compliance controls and Do Not Call handling do not replace your own legal review, consent records, suppression lists, or operational monitoring.
# Outbound Campaigns
Source: https://docs.phonely.ai/outboundcalling/createaoutboundcallingcampaign
Choose who to call, when calls can run, and which outbound flow handles them.
Outbound campaigns schedule and place calls through an agent's outbound flow. The campaign supplies the contacts, phone numbers, calling hours, and source data; the selected flow controls what happens during and after each call.
You are responsible for consent, calling hours, identification, opt-outs, recordkeeping, and every law that applies to your campaign. Complete the in-product compliance acknowledgements only after reviewing the campaign and its audience.
Viewers and organization members with read-only access can open **Outbound Calls**, browse campaigns and call flows, and view draft campaign details, but cannot create, edit, delete, or change the status of a campaign.
## Choose a campaign type
Select **Create Campaign**, then choose how contacts enter the campaign:
| Campaign type | Use it when | Contact source |
| ------------------ | ----------------------------------------------------------- | ------------------------ |
| Continuous Calling | New contacts should enter an ongoing campaign automatically | Webhook or Google Sheets |
| Batch Calling | You have a fixed list of contacts to call | CSV upload |
After choosing the type, enter a campaign name and select the use case that best describes it.
The use case is more than a label: it sets how the outbound dial queue prioritizes the campaign's calls, such as fresh-lead urgency, reminder timing, callback treatment, or standard pacing. The picker explains what each choice means for dialing. You can change the use case later from the campaign's **General** settings, and the new selection is saved with the campaign.
## Complete campaign setup
The setup has six steps:
1. **Campaign Info:** Name the campaign and choose its use case.
2. **Select Trigger Type:** Configure the webhook, Google Sheets connection, or CSV files that provide contacts.
3. **Add Phone Numbers:** Choose the outbound numbers and how Phonely selects among them.
4. **Set Call Cadence:** Choose the days, time ranges, maximum calls per hour, and any do-not-dial days.
5. **Configure Call Flows:** Select a published outbound flow and map any source fields it needs.
6. **Compliance:** Review and accept the required compliance and Do Not Call acknowledgements.
The setup remains a draft until every required step is complete.
## Configure calling hours
Enable the days when calls may run and add one or more time ranges to each day. **Calls Per Hour** limits how many calls Phonely can place in an hour.
Calling hours are evaluated in each contact's scheduling timezone. Phonely uses the agent timezone unless the campaign maps a timezone field or is configured to infer the timezone from the contact's phone number.
The editor warns when a configured range falls outside 8:00 AM–9:00 PM. This warning does not replace your own compliance review.
### Give a contact its own calling window
When your contact data already says when each person may be called, map **Recipient calling window field** in the campaign's general settings to that source field.
Write each window as a daily time range such as `09:00-17:00`, and separate multiple ranges with a semicolon: `09:00-12:00;13:00-17:00`. Each window is evaluated in that contact's own timezone.
A contact's window can only narrow the campaign's calling hours, never extend them. If a contact's window never overlaps the campaign's hours, that call is held rather than dialed.
## Set do-not-dial days
Use **Do Not Dial Days** in **Set Call Cadence** to keep a campaign from placing calls on specific dates, such as holidays. Add dates in either of two ways:
* Select the **US federal holidays** preset to add its upcoming dates at once.
* Select individual dates on the year calendar.
Date edits are part of the campaign form. They are saved when you select **Save** and discarded if you close the setup without saving. On a do-not-dial day, the campaign shows a **Paused — do-not-dial day** indicator in the campaign list and detail views and resumes automatically on the next allowed day.
Do-not-dial days do not replace the calling-hours, consent, and suppression rules that apply to each contact and jurisdiction.
## Select a flow
A campaign uses one published outbound flow. You can select an existing flow or create one during setup. Map the fields from the campaign source to the variables the flow needs before launching the campaign.
See [Outbound Flows](/outboundcalling/creating-call-flows-for-outbound-campaigns) for the flow requirements.
## Launch and monitor the campaign
After setup, start the campaign from the campaign list. Campaigns appear as **In Progress**, **Paused**, or **Completed** as their status changes.
* Pause a campaign to stop new calls temporarily.
* Resume a paused campaign when it is ready to continue.
* Open the campaign to review its queued and completed calls.
A queued call shows why it has not been dialed yet:
| Status | What it means |
| ------------------------ | ------------------------------------------------------------------ |
| **Queued** | Waiting its turn; nothing is holding it |
| **Queued · After hours** | Waiting for the campaign's calling hours in the contact's timezone |
| **Queued · On hold** | Held by a problem you need to fix |
Hover a held call to see the reason. A call goes on hold when the contact's calling window no longer overlaps the campaign's hours, when that window could not be read, or when the campaign's calling hours are misconfigured. Widen the campaign's hours or correct the contact data to release it.
Before using production contacts, test the selected flow and campaign mappings with contact data and phone numbers you control.
# Outbound Flows
Source: https://docs.phonely.ai/outboundcalling/creating-call-flows-for-outbound-campaigns
Build and select the flow that handles calls from an outbound campaign.
An outbound campaign must use a published outbound flow. The flow starts with **Make Call** and controls the conversation, routing, actions, and post-call work for every contact the campaign calls.
## Select or create the flow
In **Configure Call Flows**, select a published outbound flow. If no suitable flow exists, create one from the campaign setup and edit it on the flow canvas.
Only outbound flows appear in the selector. An inbound flow cannot be converted into an outbound flow after it is created.
## Configure Make Call
**Make Call** is the trigger for an outbound flow. Configure its greeting and voicemail behavior, then connect the live-call and post-call blocks the campaign needs.
The campaign determines the contact and outbound phone number. The flow determines what the agent says and does after the call begins.
## Map campaign data
Campaign source fields can be mapped to the inputs used by the flow. Map a field when the flow needs that value for personalization, routing, or an action.
For example, a source may provide `name`, `appointment_time`, and `account_id`. Once mapped, supported fields in the flow can select those values from **Available Variables**.
If you change the CSV columns, webhook fields, Google Sheets columns, or variables used by the flow, return to the campaign and review the mappings.
## Test before launch
1. Test the outbound flow with representative source values.
2. Publish the flow version you intend the campaign to use.
3. Verify the campaign's field mappings and phone-number routing.
4. Run a controlled campaign call to a number you own.
Confirm the greeting, conversation paths, actions, voicemail behavior, and post-call work before adding production contacts.
# Upload Contacts by CSV
Source: https://docs.phonely.ai/outboundcalling/uploadingcsv
Add a fixed contact list to a batch campaign and map its columns.
Batch campaigns receive contacts from CSV files. Each row represents one queued call, and the column names become fields that the campaign can map to phone numbers, timezones, and flow variables.
## Prepare the CSV
* Include a header row with non-empty, distinct column names.
* Include a phone-number column with country codes where required.
* Keep each file at or below 10 MB.
* Remove contacts that should not be called before uploading the file.
Use consistent values within each column. For example, keep phone numbers in one format and use valid timezone values if the campaign maps a timezone field.
To control when individual contacts may be called, add a column of daily time ranges such as `09:00-17:00`, using a semicolon between multiple ranges. See [calling windows](/outboundcalling/createaoutboundcallingcampaign#give-a-contact-its-own-calling-window) for how they interact with the campaign's hours.
## Upload and map the fields
1. Create or edit a **Batch Calling** campaign.
2. Upload one or more CSV files in **Select Trigger Type**.
3. Review the detected columns.
4. Map the contact phone number and any optional timezone, dial-out-number, or calling-window fields.
5. In **Configure Call Flows**, map the source fields used by the selected flow.
If the file or its headers change, review every mapping before starting the campaign.
## Verify the import
Use a small CSV containing phone numbers you control. Confirm that each row enters the campaign with the expected values and that the outbound flow receives its mapped variables.
Uploading a CSV can queue real outbound calls once the campaign is running. Verify the list, cadence, phone-number routing, and compliance settings before starting it.
# Webhook Triggers
Source: https://docs.phonely.ai/outboundcalling/webhookconnection
Send contacts from an external system to a continuous outbound campaign.
Use a webhook when an external system should add contacts to a **Continuous Calling** campaign. Each accepted request adds a call to the campaign queue; the campaign cadence determines when that call can run.
Phonely does not deduplicate accepted webhook requests. If the sending system retries a request, it can queue another call. Prevent duplicate requests before sending them when one contact should produce only one call.
## Configure the webhook
1. Create or edit a Continuous Calling campaign.
2. In **Select Trigger Type**, choose **Webhook**.
3. Copy the generated webhook URL and authorization details.
4. Define the JSON request body, then select **Set Fields**.
5. Map the detected fields to the contact phone number, optional timezone, dial-out number, or calling window, and any variables used by the outbound flow.
The default body includes `phone_number`, `timezone`, `dialout_number`, and `calling_window`. You can add fields required by your flow.
```json theme={null}
{
"phone_number": "+12125551234",
"timezone": "America/New_York",
"dialout_number": "+12125559876",
"calling_window": "09:00-12:00;13:00-17:00",
"customer_name": "Jordan Lee"
}
```
A `calling_window` narrows the campaign's calling hours for that contact only. See [calling windows](/outboundcalling/createaoutboundcallingcampaign#give-a-contact-its-own-calling-window).
Send JSON with the authorization required by the generated webhook. Keep the credential private and do not place it in client-side code, screenshots, or documentation examples.
## Keep the schema aligned
Select **Set Fields** whenever you add, rename, or remove a top-level field. Then review the campaign mappings and any downstream flow fields that use those values.
## Verify the trigger
Use a phone number you control and send a representative request. Confirm that:
1. the call appears in the campaign queue;
2. the phone number, timezone, and optional dial-out number or calling window resolve correctly; and
3. the selected flow receives the expected mapped values.
Testing the webhook can queue and place a real outbound call when the campaign is running.
# Performance
Source: https://docs.phonely.ai/performance
Build a board of cards that measure call volume, outcomes, topics, and end reasons across an agent's calls.
Performance turns an agent's call history into a board of cards that help you understand traffic, results, and recurring patterns.
Performance reports on the agent's real phone traffic. Web calls are excluded from every card, drilldown, and filter, and **Call type** does not offer that value.
Open **Performance** and choose an agent. The page is a single board: every chart, table, and big number on it is a card you can arrange, retype, and drill into.
Data Tables and Proactive Monitoring are no longer separate tabs. Existing data tables are converted to cards the first time you open the page, and a one-time note tells you which view received them. Proactive Monitoring opens in a side panel from the account menu or a report link.
## Filter the calls
The date range and filters in the header apply across the active view. The board's filter controls include call status, call type, and the Phonely phone number. Filters you set appear as chips in the header; remove a chip to clear that filter.
For a question about particular outcomes, topics, end reasons, sentiments, or flow blocks, open the card in **Explore** and use **Only count calls where…** to set its own conditions. Save a filter when you want to reuse the same definition across cards. For example, define which calls count as a booked appointment, then use that definition on each relevant card.
Older board-wide outcome, topic, end-reason, sentiment, caller-number, duration, and flow-block filters are no longer retained. Review older views before comparing their totals with earlier reports, and recreate supported conditions on the relevant cards.
## Read the cards
**Add widget** opens a dialog with guided creation and preset cards. Before your first guided request, describe your business goal and north star metric—the main measure of success you want to track—then select **Save and continue**. Describe the card you want and review the proposal before adding it. Use **Change business goal and north star metric** in the dialog to revise those answers later.
You can also pick a preset directly. On an empty view, you can ask Phonely to suggest a starting board built from the agent's own flow and outcomes. Preset cards cover common questions:
| Card | What it shows |
| ----------------------- | -------------------------------------------------------------- |
| **Calls over time** | Call volume across the selected range |
| **Total calls** | A single number for the range |
| **Average call length** | Mean call duration |
| **Calls by outcome** | Calls grouped by the outcome recorded by the flow |
| **Outcome detail** | Outcomes with supporting metrics in a table |
| **Unique customers** | The number of distinct customers, deduplicated by phone number |
A unique count deduplicates by customer phone number within each time bucket or breakdown group. A customer who appears in more than one group is counted once in each, so grouped unique counts do not add up to an overall customer total. Pie charts and stacking are unavailable for unique counts.
Select a segment, point, or row to open the matching calls. This lets you move from an aggregate pattern to the conversations behind it.
Each card shows when its data was last updated. Hover a number to see the count or share behind it.
### Change how a card looks
Open a card's **More options** menu to switch between **Time series**, **Bar chart**, **Big number**, **Metric bars**, **Top list**, **Table**, and **Pie**, where compatible. Unavailable types are greyed out with instructions for unlocking them. **Metric bars** requires no breakdown and at least two displayed metrics that share a unit.
An existing **Sankey** card keeps its own chart type. You cannot convert an ordinary card to Sankey from this menu.
Switching the type changes the presentation only. It never changes the number a card computes.
### Arrange the board
* Drag a card to reorder it.
* Drag a card's edge or corner to resize it.
* Select **Edit in Explore** (the pencil) to change the question behind a card.
* Use **More options** to duplicate a card, copy it to another view, export its data, or remove it from the view.
Layout changes belong to the active view. If a board cannot be saved, the header shows a **Not saved** warning; select it to retry.
You can also add a card from the board's own empty space: a **+** tile in the last row's leftover columns opens the same **Add widget** dialog.
## Build your own card
Select **Add widget**, then **Build a widget manually** to open **Explore**.
Explore replaces the board while you work in it. Build a question by choosing what to count, how to break it down, and which calls to include:
| Part | Purpose |
| ---------------------- | -------------------------------------------------------- |
| **Entity and measure** | What each number counts, such as calls or a saved metric |
| **Breakdown by** | What each series, slice, or row represents |
| **Filters** | Which calls contribute to the result |
Save the result to add it to the board. Use the browser's Back button or the back arrow to leave Explore; if you have unsaved work, Phonely asks before discarding it.
You can save a metric or filter to reuse it across cards, and manage those saved definitions from Explore. Deleting a saved definition asks for confirmation and identifies the metric or filter to be removed.
## Edit Performance with Ask AI
While **Performance** is open, use [Ask AI](/key-concepts/ask-ai) to add, edit, or remove cards; create, rename, duplicate, reorder, or delete views; or propose changes to saved metrics and filters. State the view and business question you want to change, such as "Add a card showing booked appointments over time."
Review each proposal's preview, affected view, and definition before accepting it. Adding or editing a card offers **Add to board** or **Apply change**; other proposals show the action they will perform. Reject a proposal you do not want. Asking for a change does not apply it automatically.
Use the proposal's **Undo** action when available to reverse an accepted change. You can also open a proposed card in Explore to refine it manually. If you accept an edit while that card is open in Explore, inspect the updated preview and save from Explore when it is ready.
Changing a saved metric or filter can affect cards that use it. Ask AI cannot delete a saved definition while cards still reference it; update those cards first.
## Work with views
A view keeps a board's cards, filters, and settings for an agent. Use the view selector to switch between them and its menu to create, rename, duplicate, reorder, or delete a view.
Use separate views for questions that need different scopes, such as weekly operations, negative-sentiment calls, or a specific outcome. Give each view a name that describes the question it answers.
## Interpret the results
* Use **outcomes** to measure results recorded by flows or updated after a call.
* Use **topics** to understand what callers discussed.
* Use **end reasons** to understand how calls stopped.
* Open the underlying calls before treating a change on a card as a product or flow issue.
Keep the date range and filters consistent when comparing results. A change in scope can look like a change in agent performance.
# Post-Call Outcomes
Source: https://docs.phonely.ai/post-call-outcomes
Record business results that become known after a call.
Post-call outcomes record a business result that is added or confirmed after a call, such as a completed sale, attended appointment, or later follow-up result.
They are different from the call outcomes configured on flow blocks:
| Value | When it is recorded |
| --------------------- | ----------------------------------------------------------------------------------------------------- |
| **Call outcome** | When a call reaches a block with [Call Outcome Tagging](/blocks/common-settings#call-outcome-tagging) |
| **Post-call outcome** | When an external system updates the completed call through the API |
Use a post-call outcome when the final result is not reliably known while the call is running.
## Record an outcome
Update the completed call with the [Set Post-Call Outcome endpoint](/api-reference/endpoint/set-post-call-outcome). The request can include:
| Field | Purpose |
| --------------------------- | ------------------------------------------- |
| `custom_call_outcome` | A label for the result |
| `custom_call_outcome_value` | A numeric value associated with the result |
| `custom_call_metadata` | Additional structured metadata for the call |
Use stable labels such as `Sale completed` or `Appointment attended`. Avoid creating multiple labels that mean the same thing, because each distinct label becomes a separate reporting value.
## Review recorded outcomes
In the agent's **Settings**, open **Analytics**. **Post-Call Outcomes** lists labels already recorded through the API, including when each label was first and last recorded and its total call count.
This list is read-only. It is updated automatically as completed calls receive outcomes.
Post-call outcomes and their numeric values can also be used in Performance filters and Data Table metrics.
Updating a post-call outcome changes reporting data for that call. It does not change the flow that handled the conversation.
# A/B Testing
Source: https://docs.phonely.ai/testing/ab-testing
Compare a control agent with a variant using live call traffic.
A/B Testing compares your current agent, the **Control**, with a duplicated **Variant** using live calls. Phonely routes the configured share of calls to the variant and evaluates both agents against the same success criterion. Tests can run on the calls your agent answers, on the calls it places, or on both.
Use [Unit Testing](/testing/simulation-testing) for repeatable generated scenarios before exposing changes to live traffic.
## Create a test
Open **Testing > A/B Testing** and create a test in **Planned**. The setup has four parts:
| Step | What you configure |
| ---------------- | -------------------------------------------------------------------------------------------------------------- |
| Test details | Name, description, the category of change, and which calls the test runs on |
| End criteria | Stop after a number of calls or a number of days |
| Traffic split | The percentage of calls sent to the variant, from 1% to 100% in 1% steps; the remainder stays with the control |
| Success criteria | The call outcome, ended reason, or call-duration direction that counts as success |
The category—**Voice**, **Workflow**, **Agent Settings**, **Knowledge Base**, or **Other**—labels what you intend to compare. It does not restrict which variant settings you can edit.
### Choose which calls the test runs on
A **Workflow** test asks which calls it should run on. Choose one:
| Choice | What it splits |
| ------------------ | ----------------------------------------- |
| **Inbound calls** | The calls your agent answers |
| **Outbound calls** | The calls placed by campaigns and the API |
Every other category splits calls in both directions, as do workflow tests created before this choice existed.
When a test includes outbound calls, use **Include voicemail calls in results** to decide whether outbound calls that reach voicemail count toward the result. It is off by default, so those calls are excluded until you enable it.
Success-criteria options follow that choice for workflow tests: outcome tags come from the selected direction's calls only, and an inbound test does not offer the **Voicemail** ended reason.
When choosing successful outcomes or ended reasons, search to narrow the options. **Select all N results** selects the matching options and keeps any selections outside the search. If all matches are already selected, selecting it again clears only those matches. Clear the search and review the full selection before starting the test.
### Edit the variant
Creating a test duplicates the control agent. Make the change you want to measure, then keep unrelated settings aligned so the result remains interpretable.
* Most tests open the variant in the agent editor through **Edit variant agent**.
* An outbound workflow test opens the variant's call flow instead. **Edit variant flow** takes you to the campaign page's call-flow canvas, where the Campaigns view is hidden and a chip marks the surface as the variant.
Select **Back to tests** in the notice that stays on screen while you edit to return to Testing.
## Start and manage the test
Review the variant before selecting **Begin Test**. While a test is in progress, eligible calls are assigned to the Control or Variant according to the traffic split.
The test appears in one of three sections:
* **Planned** has been configured but is not routing calls.
* **In Progress** is currently routing live calls.
* **Completed** has reached its end criterion or was terminated.
You can adjust the traffic split while a test is in progress. Terminating a test stops new calls from being assigned to it; it does not undo calls already completed.
A/B Testing affects live traffic. Test the variant independently and begin with a traffic share appropriate for the risk of the change.
## Review the result
Open a test to compare completed calls, successful calls, and success rates for the Control and Variant. You can also open the calls assigned to either arm and inspect them in Call History.
Phonely calculates success from the criterion selected during setup:
* **Call Outcome** counts calls with one of the selected outcomes.
* **Call Ended Reason** counts calls with one of the selected ended reasons.
* **Call Duration** compares whether shorter or longer calls better match the goal.
The result may also show the difference between success rates, the probability that the variant wins, a p-value, and a confidence interval. Treat these as evidence from the calls collected so far, not a guarantee about future calls. A small sample or an interval that crosses zero means the result remains uncertain.
If you decide to keep the variant, apply it deliberately and complete an end-to-end test of the resulting control agent. Do not assume every variant difference should be promoted simply because one metric improved.
Confirm that the agent is receiving eligible live calls and review the configured traffic split. Random assignment can be uneven in a small sample; allow enough calls before interpreting the result.
Review the selected success criterion and the affected calls. Confirm that their outcome, ended reason, or duration matches the values configured for the test.
Review the completed-call count and confidence interval. Continue the test when appropriate, or conclude that the measured change did not produce a reliable difference within the collected sample.
# Unit Testing
Source: https://docs.phonely.ai/testing/simulation-testing
Run repeatable AI-generated conversations and evaluate how your agent responds.
Unit Testing runs AI-generated conversations against your agent before you rely on a change in live calls. Use it to exercise a defined scenario repeatedly, check expected behavior, and compare results across runs.
Unit tests complement—not replace—[Web Chat, Web Call, and phone testing](/flow-editor/test-and-publish). They are most useful for repeatable scenarios and regression checks.
## Create a test case
Open **Testing > Unit Testing**, select **Test Cases**, then add a test case.
| Setting | What it controls |
| ------------- | ---------------------------------------------------------------- |
| Case Name | Identifies the scenario in the test list and results |
| Description | Describes the caller, situation, and behavior to exercise |
| Test Instance | How many conversations to run for the scenario |
| Variance | How much the generated conversations may differ from one another |
Write the description as a concrete caller scenario. Include the caller's goal and any important constraints, but do not prescribe the agent's response—the agent should follow its own configuration.
Each test run can incur usage charges. The current limits and price are shown in the test form before you run it.
## Choose data sources and evaluators
Use **Data Sources** to define the conversations or criteria associated with a test case:
* **Call Recordings** are recordings you upload for testing.
* **Phonely's Calls** are calls already handled by the agent.
* **AI Evaluator** defines an AI-generated caller and the criteria used to judge the interaction.
Select only sources that represent the behavior you want the test case to cover. Keep evaluators focused on one scenario so a failed result is easier to understand.
## Run tests
Run an individual test case from its card, or select **Run All Tests** to run every configured case for the agent. Phonely moves the new run to **Test Results** while it is processed.
Changing the agent does not retroactively change an earlier result. Run the relevant cases again after modifying prompts, flows, knowledge, voice behavior, or other settings that affect the scenario.
## Review results
Open **Test Results** and select a run to review its overall result and individual test instances. The result identifies the test case snapshot, AI evaluator, and status for each generated conversation.
Review failed and inconsistent instances individually. A useful follow-up is to compare their conversation paths and determine whether the issue comes from the scenario, the evaluator, or the agent configuration.
Make the test case description more specific, confirm that the selected data sources and evaluator represent the intended scenario, then run it again. Also verify that the agent version you intended to test contains the relevant changes.
Lower **Variance**, narrow the scenario, and separate unrelated goals into different test cases. Some variation is expected because the conversations are generated by AI.
Refresh **Test Results** and retry the case. If it fails again, reduce the number of instances and verify that the agent and selected data sources are still available.
# Flow Checklist
Source: https://docs.phonely.ai/workflow-checklist
Find and resolve flow errors before publishing.
The **Flow Checklist** reports reachable block errors, publish-review findings, and whether the flow has a published version. Select the clipboard icon beside **Publish** to open it. A badge appears when a check needs attention.
![Flow Checklist open beside Publish, showing a published version, two blocks with errors, their validation messages, and the Go to action]()
## What the checklist checks
| Check | What it means |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Published version** | Whether the flow has been published at least once. Without one, Phonely falls back to the current draft. This is a warning, not a publishing blocker. |
| **Block errors** | Whether a trigger or action block reachable from the flow's entry point has missing connections, invalid variables, or incomplete required settings. These errors prevent publishing. |
| **Publish review** | Advisory findings from the AI review that runs when you publish. Review or fix relevant findings, or choose **Publish anyway** when the draft is ready. |
When every check passes, the panel shows **All issues are resolved**.
## Fix block errors
1. Open the **Flow Checklist**.
2. Review the messages shown under each affected block.
3. Hover over a block entry and select **Go to**. Phonely centers the block on the canvas and opens its configuration panel.
4. Correct each connection, variable, or setting named in the messages.
5. Reopen the checklist and confirm that the block no longer appears.
## What passing the checklist means
The checklist evaluates the current draft and updates as you edit it. Publishing remains blocked while a reachable block has errors. An unconnected block parked on the canvas is not part of the executable flow and does not block publishing until it becomes reachable.
Resolving the blocking checks confirms that required configuration is present; it does not prove that every conversation path behaves as intended. Test important routes, fallbacks, transfers, and post-call actions before relying on the flow for live calls.
See [Test and Publish](/flow-editor/test-and-publish) for the complete edit, validate, publish, and test process.