# CLAUDE
Source: https://docs.thoughtly.com/CLAUDE
# Mintlify documentation
## Working relationship
* You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
* ALWAYS ask for clarification rather than making assumptions
* NEVER lie, guess, or make up information
## Project context
* Format: MDX files with YAML frontmatter
* Config: docs.json for navigation, theme, settings
* Components: Mintlify components
## Content strategy
* Document just enough for user success - not too much, not too little
* Prioritize accuracy and usability of information
* Make content evergreen when possible
* Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
* Check existing patterns for consistency
* Start by making the smallest reasonable changes
## docs.json
* Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation
## Frontmatter requirements for pages
* title: Clear, descriptive page title
* description: Concise summary for SEO/navigation
## Writing standards
* Second-person voice ("you")
* Prerequisites at start of procedural content
* Test all code examples before publishing
* Match style and formatting of existing pages
* Include both basic and advanced use cases
* Language tags on all code blocks
* Alt text on all images
* Relative paths for internal links
## Git workflow
* NEVER use --no-verify when committing
* Ask how to handle uncommitted changes before starting
* Create a new branch when no clear branch exists for changes
* Commit frequently throughout development
* NEVER skip or disable pre-commit hooks
## Do not
* Skip frontmatter on any MDX file
* Use absolute URLs for internal links
* Include untested code examples
* Make assumptions - always ask for clarification
# Actions
Source: https://docs.thoughtly.com/agents/actions
Trigger integrations mid-call so your Thoughtly agent can look up data, write CRM records, send messages, and automate workflows in real time.
Trigger integrations mid-call so your agent can look up data, write records, and automate workflows. Add actions to a [Speak node](/agents/nodes#speak-node) to run them mid-call.
Add actions from a Speak node by opening **Actions** and clicking **+ Add new action**. Choose an integration, configure it, and reference your [Variables](/agents/variables) inside the action fields. If you have multiple accounts connected for the same integration, select which account to use in the **Account** tab.
Actions appear in a compact list view. Hover over an action to reveal the drag handle icon, which lets you reorder actions by dragging. Click anywhere on an action row to edit its configuration.
### Action display names
You can set a custom **Display Name** for each action to make your workflow easier to read and maintain. This label appears in the action list and helps you quickly identify what each action does, especially when you have multiple actions of the same type.
To set a display name:
1. Click on an action to open its configuration
2. Enter a name in the **Display Name** field at the top of the sidebar
3. The name will appear in the action list instead of the default integration action name
If no display name is set, the action shows its default integration name (for example "Send Email" or "Create Contact").
### Action ID reference
Each action has a unique identifier in the format `nodeId.actionId`. You can copy this ID using the copy button in the action header when viewing an action's configuration. Use this ID to reference specific action outputs in variables or outcomes.
## How mid-call actions change the flow
**Without actions:** caller responds -> variables extract -> outcomes evaluate -> next node.
**With actions:** the node auto-proceeds without waiting for another caller reply.
1. Agent speaks (Message or Prompt).
2. Action(s) run mid-call (interruptions disabled by default).
3. Variables update from action results.
4. Outcomes evaluate (rule-based outcomes recommended).
5. Next node executes.
Because the caller does not speak before outcomes fire, use rule-based outcomes that check action results (for example `lookup_found == true`, `action_status == "ok"`). Prompt-based outcomes do not automatically "see" internal values unless you surface them in the spoken conversation.
## Recommended patterns
### 1) Lookup -> Branch
**Goal:** Route based on CRM or API results.
* **Action:** CRM or webhook lookup using key fields (phone, email, account ID).
* **Variables:** `lookup_found` (boolean), `customer_id` (text).
* **Outcomes (rule-based):**
* `lookup_found == true` -> enriched path (use variables like `first_name`).
* `lookup_found == false` -> collect details before moving on.
### 2) Validate -> Retry loop
**Goal:** Ensure a required field is valid before proceeding.
* **Action:** Validator or API check (for example email verification).
* **Variables:** `email`, `email_valid` (boolean).
* **Outcomes (rule-based):**
* `email_valid == true` -> next step.
* Else -> self-loop to the node asking for email again (limit retries). See [Outcomes -> Loops](/agents/outcomes#loops-special-use-case).
### 3) Book -> Confirm
**Goal:** Schedule an appointment during the call.
* **Action:** Scheduler integration (calendar, booking tool).
* **Variables:** `timeslot_chosen`, `booking_status`.
* **Outcomes (rule-based):**
* `booking_status == "confirmed"` -> confirmation message then [Transfer](/agents/nodes#transfer-node) or [End](/agents/nodes#end-node).
* Else -> offer alternatives or transfer to a human.
```mermaid theme={null}
%%{init: {'theme':'base', 'themeVariables': { 'fontSize':'18px'}}}%%
graph TD
A["📅 Speak Node: Collect Appointment Time"] --> B["⚡ Action: Schedule Appointment"]
B --> C{"✓ Check booking_status"}
C -->|"✓ confirmed"| D["💬 Speak: Confirmation Message"]
C -->|"✗ failed/error"| E["💬 Speak: Offer Alternative Times"]
D --> F["✅ Transfer or End Call"]
E --> G["☎️ Transfer to Human"]
style A fill:#e3f2fd,stroke:#1976d2,stroke-width:4px,color:#000
style B fill:#fff3e0,stroke:#f57c00,stroke-width:4px,color:#000
style C fill:#f3e5f5,stroke:#7b1fa2,stroke-width:4px,color:#000
style D fill:#e8f5e9,stroke:#388e3c,stroke-width:4px,color:#000
style E fill:#ffebee,stroke:#d32f2f,stroke-width:4px,color:#000
style F fill:#e8f5e9,stroke:#388e3c,stroke-width:4px,color:#000
style G fill:#ffebee,stroke:#d32f2f,stroke-width:4px,color:#000
```
## Authoring tips
* **Interruptions:** Stay disabled by default for mid-call actions to prevent the caller from breaking the integration flow. If you enable interruptions, plan for partial inputs.
* **Speak node choice:** Use Message mode for fixed pre/post phrases. Use Prompt mode when the agent must compose dynamic summaries from action results.
* **Lean payloads:** Send only the variables you need. Clear, minimal fields reduce errors.
* **Preface long actions:** Add a short line like "One moment while I check that" before triggering an action to set caller expectations.
* **Structured outputs:** Set predictable fields (such as `action_status = "ok"` or `"error"`) to simplify rule checks.
## Error handling and resilience
Design outcomes for real-world hiccups:
* **Happy path:** `action_status == "ok"` will proceed.
* **Recoverable:** `action_status == "error"` will retry
* **Fallback:** persistent failure -> transfer to a human or offer a call-back.
* **Timeouts:** if an action exceeds your expected SLA, branch to a graceful message and continue.
**Caller experience guardrails**
* Use **Uninterrupted message** for pre-action instructions so the agent is not cut off mid-sentence.
* For actions that take several seconds, add a short progress update after a couple of seconds to reduce perceived wait time.
## Data flow and variables
* Action outputs can set or update [Variables](/agents/variables) such as `customer_id`, `plan`, or `lookup_found`.
* These values are immediately available to rule-based outcomes in the same node.
* If you need AI to summarize results, surface key values verbally in a Prompt speak node after the action completes.
## Setup checklist (quick start)
* [ ] Open a [Speak node](/agents/nodes#speak-node)
* [ ] Click **Add action** and choose an integration
* [ ] Select which account to use (if you have multiple accounts for the same integration)
* [ ] Configure fields (URL, method, headers, body)
* [ ] Map your [Variables](/agents/variables) to action inputs
* [ ] Add rule-based [Outcomes](/agents/outcomes) that check action results
* [ ] Test the flow using [Test Agent](/agents/testing)
* [ ] Review action logs and outputs
* [ ] Verify error handling branches are in place
## Common mistakes to avoid
* Relying on prompt-based outcomes immediately after actions; they cannot see internal flags unless you speak them.
* Skipping error branches or default outcomes, which can stall the flow.
* Forgetting to cap retries or offer a human hand-off.
* Fetching more data than you need.
* Re-enabling interruptions and losing action results mid-flow.
## See also
* [Speak nodes](/agents/nodes#speak-node) - where actions live.
* [Variables](/agents/variables) - read and write values used by actions and rules.
* [Outcomes](/agents/outcomes) - build deterministic branches after actions.
* [Transfer node](/agents/nodes#transfer-node) - escalate on errors or high intent.
# Call screening bypass
Source: https://docs.thoughtly.com/agents/call-screening-bypass
Configure outbound voice agents to detect and respond to call-screening prompts like name and reason gates so they reach a live person every time.
Call screening bypass helps a Thoughtly voice agent handle automated screening prompts at the start of outbound calls. When a screening service asks who is calling, which company they represent, or why they are calling, the agent can respond before continuing the normal conversation flow.
This is useful for outbound teams that call contacts who use phone screening, spam protection, virtual receptionists, or device-level call filters.
Call screening bypass helps agents respond to screening prompts. It does not guarantee that every carrier, device, app, or receptionist will connect the call.
## How it works
When enabled, the agent begins with a short screening stage before the main conversation. During that stage, it listens for screening prompts and answers with the information you configure.
Typical screening prompts include:
* “Who is calling?”
* “What company are you calling from?”
* “What is the reason for your call?”
* “Please state your name after the tone.”
After the screening interaction completes and the recipient answers, the agent continues into the normal start node or call flow.
## Setup fields
Configure screening responses with clear, short values:
| Field | Description | Example |
| ------------------ | -------------------------------------------------------- | ------------------------------------------ |
| Agent name | The name the agent should give when asked who is calling | “Ava” |
| Company name | The business represented by the agent | “Acme Home Services” |
| Reason for calling | A concise reason that sounds natural to the recipient | “following up on your appointment request” |
## Writing a good reason for calling
Keep the reason specific, truthful, and short.
Good examples:
* “following up on your quote request”
* “calling about your upcoming appointment”
* “returning your request for more information”
Avoid vague or spammy phrasing:
* “important business matter”
* “urgent opportunity”
* “please answer this call”
## Testing
To test call screening bypass:
1. Enable screening bypass on the agent or phone number where available.
2. Place a test call to a number that uses call screening.
3. Review the call transcript in [History](/platform/history).
4. Confirm the screening response is accurate and the agent continues the main flow after connection.
## Relationship to branded calling
Call screening bypass and branded calling solve different trust problems:
* **Call screening bypass** helps the agent answer automated screening prompts.
* **Branded calling** helps the recipient see a verified business name or identity on supported carriers/devices.
Use both when available for high-volume outbound workflows.
# Deploy a voice agent
Source: https://docs.thoughtly.com/agents/deployment
Publish your Thoughtly voice agent, assign a phone number, and start handling inbound calls or launching outbound campaigns in production.
## Deploying your first Voice Agent
Now that you've [built your Voice Agent](/agents/overview), it's time to deploy it and start making calls. Inbound deployment is quite different from outbound deployment, so we'll cover both here.
Simply put, inbound calls can be easily handled by connecting a phone number, while outbound calls often require the use of [Automations](/automations/getting-started) to trigger the call.
## Inbound Deployment
Inbound deployment is the process of connecting a phone number to your Voice Agent so that it can receive calls. You can either buy a new phone number from Thoughtly or forward calls from your existing phone number to your Voice Agent.
### Methods
Below are the two methods for inbound deployment. Choose the one that best fits your needs and read the corresponding documentation to get started:
1. **[Buying phone numbers](/phone-number/getting-started)**: Purchase a new phone number from Thoughtly and connect it to your Voice Agent. This is the easiest way to get started– all you have to do is share your new phone number with customers.
2. **[BYOC - Bring Your Own Carrier](/phone-number/byoc)**: Purchase new numbers or import existing numbers from Twilio/Telnyx carriers. You can also forward calls from your existing phone number to your Voice Agent.
## Outbound Deployment
Outbound deployment is the process of making calls from your Voice Agent. You can use Automations to trigger outbound calls based on certain conditions, such as a new lead being added to your CRM.
### Recommended Prerequisites
Before you deploy your Voice Agent, we recommend that you complete the following steps:
1. **Voicemail**: If you plan on making outbound calls, you may want to set up [Voicemail](/agents/settings#voicemail) to leave a message if the call goes unanswered.
2. **Automations**: If you plan on making outbound calls, you'll need to set up [Automations](/automations/getting-started) to trigger those calls. Make sure to read the [Automations documentation](/automations/getting-started) to get started.
3. **Phone Numbers**: If you plan on making outbound calls, you'll need to have a phone number connected to your Voice Agent. You can either [buy a new phone number](/phone-number/getting-started) or use an existing one.
## SMS
In addition to making and receiving calls, your Voice Agents can also send and receive SMS messages. This can be a powerful tool for customer engagement, especially when used in conjunction with your Voice Agent on phone calls.
SMS messages can be sent during calls or as part of automation workflows using the [Send SMS action](/automations/actions#messaging-and-inbound). You can send text messages to share links, collect information, or provide additional context.
SMS can also be used to follow up with customers after the call has ended, or if the call was missed, by using [Automations](/automations/getting-started).
# Migrate legacy agents to v1.8 Agent Builder
Source: https://docs.thoughtly.com/agents/migration-guide
Step-by-step guide for rebuilding legacy v1 free-form Thoughtly agents in the v1.8 node-based Agent Builder with parity for prompts, actions, and flows.
**v1 agents were retired on February 16, 2026.** v1 agents are no longer supported. If you haven't migrated yet, follow this guide to rebuild your agent in v1.8 as soon as possible.
This guide walks you through rebuilding a legacy **v1 "free-form"** agent in the **v1.8 [Agent Builder](/agents/overview)**.
***
## The migration mindset
**v1** let builders "jump around" with rules and loosely structured prompts.
**v1.8** is more structured:
* You build a conversation as a graph using **four node types**: [Start](/agents/nodes#start-node), [Speak](/agents/nodes#speak-node), [Transfer](/agents/nodes#transfer-node), [End](/agents/nodes#end-node).
* **Speak** is split into two variants:
* **Message** (fixed wording, can be verbatim).
* **Prompt** (adaptive instructions, like a mini playbook).
* [Outcomes](/agents/outcomes) decide where the conversation goes next (and are where "rules" belong now). Unlike in **v1**, outcomes in **v1.8** agents are more strict. The agent will not jump from the first node to the last. This allows for more robust workflows while keeping flexibility.
* [Variables](/agents/variables) capture structured data *right after the caller replies and before outcomes evaluate* so outcomes can branch on fresh values.
* [Actions](/agents/actions) run integrations mid-call and change flow timing.
***
## v1 to v1.8 mapping (quick translation table)
| v1 concept | v1.8 replacement | Notes |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| "Opening script" | [**Start node**](/agents/nodes#start-node) | Start is spoken exactly as written; great for consent/compliance lines. |
| Mixed "message/prompt" block | [**Speak -> Message**](/agents/nodes#speak-node) or [**Speak -> Prompt**](/agents/nodes#speak-node) | Use **Message + Repeat verbatim** for exact lines; use **Prompt** for dynamic responses. |
| Rule-heavy branching | [**Outcomes**](/agents/outcomes) | Use **rule-based outcomes** for deterministic branching; **prompt-based outcomes** for intent classification. |
| "Ask question + parse answer" via rules | [**Variables**](/agents/variables) | Variables extract before outcomes; define clear extraction instructions. |
| "Jump anywhere", use rules for navigation | **Explicit node connections + loops** via [Outcomes](/agents/outcomes#loops-special-use-case) | Use outcomes + loop patterns for retries/clarification. |
| Knowledge stuffed in prompt/rules | [**Genius knowledge base**](/genius/getting-started) + [attach to agent](/genius/agent-binding) | Strongly prefer Q\&A formatting for retrieval speed and accuracy. |
***
## Step-by-step migration process
### Step 1: Inventory your v1 agent (before you touch v1.8)
Create a quick "agent spec" from the v1 setup:
* Primary goal (qualify, schedule, support, collections, and so on).
* Required **verbatim** lines (consent, disclaimers, identity statements) using [Start](/agents/nodes#start-node) or Speak -> Message in [Speak nodes](/agents/nodes#speak-node).
* Your **major branches** (happy path, objections, voicemail/no-answer, escalation) mapped to [Outcomes](/agents/outcomes).
* What data you capture, **if any** (name, email, intent, budget, eligibility) as [Variables](/agents/variables).
* Which integrations you hit, **if any** (CRM lookup, scheduler, webhook, ticketing) as [Actions](/agents/actions).
This becomes your blueprint for the v1.8 flow.
***
### Step 2: Rebuild the skeleton with nodes
In v1.8, every agent starts with [Start (step 0)](/agents/nodes#start-node) and then flows through numbered nodes (step 1, 2, 3). These step numbers show up during [Testing](/agents/testing) and can be referenced later.
Recommended skeleton:
1. **Start**: tight opener (+ verbatim compliance line if needed).
2. **Speak (Prompt)**: what the agent is supposed to say. Do not put too much text in a single node; if it makes sense, split it. See [Speak nodes](/agents/nodes#speak-node).
3. Branch to a few "big rocks" (for example Qualified / Not qualified / Objection / Transfer) using [Outcomes](/agents/outcomes).
4. **End** nodes for each major ending state (success, voicemail, no-match) using [End nodes](/agents/nodes#end-node).
***
### Step 3: Convert v1 "rules" into outcomes (your new routing layer)
[Outcomes](/agents/outcomes) decide **where the conversation goes after a node**.
Use this rule of thumb:
* **[Prompt-based outcomes](/agents/outcomes#prompt-based-outcomes-ai)**: when you need natural-language classification ("is this an objection?", "are they interested?", "did they ask pricing?").
* **[Rule-based outcomes](/agents/outcomes#rule-based-outcomes-deterministic)**: when you have **Variables** or [Action](/agents/actions) flags and want deterministic logic (recommended after actions).
**Migration pattern (common):**
* v1: "If user sounds qualified, go to scheduling; else ask more questions."
* v1.8: Speak node -> prompt-based outcomes:
* "User said *something* that qualifies them" -> scheduling branch.
* "User did not say *something* that qualifies them" -> clarification branch.
* Default -> fallback / transfer.
**OR**
* v1.8: Speak node -> extract [Variables](/agents/variables) -> rule-based outcomes:
* `qualified == true` -> scheduling branch.
* `qualified == false` -> clarification branch.
* Default -> fallback / transfer.
Loops are a first-class pattern for retries and clarification. Use them deliberately and cap retries. See [Loops](/agents/outcomes#loops-special-use-case).
***
### Step 4: Replace "parsing via rules" with variables
[Variables](/agents/variables) are how you capture structured data for:
* branching in [Outcomes](/agents/outcomes),
* inputs to [Actions](/agents/actions),
* post-call workflows in [Automations](/automations/getting-started).
Key behavior to design around:
* Variables extract **immediately after the caller reply and before outcome evaluation**.
* You can choose **Current speak node** vs **Conversation history** in [Variables](/agents/variables).
* Re-visiting a node can **re-extract and overwrite** previous values (useful for confirmation loops).
***
### Step 5: Migrate integrations to Actions (mid-call)
In **v1**, the only supported mid-call action was **Calendly scheduling**, and it was tightly coupled to rules and implicit flow behavior.
In **v1.8**, scheduling is handled through a **new mid-call [Actions](/agents/actions) framework**, with explicit Speak nodes, [Variables](/agents/variables), Actions, and [Outcomes](/agents/outcomes). Because this is both the **only overlapping mid-call capability** between v1 and v1.8 and the most structurally different, scheduling migration is covered in a dedicated guide.
Continue here:
**[Scheduling in v1.8 (Agent Builder)](/resources/agent-scheduling)**
For action details, see **[Calendly](/integrations/scheduling/calendly)** and **[Cal.com](/integrations/scheduling/cal-com)**.
**Important:** v1 scheduling logic cannot be ported directly. It must be rebuilt using v1.8 patterns (Variables -> Actions -> rule-based Outcomes). Attempting to replicate v1 rule-based scheduling will lead to brittle or broken flows.
***
### Step 6: Move "knowledge inside prompts" into Genius (recommended)
If your v1 agent depended on long prompt/rules to answer FAQs, move that into [Genius](/genius/getting-started):
* Keep content in **Q\&A format** (faster retrieval, better matching).
* Attach the Genius knowledge base to the agent via [Settings -> Genius tab](/agents/settings#genius-tab) or the [Genius binding guide](/genius/agent-binding).
***
### Step 7: Recreate global behavior in Settings (do not bury routing here)
Use [Settings -> Advanced prompt](/agents/settings#advanced-settings) for persona, tone, and guardrails -- **not navigation logic**.
Also migrate/tune:
* **Voice and Language** in [Settings](/agents/settings#main-settings).
* **Presence tuning** (silence timeout; adjust endpointing, sensitivity, retries) in [Settings -> Presence tab](/agents/settings#presence-tab).
* **Voicemail** (keep the message short, avoid sensitive info) in [Settings -> Voicemail](/agents/settings#voicemail).
***
### Step 8: Test like the v1.8 docs recommend (text first, then voice)
Use both built-in testing modes:
* **[Test Agent (text chat)](/agents/testing#test-agent-text-chat)**: fastest for checking outcomes, variables, and action flags.
* **[Call Me (real call)](/agents/testing#call-me-real-call)**: validate TTS, barge-in, endpointing/latency, transfers, and action timing.
***
### Step 9: Cutover (deployment + phone number assignment)
When you are ready to replace v1:
* Assign the appropriate phone number profiles (inbound/outbound/SMS) to the new v1.8 agent. See [Deployment](/agents/deployment) and [Phone Number Configuration](/phone-number/configuration).
***
## Common migration pitfalls (and how to avoid them)
* **Using Prompt when wording must be exact** -> use **Message + Repeat verbatim** (or [Start](/agents/nodes#start-node)).
* **Branching after an Action with prompt-based outcomes** -> use **rule-based outcomes** that check [Action](/agents/actions) flags/results.
* **Vague variable extraction instructions** -> use explicit constraints + "do not invent values" in [Variables](/agents/variables).
* **Special characters being spoken aloud** -> add the "no special characters" instruction to the [Advanced prompt](/agents/settings#advanced-settings) (global fix).
* **Relying on legacy post-call** -> migrate workflows to [Automations](/automations/getting-started) (recommended by docs).
## See also
* [Nodes](/agents/nodes) - Start, Speak, Transfer, End.
* [Outcomes](/agents/outcomes) - routing and loop patterns.
* [Variables](/agents/variables) - extraction and validation.
* [Actions](/agents/actions) - mid-call integrations.
* [Settings](/agents/settings) - voice, presence, and advanced prompt.
* [Testing](/agents/testing) - Test Agent and Call Me.
* [Deployment](/agents/deployment) - go live with phone numbers.
* [Genius](/genius/getting-started) - knowledge base setup.
# Node types in the Agent Builder
Source: https://docs.thoughtly.com/agents/nodes
Reference for every node type in the Thoughtly Agent Builder, including message, decision, action, transfer, and end nodes that shape conversation flow.
Thoughtly agents use four node types: **Start**, **Speak**, **Transfer**, and **End**. Use the canvas toolbar at the bottom center of the screen to manage nodes and organize your flow.
Each node is automatically assigned a sequential step number that helps you track conversation flow during testing and call replay. The Start node is always step 0, and subsequent nodes are numbered sequentially (1, 2, 3, etc.). These step numbers appear in the UI, test logs, and when referencing node responses in variables.
## Canvas toolbar
The canvas toolbar appears at the bottom center of the Agent Builder and provides quick access to common actions:
* **Auto-organize** - Automatically arranges nodes in a clean, readable layout
* **Duplicate** - Clones the selected node with correct positioning (requires a node to be selected)
* **Delete** - Removes the selected node and its connected edges (requires a node to be selected)
* **Add Node** - Opens a menu to create new nodes:
* **Speak** - Creates a speak/question node
* **Transfer** - Creates a transfer\_action node
* **End** - Creates an end node
The Duplicate and Delete buttons are only enabled when you have a node selected on the canvas.
## Start node
**What it does:** Opens the conversation. Whatever you write here is the first thing your caller hears.
**Guidelines**
* Keep it short and attention grabbing.
* Use plain language; avoid jargon.
* Proofread carefully; content in **Start** is repeated verbatim.
**Tips**
* If you need legal or opt-in wording, keep it here so it is always delivered the same way.
* Consider referencing [Variables](/agents/variables) for simple personalization (for example, the caller's first name), but test pronunciation with [Call Me](/agents/testing#call-me-real-call).
Everything in the Start node's **Message** field is spoken exactly as written. Double-check spelling, punctuation, and acronyms.
## Speak node
**What it does:** Drives the conversation. Speak nodes decide what the agent says, how it says it, and when it moves on.
Speak nodes come in two variants: **Message** and **Prompt**.
### 1) Message speak node
* **Use when:** You want the agent to say a specific line (short answer, confirmation, compliance statement) with minimal variation.
* **Behavior:** The agent speaks the text you provide, using context only to keep tone natural.
* **Speech settings:** Click the gear icon in the message header to access speech options:
* **Verbatim:** Say exactly what is written every time (just like the [Start node](#start-node)). Ideal for consent or disclaimers.
* **Uninterrupted:** Prevents the caller from interrupting. Useful for longer instructions or critical copy.
* **Spell Numbers:** Improves pronunciation of long numbers such as order IDs or confirmation codes by reading them digit-by-digit. Pair with [Phone numbers](/phone-number/getting-started) and other numeric data.
* **Good for:** Simple Q\&A, confirmations, disclaimers, short instructions.
A blue indicator dot appears on the settings icon when any speech setting is active, making it easy to see which nodes have special configurations.
### 2) Prompt speak node
* **Use when:** The agent must compose a response using multiple pieces of information (purchase details, caller info, integration outputs, dynamic Q\&A).
* **Behavior:** Treat the field as instructions for how the agent should respond. Think mini playbook, not a fixed script.
* **Speech settings:** Click the gear icon in the message header to access speech options:
* **Uninterrupted:** Prevents the caller from interrupting. Useful for longer instructions or critical copy.
* **Spell Numbers:** Improves pronunciation of long numbers by reading them digit-by-digit.
* Note: **Verbatim** is not available in Prompt mode by design; prompts stay adaptive.
* **Authoring tips**
* Write in the order: goal -> constraints -> must-say points -> tone. Keep it concise.
* Reference data via [Variables](/agents/variables) such as CRM fields or custom attributes.
* Specify the delivery channel if it matters ("Keep under 160 characters for SMS.").
* End with a clarity cue such as "Keep it short and concise."
* **Pro tip:** Frontier models (GPT-5, Gemini 2.5, and similar) are great at drafting first-pass prompts. Ask for a proposal, then adapt it inside your Prompt speak node.
## Early summaries
End nodes and Transfer nodes can generate a summary before the call ends or transfers. Early summaries are useful when another system or human needs context immediately instead of waiting for normal post-call processing.
When enabled:
* The summary is generated before the final hangup or transfer.
* Downstream systems can retrieve the summary using the call or interview response identifier where supported.
* Warm transfers can include context for the receiving team.
Use early summaries for live handoffs, urgent support workflows, or integrations that need immediate post-call context.
## Transfer node
**What it does:** Hands the caller to a human or another agent.
Transfer nodes offer two modes:
### 1) Phone Router
* Transfers the caller to a specific [Phone number](/phone-number/getting-started).
* Optional pre-transfer **Message** lets the agent speak before the hand-off.
* The transfer occurs immediately after that message (if present).
* Phone numbers are validated in real-time using country-aware formatting rules to prevent transfer failures.
* Optional **Extension** field allows you to specify an extension number for the transfer destination.
Content in the Phone Router **Message** is spoken exactly as written. Proofread it before publishing.
**Phone number validation**
* The system automatically validates phone numbers based on the selected country's formatting rules.
* Validation appears after you enter 7 or more digits.
* Leading and trailing whitespace is automatically trimmed to prevent invisible character issues.
* You can use [Variables](/agents/variables) in the phone number field; validation is bypassed when variables are present.
* Invalid phone numbers will show an error message and prevent the node from being saved until corrected.
Use the country dropdown to ensure your phone number is validated against the correct country's format. The system supports international phone numbers with proper country codes.
**Extension field**
* The **Extension** field supports both static text and dynamic [Variables](/agents/variables).
* Use the bolt icon (⚡) to insert variables such as `{{system.contact.email}}` or custom extracted data.
* Variables appear as styled chips in the field for easy identification.
* Extension values are sent to the destination phone system after the call is connected.
### 2) Agent Transfer
* Connects the caller to another [Agent](/agents/overview) in your account with no extra setup.
* Select the target agent from your list; the current agent session ends when the transfer begins.
* Optional pre-transfer **Description** lets you customize what the agent says before the hand-off (defaults to "Transferring you to \[agent name] now").
* Ideal for warm hand-offs or specialist escalation after identity verification or form capture.
**When to use Transfer**
* Call routing after qualification.
* Escalation to a specialist team.
* Warm hand-offs after identity verification or form capture via [Actions](/agents/actions).
## End node
**What it does:** Closes the conversation gracefully and hands control back to any downstream [Automations](/automations/getting-started).
**Guidelines**
* Keep the goodbye short and courteous.
* Use consistent endings across flows to reinforce brand tone.
* Create multiple **End** nodes to close different branches (success, voicemail, no-match).
Content in the End node's **Message** is spoken exactly as written. Review it for accuracy.
## Quick decision guide
* **Fixed line that must be exact?** -> Use **Start** or Speak > **Message** with **Repeat verbatim**.
* **Adaptive response using data or context?** -> Use Speak > **Prompt**.
* **Need to hand off?** -> Use **Transfer** (Phone Router or Agent Transfer).
* **Conversation finished?** -> Use **End**.
## Common mistakes to avoid
* Putting long scripts in **Start**; keep the opener tight.
* Using **Prompt** when an exact line is required; select **Message** + **Verbatim** instead.
* Forgetting to enable **Uninterrupted** for critical information.
* Skipping pronunciation checks; turn on **Spell Numbers** for IDs, order numbers, or [Phone numbers](/phone-number/getting-started).
* Missing the speech settings icon; click the gear icon in the message header to access all speech options.
## See also
* [Variables](/agents/variables) - personalize messages safely and branch on captured data.
* [Phone Numbers](/phone-number/getting-started) - formatting, country codes, and testing.
* [Agents](/agents/overview) - creating, naming, and organizing agents.
* [Outcomes](/agents/outcomes) - routing logic after Speak nodes.
* [Actions](/agents/actions) - mid-call work, lookups, and best practices.
# Outcomes and conversation branching
Source: https://docs.thoughtly.com/agents/outcomes
Define outcomes that decide where a Thoughtly voice agent routes the conversation after each caller response, enabling dynamic branching and follow-ups.
**Prerequisites**: Complete [Agent Builder Overview](/agents/overview) and [Nodes](/agents/nodes) first.
Outcomes tell your agent **where to go next** after a caller speaks. Clear outcomes mean smooth navigation; think of them as written playbooks that ensure your agent always knows what to do.
Add outcomes from the right panel of a [Speak node](/agents/nodes#speak-node). Open the node, scroll to **Outcomes**, and click **Add outcome**.
There are two outcome types:
1. **Prompt-based outcomes** (AI decides)
2. **Rule-based outcomes** (deterministic checks)
A node can use either prompt-based or rule-based outcomes, not both. Pick the mode that fits the scenario.
### Comparison: Prompt-based vs Rule-based
| Feature | Prompt-based | Rule-based |
| ---------------------- | ----------------------------------- | ------------------------------- |
| **Decision Maker** | AI interprets intent | Exact logical conditions |
| **Best For** | Open-ended replies, varied phrasing | Structured data, yes/no answers |
| **Accuracy** | Flexible interpretation | 100% deterministic |
| **Setup Complexity** | Write clear labels | Define logical rules |
| **Maintenance** | Rename labels to clarify | Reorder rules carefully |
| **Ambiguity Handling** | Interprets closest match | Requires exact match or Else |
| **Use Case** | "Interested or not?" | "Email valid? Budget > \$250k?" |
| **Compliance** | ⚠️ Not recommended | ✅ Required for critical paths |
## Prompt-based outcomes (AI)
**What it does:** After the caller responds, Thoughtly evaluates the reply with AI and selects the best matching outcome.
**When to use:**
* Interpreting open-ended replies (interest level, objections, next-step intent)
* Handling varied phrasing where exact keywords are unpredictable
**How to write great outcomes:**
* **Be distinct.** Avoid overlapping labels such as "Positive" and "Very positive."
* **Be concrete.** Prefer "Wants appointment" over "Positive answer."
* **Be short.** Aim for 12-50 characters or one to two short sentences.
* **Cover common branches.** Skip tiny variations that sound the same.
**Common Mistake**: Using overlapping outcome labels like "Positive" and "Very Positive." The AI may struggle to distinguish them. Instead, use concrete labels: "Wants to book" vs "Interested, needs info."
**Example set:**
* Wants to book now
* Interested, send SMS link
* Not interested
* Busy - call back later
**Testing prompt outcomes:**
1. Draft three to five sample caller replies for each outcome.
2. Run test calls or the simulator and observe which path is chosen.
3. If outcomes collide, rename them to be more specific and retest.
Prompt outcomes pair best with a [Prompt speak node](/agents/nodes#2-prompt-speak-node), where your prompt already frames the agent's intent and tone.
## Rule-based outcomes (deterministic)
**What it does:** After the caller responds (or after an [Action](/agents/actions) runs), the system checks your rules from top to bottom and takes the first match. No AI is involved.
**When to use:**
* Branching based on structured info (yes/no answers, numbers, captured email)
* Navigating after Actions (lookup results, API flags, form validation)
* Enforcing critical logic where ambiguity is risky (compliance, verification, eligibility)
**How it is evaluated:**
* Outcomes are checked **from top to bottom** in the order you arrange them
* The **first matching rule wins** and routes to its connected node
* All subsequent rules are skipped once a match is found
* Always add a final **Else** (default) outcome to catch anything that doesn't match
**Reordering outcomes:** Hover over an outcome to reveal the drag handle icon. Click and drag to reorder outcomes. For rule-based outcomes, edge connections automatically update to reflect the new order.
**Example: Email validation flow**
In the screenshot above, outcomes are evaluated top-to-bottom:
**Outcome A** (checked first)\
Rule: `caller_said_stop == true`\
→ Routes to: **End node** (conversation terminates)
**Outcome B** (checked second, only if A fails)\
Rule: `email_is_valid == true`\
→ Routes to: **Collect address details** (next step in happy path)
**Outcome C** (checked third, acts as Else/Default)\
Rule: Always matches if A and B both failed\
→ Routes to: **Clarify budget** (fallback to gather more info)
**Why order matters:** If you swap A and C, the "Clarify budget" path would always execute first (since Else always matches), and the agent would never check if the caller said stop.
**Common Mistake**: Forgetting the Else/Default outcome in rule-based routing. Always add a fallback to handle unexpected inputs or the agent will get stuck.
**Logic safety checklist:**
* Are rules mutually exclusive where needed?
* Is the most specific rule above the general ones?
* Do you have a final Else/Default outcome?
* Did you test negative and no-input cases?
## Loops (special use case)
You can loop an outcome back to the same node.
* Keep answering questions until the caller is satisfied.
* Re-ask or verify required information such as email or budget.
**Simple Q\&A loop (Prompt + prompt outcomes):**
1. Speak node -> Prompt: "Answer the caller's questions clearly and concisely. If the caller asks a new question, continue; if not, proceed."
2. Add two prompt-based outcomes:
* Caller asked a question -> connect back to this node (self-loop)
* No more questions -> go to the next step
3. Test with varied phrasing to confirm the loop works.
Add a maximum loop count or a fallback branch to avoid infinite loops. For required fields, pair the loop with rule checks (for example `email_is_valid == false`) so the agent retries with a clarifier or offers a [Transfer](/agents/nodes#transfer-node).
## Troubleshooting
**Outcomes not triggering correctly**
* Verify outcome type matches your use case (prompt for open-ended, rules for structured)
* Check that outcome labels are distinct and specific
* Test with varied caller responses using [Test Agent](/agents/testing)
**Agent gets stuck at a node**
* Ensure rule-based outcomes have an Else/Default path
* Verify all conditions are achievable (not logically impossible)
* Check that prompt outcomes have at least 2-3 options
**Wrong outcome chosen (prompt-based)**
* Rename outcomes to be more specific and concrete
* Add more example phrases in your testing
* Consider switching to rule-based if logic is too complex
**Rule order issues**
* Remember: first match wins in rule-based outcomes
* Move specific rules above general ones
* Test all branches with [Test Agent](/agents/testing)
## Common mistakes to avoid
* **Vague labels**: Using "Positive" instead of "Wants to book now" in prompt mode
* **Missing Else**: Forgetting the default fallback in rule-based outcomes creates [dead ends](/resources/glossary#dead-end)
* **Wrong order**: Placing general rules before specific ones causes incorrect matches
* **Compliance risk**: Using prompt outcomes for legal/medical/financial decisions where exactness matters
## See also
* [Speak nodes](/agents/nodes#speak-node) - choose Message vs. Prompt
* [Actions](/agents/actions) - mid-call steps that set flags and values
* [Variables](/agents/variables) - capture data for branching logic
* [Transfer node](/agents/nodes#transfer-node) - escalate to humans or other agents
* [End node](/agents/nodes#end-node) - finish conversations cleanly
* [Testing](/agents/testing) - validate outcome logic with Test Agent
* [Glossary: Happy Path](/resources/glossary#happy-path) - designing the ideal conversation flow
# Agent Builder overview
Source: https://docs.thoughtly.com/agents/overview
Design, test, and launch conversational voice agents with the Thoughtly Agent Builder — a visual node-based editor for prompts, actions, and outcomes.
**Prerequisites**: Complete [Introduction](/getting-started/introduction) and [Quick Start](/getting-started/quick-start) first.
Welcome to the Agent Builder. This is where non-technical teams design, test, and launch [conversational agents](/resources/glossary#voice-agent) that sound natural and get work done.
## What you can build
* Voice agents that open calls, answer questions, qualify leads, book meetings, and transfer to people when needed
* Consistent, brand-safe scripting with adaptive AI where it helps and deterministic rules where it matters most
## How the builder is organized
* **Nodes and their types** - The building blocks of a flow: Start, Speak (Message/Prompt), Transfer, End
* **Outcomes** - Decide where to go next after each turn (AI prompt-based or deterministic rule-based)
* **Variables** - Capture data from the conversation for branching and follow-up
* **Actions** - Run mid-call integrations (lookups, webhooks, schedulers) so the agent can do real work
* **Settings** - Tune voice, language, presence/endpointing, knowledge, and post-call behavior
* **Testing (Test Agent & Call Me)** - Validate logic via text and polish the live voice experience with real calls
## Builder workflow (high level)
1. Sketch the flow with Nodes and their types (Start -> Speak -> Transfer/End).
2. Define navigation using Outcomes (pick prompt-based or rule-based per node).
3. Capture facts with Variables (extracted before outcomes).
4. Add mid-call work with Actions (lookups, booking, CRM updates) and route on results.
5. Tune Settings (voice, language, presence, voicemail handling, advanced prompt).
6. Test with Test Agent (text) -> Call Me (live call), then iterate.
## What to use when
* **Fixed, must-say lines** -> Use Speak > Message and enable *Repeat verbatim*.
* **Composed responses from context/data** -> Use Speak > Prompt.
* **Open-ended interpretation** -> Choose prompt-based outcomes.
* **Compliance or precision** -> Choose rule-based outcomes.
* **Need external data or side effects** -> Add Actions.
* **Branching on captured data** -> Combine Variables with rule checks.
* **Final polish** -> Adjust Settings and run Call Me.
## Build your first agent (10-minute quick start)
1. Create an agent and set Voice/Language under Settings.
2. Add a Start node with a short opener and any required consent.
3. Add a Speak -> Prompt for qualification, and define three to four Outcomes (for example Book now, Call back, Not interested, Clarify).
4. Add Variables (for example email, budget) with clear extraction instructions.
5. Add an Action (CRM lookup or scheduler) and use rule-based outcomes to branch on results.
6. Use Test Agent to verify paths; then Call Me for a real call and tune presence/latency.
7. Add Transfer and End nodes to finish gracefully.
## Troubleshooting
**Agent not responding as expected**
* Test with [Test Agent](/agents/testing) first to debug conversation flow
* Check that outcomes are configured (prompt-based or rule-based)
* Verify variables are extracting data correctly
* Review [Settings](/agents/settings) for voice and language configuration
**Conversation getting stuck at a node**
* Ensure all nodes have outcomes defined (no dead ends)
* Add Else/Default outcome in rule-based routing
* Check that prompt outcomes have at least 2-3 options
* Use [Testing](/agents/testing) to trace execution path
**Actions not executing**
* Verify integration is connected in [Settings](/agents/settings)
* Check action configuration has all required fields
* Test integration separately in [Automations](/automations/getting-started)
* Review action execution order (actions → variables → outcomes)
**Voice quality or timing issues**
* Adjust [presence settings](/agents/settings#presence-tab)
* Try different voices from the [Voice Selector](/agents/voices)
* Test with [Call Me](/agents/testing#call-me-real-call) to hear actual performance
* Review network latency and server region settings
**Common Mistake**: Building complex flows without testing each node. Always use [Test Agent](/agents/testing) to validate conversation logic before adding more nodes. This catches issues early when they're easy to fix.
## Best Practices
* **Actions execute before outcomes** in a node. Order: actions → variables → outcomes. On nodes with actions, outcomes evaluate immediately after the action completes — before the caller speaks again — so use rule-based (not prompt-based) outcomes on action nodes.
* **Prompt outcomes** are great for open conversational turns. Use **rule outcomes** for form validation or compliance checks.
* **Test with Test Agent** (text) first to refine logic cheaply, then **Call Me** (voice) to polish live sound.
* **[Genius](/genius/getting-started) stores information**. Agent instructions or custom prompts shape behavior.
* **Start simple**: Build a basic flow, test it, then add complexity incrementally.
## See also
* [Nodes](/agents/nodes) - build blocks and their types
* [Outcomes](/agents/outcomes) - route the conversation
* [Variables](/agents/variables) - capture and reuse data
* [Actions](/agents/actions) - run integrations and logic mid-call
* [Settings](/agents/settings) - voice, language, presence, advanced customization
* [Testing](/agents/testing) - validate and refine your agent
* [Genius](/genius/getting-started) - adding knowledge to agents
* [Glossary: Voice Agent](/resources/glossary#voice-agent) - understanding voice AI, Call Me, and troubleshooting
# Agent settings
Source: https://docs.thoughtly.com/agents/settings
Tune voice selection, response behavior, transfer rules, and post-call workflows for each Thoughtly agent from a single configuration panel.
Fine-tune stability, voice/LLM behavior, and post-call workflows for each agent.
Open any agent in the Agent Builder. The builder has three tabs: **Create** (the visual flow editor), **Deploy** (deployment configuration), and **Responses** (redirects to [History](/platform/history) filtered for this agent). Settings are available in the sidebar panel within the Create tab.
## Main settings
* **Agent name** - Internal label shown to you and your team.
* **Conversation type** - Lightly optimizes tone and behavior for your use case. *General* works for most flows. Choose a specific type if you have a narrow scenario (qualification, support, collections, etc.).
* **Voice** - Click the Voice field to open the inline **Voice Selector** panel with **Saved** and **Explore** tabs. Browse, preview, and assign voices without leaving the builder. See [Voices](/agents/voices) for full details.
* **Language** - Primary speaking language for the agent (for example English or Ukrainian). Set this explicitly if not English and align with your callers' locale.
## Genius tab
* **Attach Genius database** - Connect one of your existing Genius knowledge bases to enable retrieval-augmented answers.
* **When to use** - Product FAQs, policy answers, common objections.
* **Tips** - Keep entries concise, current, and free of internal jargon.
This tab is for **assigning** an existing knowledge base to your agent. To **create** a new Genius database, go to [Tools → Genius](/genius/getting-started).
## Presence tab
Fine-tune how the agent listens and decides when a caller is finished speaking.
* **Sensitivity threshold to caller** - Controls how easily the agent treats audio as speech.
* Higher value: ignores more background noise, reduces false starts; may miss very quiet voices.
* Lower value: captures softer voices; may pick up room noise.
* **Recommendation:** start mid-range; increase in noisy environments.
* **Silence timeout** - How long to wait after silence before re-engaging (for example "Are you still there?"). Minimum value is 4000ms (4 seconds) to prevent premature re-engagement prompts.
* **Silence retries** - Number of re-engagement attempts before ending the call.
* **Recommendation:** 1-2 for sales, 0-1 for support/IVR flows.
* **Utterance end / endpointing** - Time window that decides when a sentence is considered finished. Larger values give callers more time but add latency;
## Post-call
**Deprecation Notice**: Post-call settings are being phased out in favor of [Automations](/automations/getting-started). We recommend using the **On Call Completed** trigger in Automations for all post-call workflows. This provides more flexibility, better error handling, and integration with your full automation stack.
Legacy post-call settings allow basic automation after each call ends. These run automatically when the call terminates, regardless of outcome.
### Available Options
* **Email notifications** - Automatically send a summary email to all team members after each call completes. The email includes:
* Call duration and outcome
* Transcript of the conversation
* Timestamp and caller information
**Use case**: Quick notifications to sales teams or support managers without building a full automation.
* **Disposition** - Automatically tag calls based on the transcript content and call outcome. The system analyzes the conversation and applies predefined labels like "Qualified lead," "No answer," "Left voicemail," or "Request callback."
**Use case**: Basic call categorization for reporting and filtering in your call history.
### Migration Recommendation
For more powerful post-call workflows, use [Automations](/automations/getting-started) with the **On Call Completed** trigger. This gives you access to:
* Conditional logic based on call outcomes and variables
* CRM updates and data syncing
* Multi-step workflows with error handling
* Integration with webhooks and third-party services
* Advanced notification routing
* Flexible trigger scope (one agent, multiple agents, or All Agents)
## Voicemail
Allow the agent to leave a message when reaching voicemail.
* **Enable voicemail** - When detected, the agent plays your voicemail message and ends the call.
* **Best practices:** keep it under 20-25 seconds, include a call-back request and number/URL, and avoid sensitive information.
## Advanced settings
* **Advanced prompt** - Overarching instruction the agent considers before anything else. Use it to define persona, tone, and high-level guardrails. Do not put navigation logic here; keep routing in Speak nodes and Outcomes.
**Template**
```
You are a helpful, concise sales assistant. Be friendly and confident. Prefer short sentences. If the caller expresses confusion, summarize and ask one clarifying question. Avoid medical or legal advice.
```
**Tips**
* Keep it short (3-6 lines).
* Avoid duplicating instructions already present in node prompts.
* Revisit after a few test calls to tune tone, not logic.
## Setup checklist
1. Name the agent and set Conversation type.
2. Choose Voice, Voice speed, and Language.
3. Attach a Genius database if needed.
4. Tune Presence (sensitivity, silence timeout/retries, endpointing).
5. Configure Post-call notifications and Disposition (or rely on Automations).
6. Enable Voicemail and add a clear message.
7. Add an Advanced prompt for persona; keep routing logic in nodes and outcomes.
## See also
* [Voices](/agents/voices) - browse, preview, and assign voices.
* [Speak nodes](/agents/nodes#speak-node) - author messages and prompts.
* [Outcomes](/agents/outcomes) - routing after each turn.
* [Automations overview](/automations/getting-started) - post-call workflows and reporting.
## Variables in advanced prompts
Advanced prompts can reference variables that are filled at runtime. This lets you adapt agent behavior based on contact attributes, automation payloads, CRM fields, or channel context.
Example:
```text theme={null}
The contact's lead source is {{ contact.lead_source }}. If the source is "referral", thank them for being referred before asking qualification questions.
```
Always test variable-backed prompts with realistic sample data before publishing.
# Test voice agents before launch
Source: https://docs.thoughtly.com/agents/testing
Validate conversation logic, voice quality, and integrations with Thoughtly's in-app test caller and simulated runs before deploying an agent to production.
Validate your flows before going live. These tools save time, catch logic gaps, and ensure the voice experience matches your brand.
## Test Agent (text chat)
**What it does:** Lets you talk to your agent in text. Ideal for fast debugging while building.
**Why it is useful**
* Instant feedback - no dialing required.
* Validate [Outcomes](/agents/outcomes) logic, [Variables](/agents/variables) extraction, and [Actions](/agents/actions) outputs.
* Reproduce edge cases quickly by copying and pasting caller messages.
**How to use**
1. Click **Test Agent**.
2. Send a few representative messages (greeting, objections, qualification answers).
3. Watch for:
* Outcome path taken
* Node step numbers in the conversation flow
* Variables extracted or updated
* Action results and flags
4. Adjust Speak nodes, outcomes, or variables as needed and retest.
**Pro tips**
* Keep a list of 10-15 common caller phrases per branch and run them after each edit.
* Use the self-loop pattern to test Q\&A depth (see [Outcomes -> Loops](/agents/outcomes#loops-special-use-case)).
* If a Prompt feels wordy, shorten it and retest - clarity beats cleverness.
**Limitations**
Text chat does not reveal TTS quality, barge-in timing, or background-noise behavior. Use **Call Me** to test the real call experience.
## Call Me (real call)
**What it does:** Places an actual phone call to you from the agent. Perfect for final checks before talking to customers.
**What to listen for**
* **Voice & style:** Does the selected voice match your brand? Any mispronunciations? Adjust voice/language under [Settings](/agents/settings).
* **Barge-in/interruptions:** Are critical lines protected by *Uninterrupted message*?
* **Endpointing/latency:** Is the agent cutting callers off or waiting too long? Tune sensitivity, utterance end, and silence timeout/retries in Settings -> Presence.
* **Transfer behavior:** Does the [Transfer node](/agents/nodes#transfer-node) hand off cleanly and play the pre-transfer message?
* **Action timing:** Do mid-call actions feel smooth? Add a short "One moment..." line if needed.
**How to use**
1. Click **Call Me** and confirm your phone number.
2. Take the call and run through your top 5-10 scenarios (success, objections, no-answer, transfer).
3. After the call, review the response log for more information about the call. Node step numbers help you identify exactly where the conversation went during replay.
**Checklist for a pass**
* Opener is crisp; consent or disclaimers are verbatim where needed.
* Numbers are easy to understand (enable *Read numbers phonetically* for IDs).
* Interruptions behave as intended (on for long instructions; off for natural conversation).
* Transfers work; voicemails leave the right message.
* Post-call notifications and dispositions land where expected (Settings -> Post-call).
**Troubleshooting**
* Agent talks over you -> lower sensitivity or shorten utterance end (Settings -> Presence).
* Agent waits too long -> reduce utterance end or silence timeout.
* Wrong path chosen -> check outcome labels for overlap (prompt-based) or rule order (rule-based).
* Variables empty or incorrect -> switch source to *Current speak node* for precise asks; tighten extraction instructions.
* Mid-call action confusion -> ensure rule-based outcomes check action flags.
## Workflow recommendation
1. Build the flow skeleton with Speak nodes and Outcomes.
2. Validate logic and extractions with Test Agent (text).
3. Add Actions and retest text.
4. Tune Settings (Presence, Voice/Language).
5. Use Call Me for live feel and final polish.
## See also
* [Speak nodes](/agents/nodes#speak-node) - author prompts and messages.
* [Outcomes](/agents/outcomes) - routing after each turn.
* [Variables](/agents/variables) - capture and reuse information.
* [Actions](/agents/actions) - mid-call integrations and branching.
* [Settings](/agents/settings) - Presence, Voice, Language tuning.
* [Voices](/agents/voices) - browse, preview, and assign voices.
## Testing with sample metadata
Test Agent can use sample metadata so you can verify how an agent behaves with realistic caller or workflow context before placing a real call.
Examples of useful test metadata:
```json theme={null}
{
"first_name": "Jordan",
"lead_source": "website_form",
"appointment_type": "consultation",
"priority": "high"
}
```
Use sample metadata to test personalization, variables, conditional routing, and prompts that depend on CRM or automation data.
## Test chat sessions
Text-based test sessions are isolated from live calls. Use them to quickly inspect prompts, branching, and variable usage. For voice quality, interruption behavior, pronunciation, and transfer timing, place a real test call before going live.
# Voice agent tips and tricks
Source: https://docs.thoughtly.com/agents/tips-and-tricks
Practical patterns and best practices for building reliable, natural-sounding Thoughtly voice agents — covering prompts, actions, voices, and edge cases.
## Introduction
Building an effective Voice Agent requires more than just adding nodes and connecting them. It demands clarity, logical flow, and adherence to structured guidelines. Thoughtly’s no-code Agent Builder simplifies the process, but following best practices will help ensure reliability, scalability, and ease of maintenance.
## General Best Practices
Clear instructions are critical in each node. If a conversation flow is confusing to a human, it will be confusing to AI. Remember, AI does not think smarter than humans—it follows patterns. Avoid spelling errors to prevent misinterpretation, and ensure all text is structured logically.
When crafting prompt instructions, do not use special characters such as `*`, `^`, or `$`. These can interfere with parsing and processing, leading to unintended errors. Implementing a system guardrail for this is highly recommended.
### Rules for Building an Agent
When you build an agent, you must follow these rules:
* No special characters allowed in each node's message/instructions.
* No special characters allowed in outcomes, but `-` and `/` are okay.
* Outcomes need a minimum of 12 characters.
* Node messages can be up to 2000 characters.
* No nodes can be connected to themselves or the one directly above them.
## Structuring Nodes Effectively
A well-structured Voice Agent depends on clear node organization. Ensuring logical flow between nodes prevents confusion and helps AI handle conversations smoothly. Additionally, avoid unnecessary complexity in node construction:
* The start node’s outcome should avoid simulating voicemail detection, as it is unreliable.
* If an outcome is labeled "caller has questions" and leads to another node, do not assume the question has already been answered. The next node’s purpose is to provide an explicit answer.
* Avoid phrases like "ask me anything." Instead, be specific about the topics the agent can answer to prevent hallucination or unexpected behavior.
* Remove all spelling errors. Poorly structured outcomes can be misinterpreted, leading to incorrect logic paths.
Additionally, review the actions used in nodes. If an action only references `{{system.contact.phone_number}}`, there may be no need to extract it again from conversation history. Eliminate redundant actions where possible to streamline performance.
### Start Node
Your Start Node is the gateway to the conversation. It should be simple, clear, and direct. Avoid attempting to simulate voicemail detection, as it is unreliable. Instead, focus on setting the stage for a structured conversation.
### End Nodes
A well-structured conversation needs a clear exit. Multiple end nodes are allowed, but each must include a distinct closing message to ensure a smooth call conclusion. This prevents dead-end interactions and leaves a positive impression on callers.
End nodes must use static, verbatim text and cannot reference dynamic variables. This rule ensures consistency and predictability, eliminating potential errors. Node messages can be up to 2000 characters.
### Transfer Nodes
Multiple transfer nodes can be used to direct calls efficiently. For phone transfers, use clear messages to guide the caller. For agent transfers, specify the agent’s name and purpose clearly. When using multiple transfer nodes, ensure that each has distinct names or messages to avoid confusion.
Like end nodes, transfer nodes must also be static and cannot reference dynamic variables. Implementing this as a system guardrail will prevent potential errors in call routing. Additionally, transfer nodes must have a minimum of 80 characters.
## Optimizing Speak Nodes
Speak nodes should strictly contain speech instructions—nothing else. Do not include navigation rules or conditional logic within these nodes. The AI should focus solely on delivering the intended speech.
Avoid vague prompts such as “ask me anything.” Instead, anticipate the caller’s possible questions and define clear, specific outcomes to guide the conversation effectively.
## Managing Actions and Variables
Variables play a crucial role in customizing responses, but they must be used properly. Ensure that the variable picker includes the node ID for better organization and tracking.
Bracketed variables (e.g., `[variable]`) should be used only within speech instructions. They represent dynamic information the agent may reference based on conversation history. Be cautious with replacements in additional rules to maintain consistency and avoid errors.
## Navigating Outcomes
Each node must lead to a distinct outcome. Avoid creating loops where a node directly links back to its parent. However, looping back to ancestor nodes is permitted when necessary for logical flow.
Ensure that within a given conversation branch, each node has unique instructions all the way up to the start node. If an outcome is meant to address caller questions, do not assume the question has been answered in previous nodes—make sure the next node provides a direct answer.
Additionally, outcomes need a minimum of 12 characters.
## Guidelines for Advanced Rules
Advanced rules should be used sparingly and only when absolutely necessary. Never include navigation instructions in advanced rules. Statements like "do not move forward unless..." should be avoided. Instead, structure your conversation flow using outcomes and well-defined nodes.
Additionally, do not place questions inside advanced rules. Instead, ensure questions are handled within the agent’s node structure for better clarity and response accuracy.
Use advanced rules only when absolutely necessary. They should never contain questions or navigation instructions. Instead of relying on complex logic within rules, structure your conversation flow in a way that naturally guides the user through different paths.
## Best Practices for Genius Data Integration
Genius data sources should always follow a strict Question & Answer (Q\&A) format. Avoid including unnecessary details—concise, well-structured data reduces hallucinations and improves response accuracy.
Review each Genius data source regularly and ensure it aligns with the Q\&A format. The current format in some agents may be confusing the model, leading to incorrect or irrelevant responses. Remove any unnecessary information to enhance accuracy.
Exercise caution with scheduling data and time-sensitive information. Since AI does not have real-time context awareness, incorrect or outdated information can lead to confusion. Regularly review and update Genius data sources to maintain reliability.
## Ensuring Effective Data Extraction
Data extraction nodes must be set up correctly to function as intended. Every data extraction action should have a clearly defined field for extraction. Before deployment, test extraction actions in the output tab using a sample response. If the test returns no output, it indicates an issue that must be fixed before production use.
Ensure that the field being extracted is valid. If an agent is attempting to extract a field that does not exist, such as "Phone Optimization," the action will fail. Test the extraction in the output tab before proceeding to avoid unnecessary errors.
## Final Thoughts
Following these best practices will help you build a robust and effective Thoughtly Voice Agent. By structuring nodes properly, defining distinct outcomes, and ensuring clear speech instructions, you can create a seamless and professional AI-powered voice experience. Keep refining and testing your agent to achieve optimal performance and user satisfaction.
# Troubleshoot Thoughtly voice agents
Source: https://docs.thoughtly.com/agents/troubleshooting
Diagnose and resolve common voice agent issues including audio quality, transfers, action failures, prompt drift, and unexpected hang-ups in Thoughtly.
## Common Issues
### Agent Not Responding as Expected
If your agent isn't responding correctly:
* Review your agent's configuration in [Settings](/agents/settings)
* Check [Outcomes](/agents/outcomes) and [Variables](/agents/variables) setup
* Verify node connections in the agent builder
* Test with simple conversations first using [Test Agent](/agents/testing)
### Call Quality Issues
For call quality problems:
* Check internet connection stability
* Verify phone number configuration in [Phone Numbers](/phone-number/configuration)
* Review the [Settings](/agents/settings) including voice and presence tuning
* Test with different voice options from the [Voice Selector](/agents/voices)
### Agent Not Following Node Flow
If your agent isn't following the intended conversation flow:
* Verify all nodes are properly connected
* Check outcome conditions and logic
* Review the [Nodes](/agents/nodes) documentation
* Test each branch of the conversation separately
### Variable Issues
For variable-related problems:
* Ensure variables are properly defined
* Check variable scope and availability
* Review the [Variables](/agents/variables) guide
* Verify data is being passed correctly
### Special Characters in Call Transcripts
If your agent is pronouncing special characters (asterisks, underscores, brackets, etc.) during calls:
The LLM may be generating speech-like markdown that includes special characters. To resolve this, add the following instructions to your agent's **Advanced Prompt** (not individual speak nodes):
```
You are writing text for TTS; special characters like *, _, #, [, ], (, ), etc. must never appear.
Never output special characters under any circumstance.
If input contains special characters, remove them and rewrite naturally.
If you need to refer to a special character, spell out its name (e.g., "asterisk", "underscore").
```
This ensures the instruction applies to the entire agent and prevents special characters from appearing in the call transcript or being pronounced by the TTS system.
For additional assistance, visit our [Support Center](/support/getting-help).
# Variables in voice agents
Source: https://docs.thoughtly.com/agents/variables
Capture caller data into variables and reuse it across nodes for branching, action payloads, dynamic prompts, and post-call follow-up in Thoughtly.
**Prerequisites**: Review [Speak Nodes](/agents/nodes#speak-node) and [Outcomes](/agents/outcomes) first.
Variables let your agent **capture information from the conversation** for use later: within the same call (branching with [Outcomes](/agents/outcomes), deciding [Actions](/agents/actions)) and after the call (CRM updates, notes, automations).
**When they extract:** Immediately after the caller's latest reply and **before** outcome evaluation. That means your outcomes can reference fresh variable values right away.
Add variables from the right panel of a [Speak node](/agents/nodes#speak-node). Open the node, scroll to **Variables**, and click **Add variable**.
## Visual type indicators
Variables display with type-specific icons throughout the Agent Builder to help you quickly identify their format:
* **Text variables** show a text icon
* **Number variables** show a grid icon
* **Boolean variables** show a customize icon
These icons appear in:
* The variable picker dropdown when inserting variables into messages
* Variable chips within the message editor
* The variables list in speak nodes
* Canvas node previews
* Outcome rules that reference variables
This visual system makes it easier to track variable types at a glance and ensures you're using the correct format in your logic.
## Fields
* **Name** - A short, readable identifier you will reference in rules and prompts (for example `budget`, `email`, `callback_time`).
* **Source** - Choose **Current speak node** or **Conversation history**.
* *Current speak node* extracts only from the caller's most recent turn, ignoring earlier context. Great for precise questions such as "What is your email?" when you only want the latest answer.
* *Conversation history* searches the entire conversation for the best value. Useful when the caller may have mentioned it earlier or you want a fallback.
* **Extraction instructions** - This is the heart of the variable. Write exactly what to extract and how to transform it. Be explicit about constraints, examples, and edge cases.
**Template you can copy**
```text theme={null}
Goal: Extract the the caller states.
If multiple candidates: choose the most recent, high-confidence value.
If absent or unclear: return an empty value (no placeholder text).
Normalization: .
Do not invent values.
```
* **Format** - Enforces the output type so downstream logic stays predictable. Each type displays with a unique icon throughout the Agent Builder for easy identification.
* **Text** - Text values (names, emails, addresses). Displays with a text icon.
* **Number** - Numeric only (budgets, credit scores). The system requires a valid number. Displays with a grid icon.
* **Boolean** - True/false values (consent, qualification). Displays with a customize icon.
## Authoring examples
Name: `budget` Source: Current speak node Extraction instructions: Extract the maximum home budget the caller states as a plain number in USD, with no commas or text. If a range is given (for example "200 to 250k"), choose the upper bound. If not provided, leave empty. Format: Number Use with: Rule outcome `budget >= 250000` -> High-intent path.
Name: `email` Source: Conversation history Extraction instructions: Extract the caller's email. Normalize to lowercase and remove spaces. If multiple addresses are present, choose the most recent. If none, leave empty. Format: Text Use with: Rule outcome `email` matches `/.+@.+\\..+/` -> Collect address details.
Name: `callback_ok` Source: Current speak node Extraction instructions: Determine whether the caller has explicitly agreed to a call-back. Return `true` for clear consent like "Yes, call me later," otherwise return `false`. Format: Boolean Use with: If `callback_ok == true` -> trigger [Actions](/agents/actions) to create a follow-up task.
## Re-extraction and overrides
* Each time the agent visits a node that defines a variable, it retries extraction and overwrites the previous value if it finds a better one.
* You can intentionally redefine variables later to refine accuracy (for example, asking the caller to confirm their email).
* Prefer *Current speak node* for confirmations to avoid pulling older mentions from the conversation history.
## System variables
Thoughtly provides built-in system variables that you can reference in your agent without defining them explicitly:
* **`{{system.interviewResponse.id}}`** - The unique call ID for the current conversation. Use this to reference the specific call in mid-call actions, webhooks, or external systems.
**Example use case:** Pass the call ID to a webhook during the call so your external system can track which conversation triggered the action.
```text theme={null}
Webhook URL: https://api.example.com/call-events?call_id={{system.interviewResponse.id}}
```
## Referencing node responses
You can reference data captured at specific nodes using the node step number. When a node extracts information or receives a response, you can access it later in the conversation using the format `Node #[step]: Answer` or `Node #[step]: [field_name]`.
**Example:** If node step 3 asks for the caller's email and node step 5 performs an API lookup, you can reference the email response as `Node #3: Answer` in your API action configuration or in subsequent speak node prompts.
Node step numbers are automatically assigned sequentially (Start = 0, then 1, 2, 3, etc.) and remain consistent throughout the conversation, making it easy to reference earlier responses even as you modify your agent flow.
## AI-Generated Variables
Many times, you'll want to create a variable that is generated by an AI model. For example, you might want to create a variable that contains the caller's email address, or keywords that were mentioned based on the call [transcript](/resources/glossary#transcript).
## Validation patterns (pair with Outcomes)
Use rule checks to keep data clean:
* **Required:** If `email` is empty -> loop back to re-ask (self-loop pattern; see [Outcomes](/agents/outcomes#loops-special-use-case)).
* **Ranges:** `credit_score` between 300 and 850; `budget >= 250000`.
* **Flags from Actions:** for example `crm_lookup_found == true`.
## Troubleshooting
**Variable extracting incorrect data**
* Make extraction instructions more specific and concrete
* Switch from Conversation history to Current speak node for precision
* Add examples of correct format in extraction instructions
* Test with [Test Agent](/agents/testing) to verify extraction
**Variable always empty**
* Verify caller is actually providing the information
* Check if variable source is set correctly (current vs history)
* Ensure extraction instructions aren't too restrictive
* Review [test call recordings](/agents/testing#call-me-real-call) for what was said
**Wrong format being extracted**
* Confirm Format field matches expected type (Text/Number/Boolean)
* Add explicit format requirements to extraction instructions
* Use validation rules in [Outcomes](/agents/outcomes) to catch errors
**Variables conflicting with actions**
* On nodes with actions, the order is: actions run → variables update from action results → outcomes evaluate (see [Actions](/agents/actions) for execution order)
* Variables do update from action results on the same node, so you can branch on action output without a separate node
* Use a separate node only if you need the caller to speak again before the next action or outcome
**Common Mistake**: Using vague extraction instructions like "Get their contact info." Be specific: "Extract phone number in format +1-555-555-5555 from caller's response. If not provided, leave empty."
## Best practices
* **Order of operations:** Variables extract before outcomes, so branching logic always sees the latest values.
* **Be explicit:** The more concrete your instructions, the higher the accuracy. Avoid vague wording.
* **Handle empty values:** Plan what happens if the variable is missing (default branch, re-ask loop).
* **Name consistently:** Use lowercase snake\_case (for example `credit_score`, `callback_time`) so rules stay readable.
* **PII caution:** Only capture the [personally identifiable information](/resources/glossary#pii) you actually need.
## See also
* [Outcomes](/agents/outcomes) - branch using the variables you extract
* [Speak nodes](/agents/nodes#speak-node) - where variables live and update
* [Actions](/agents/actions) - set or update variables via lookups and APIs
* [Transfer node](/agents/nodes#transfer-node) - escalate when validation fails repeatedly
* [Testing](/agents/testing) - validate variable extraction with Test Agent
* [Glossary: PII](/resources/glossary#pii) - handling sensitive data responsibly
## Channel type variable
When building omnichannel workflows, use the channel type to adjust agent behavior by medium. For example, an agent can write shorter copy for SMS, longer copy for email, and spoken phrasing for voice.
Example use cases:
* Route email conversations to a different branch than voice calls.
* Keep SMS replies under a target length.
* Avoid voice-specific phrases in email or WhatsApp.
* Track outcomes by channel in analytics.
## Variables in more fields
Variables can now be used in more builder fields, including prompts, extraction instructions, number fields, date fields, and selected integration inputs where supported. Use the data picker when available to avoid typos.
# Vibes AI assistant
Source: https://docs.thoughtly.com/agents/vibes-assistant
Build and refine Thoughtly voice agents conversationally with Vibes, an AI assistant that drafts prompts, nodes, and outcomes from plain-language instructions.
Vibes helps you create and edit Thoughtly agents through natural conversation. Instead of starting with a blank canvas, describe the workflow you want and Vibes can draft nodes, outcomes, prompts, and actions for you.
Use Vibes as a guided builder, not a replacement for review. After Vibes creates or edits an agent, inspect the flow, required fields, integrations, variables, and compliance copy before publishing.
## What Vibes can help with
Vibes can assist with:
* Building a new agent from a plain-language description
* Updating an existing flow
* Adding or editing nodes and outcomes
* Drafting prompts and messages
* Configuring agent settings
* Explaining how a workflow is structured
* Iterating on a flow after testing
## When Vibes asks questions
If your request is too broad, Vibes may ask clarifying questions before building. This avoids creating a generic agent that misses important business logic.
Vibes may ask about:
1. **Business type** — the industry or use case
2. **Agent objective** — what the agent should accomplish
3. **Information to collect** — name, email, budget, appointment type, objections, or other fields
4. **Integrations** — CRM, calendar, SMS, webhook, email, or other systems
5. **Routing and success criteria** — when to transfer, end, follow up, or mark the conversation successful
## Good prompts
Good Vibes prompts are specific about the desired outcome.
```text theme={null}
Build a lead qualification agent for a home-services company. It should greet inbound callers, ask what service they need, collect address and timing, qualify urgency, and transfer emergencies to our dispatch line. For non-emergencies, create a callback task and send an SMS confirmation.
```
```text theme={null}
Create an SMS follow-up agent for missed calls. If the contact replies, ask whether they still need help, collect the best callback time, and update the contact with the requested service.
```
```text theme={null}
Update this agent so that when the caller asks for pricing, it gives a short answer, collects their email, and sends a follow-up through the Send Email action.
```
## Vague prompts
Vague prompts usually need follow-up before Vibes can build well.
```text theme={null}
Build me a scheduling agent.
```
Better:
```text theme={null}
Build a scheduling agent for a dental office. It should ask whether the patient is new or returning, collect preferred days, check Calendly availability, book the selected slot, and send an SMS confirmation.
```
## Review checklist
Before publishing a Vibes-generated flow:
* Confirm the agent goal and success criteria are correct.
* Read every message and prompt in the expected channel context.
* Check that variables reference the right fields.
* Confirm required integrations are connected.
* Verify transfer numbers, scheduling links, and webhook URLs.
* Test with realistic metadata in [Test Agent](/agents/testing).
* Make sure compliance language, opt-out handling, and suppression rules fit your workflow.
Vibes can accelerate setup, but generated flows should still be reviewed and tested before production use.
## Troubleshooting
### Vibes built the wrong thing
Ask Vibes to modify the specific part that is wrong, or edit the flow manually. For best results, name the node, action, or outcome you want changed.
### Vibes skipped questions
If you want a more guided setup, start with a shorter request and answer the clarification questions. If you already provided enough details, Vibes may proceed directly to building.
### You navigated away during setup
If Vibes was asking questions and you left the Agent Builder, return to the same agent. Your pending question card should reappear. If it does not, refresh the page.
# Bring Your Own Key (BYOK) for voices
Source: https://docs.thoughtly.com/agents/voice-byok
Connect your own ElevenLabs, Cartesia, or other voice provider API keys to Thoughtly to use your personal voices, usage limits, and provider pricing.
## What is BYOK?
**Bring Your Own Key (BYOK)** lets you connect your own voice provider API key to Thoughtly. Instead of using shared platform credentials, your agents use your provider account directly. This gives you:
Rate limits and quotas come from your provider plan, so you are never constrained by shared platform limits.
Volume discounts or custom pricing you have arranged with your provider apply automatically.
[Clone custom voices](/agents/voice-cloning) stored directly in your provider account for full ownership and portability.
Your private, cloned, and generated voices appear alongside the full public catalog.
## ElevenLabs
### Connect your key
A paid ElevenLabs plan (**Starter** or above) is required. Free ElevenLabs API keys cannot be connected because the validation step rejects them. You can find your API key in your [ElevenLabs dashboard](https://elevenlabs.io) under **Profile + API key**.
Go to **[Settings > Integrations](https://app.thoughtly.com/integrations)** in the Thoughtly dashboard. Look for the **ElevenLabs** card.
Click **Connect** on the ElevenLabs card and paste your API key. Thoughtly validates the key against your ElevenLabs account before proceeding.
Once validated, Thoughtly automatically imports your **cloned** and **generated** voices from ElevenLabs into your workspace voice library. These voices appear in the **Saved** tab tagged with **Your ElevenLabs**.
After connecting, the ElevenLabs card on the Integrations page shows **Connected**.
### Review your subscription
Once connected, you can view your ElevenLabs subscription details directly in Thoughtly. The subscription screen shows:
* **Plan tier** and billing period
* **Character usage**: how many characters you have used out of your monthly quota, and when it resets
* **Voice slots**: how many custom voice slots you have used and how many are available
* **Features**: which capabilities your plan includes, such as Instant Voice Cloning and Professional Voice Cloning
Use this screen to monitor your usage and confirm your plan supports the features you need.
### What changes after connecting
Once your ElevenLabs key is active:
* A **Your ElevenLabs** badge appears in the Voice Selector header, confirming BYOK is active.
* The **Saved** tab shows only voices linked to your ElevenLabs account. Built-in default voices (like Tessa, James, Lisa) are hidden.
* The **Explore** tab shows the full voice catalog. When you save or assign a voice, it is linked to your credentials automatically.
* [Voice cloning](/agents/voice-cloning) creates clones in your ElevenLabs account rather than using Thoughtly's shared account.
* **Cartesia voices** remain available regardless of BYOK status.
If the Saved tab is empty after connecting, your ElevenLabs account may not have any cloned or generated voices yet. Use the **Explore** tab to save voices, or [clone a new voice](/agents/voice-cloning).
### Concurrency
Your ElevenLabs plan determines how many simultaneous voice requests your agents can make. If your agents exceed this limit, calls may experience delays or fall back to a default voice.
| Plan | Concurrent requests |
| -------- | ------------------- |
| Starter | 3 |
| Creator | 5 |
| Pro | 10 |
| Scale | 15 |
| Business | 15 |
Concurrency is managed entirely by ElevenLabs based on your plan. If you need higher limits, upgrade your ElevenLabs plan or contact ElevenLabs about enterprise options.
### Managing your key
Your ElevenLabs API key is managed on the **[Integrations](https://app.thoughtly.com/integrations)** page.
**Rotating your key**: disconnect the current key and reconnect with the new one. Thoughtly re-imports your voices automatically on reconnect.
**Disconnecting**: go to **Settings > Integrations** and remove the ElevenLabs connection.
Disconnecting removes all BYOK-linked voices from your workspace library. Agents that were using those voices fall back to the default voice. Cartesia voices are not affected.
A small number of enterprise workspaces operate without BYOK and instead use Thoughtly-managed voice credentials. If your Saved tab shows built-in default voices rather than your own ElevenLabs library, contact your account manager for setup assistance.
## Workspace-Level Library
Saved voices belong to the **workspace**, not individual users:
* All team members can access saved voices across their agents
* Voice selections persist across sessions
* No per-user sharing limitations
## Premium Voices
Some voices consume more [Credits](/platform/billing) per minute. These are badged with a multiplier like **2x cost** or **3x cost** in both the Saved and Explore tabs. Use premium voices for high-value interactions and standard voices for volume.
## Troubleshooting
* BYOK is rolled out gradually. If you don't see the card for your provider, contact your account manager to enable it for your workspace.
* Verify the key is copied correctly with no extra spaces.
* Confirm the key is active in your provider's dashboard.
* Check that your subscription with the provider has not expired.
* Only **cloned** and **generated** voices are imported automatically. Standard library voices must be saved manually from the **Explore** tab.
* If you recently created voices in your provider account, disconnect and reconnect to re-import.
* **Did you save it?** In the Explore tab, click the **Bookmark** icon or click the voice row to save + assign. Just pressing Play does not save.
* **Check your key**: Your Saved tab shows voices linked to your [BYOK](#what-is-byok) credentials. Confirm your API key is active on the **Integrations** page.
* **Refresh**: Close and reopen the Voice Selector panel, or refresh the Agent Builder page.
* **Vendor removal**: The voice may have been removed by Cartesia or ElevenLabs.
* Previews use sample text; real calls use your agent prompts, which may sound different.
* Tune [Presence settings](/agents/settings#presence-tab) (sensitivity, endpointing) to optimize real-call behavior.
* Always test with [Call Me](/agents/testing#call-me-real-call) before deploying.
* Check your internet connection. The voice catalog may be temporarily unreachable.
* Try refreshing the Agent Builder page.
* If the problem persists, check the [Platform Status](https://status.thoughtly.com) page.
* Add phonetic spellings to your agent prompts (e.g. "Thoughtly" → "Thought-lee").
* Create pronunciation entries in your [Genius](/genius/getting-started) knowledge base.
* Consider [Voice Cloning](/agents/voice-cloning) for specialized terminology.
* Rewrite prompts conversationally. Use contractions, short sentences, and natural phrasing.
* Add punctuation for pacing: commas for short pauses, periods for longer breaks.
* Try a different voice from the Explore tab.
* Confirm the agent's **Language** setting matches the voice's language.
* Use the **Language** filter chip in the Explore tab to find voices in the correct locale.
* See [Voice Optimization](/agents/voice-optimization#choosing-the-right-voice) for accent-matching strategies.
### Still stuck?
If none of the above resolves your issue:
1. Note your **Team ID** (found in workspace settings)
2. Describe the exact steps you took and what you expected to happen
3. [Contact support](/support/getting-help) with this information
## Test your ElevenLabs connection
After adding an ElevenLabs API key, use **Test Connection** to confirm that Thoughtly can access your account and voices. If the test fails, verify that the key is active and has access to the voices you expect to use.
## Legacy voice behavior
Some older workspaces may have legacy voice configurations. If a legacy voice no longer appears in the selector, choose an available Cartesia voice or connect your own ElevenLabs key to use custom ElevenLabs voices.
# Voice cloning for agents
Source: https://docs.thoughtly.com/agents/voice-cloning
Create custom voice clones for Thoughtly agents by recording or uploading audio samples directly inside the Agent Builder, with quality and consent tips.
Create custom voice clones to give your agents a unique, brand-specific sound that isn't available in the public voice library. The **Clone Voice** modal is accessible directly from the **Saved** tab in the Agent Builder's Voice Selector.
## Requirements
| Requirement | Detail |
| ----------------------- | ------------------------------------------------------------------------------------------ |
| **Recording length** | Up to 20 seconds (stops automatically at 20 s). Record the full duration for best results. |
| **Upload length** | No length limit for uploads. Longer samples can improve quality. |
| **Input method** | Browser microphone recording **or** audio file upload |
| **Supported formats** | Any browser-compatible audio format (WAV, MP3, etc.) |
| **Browser permissions** | Microphone access must be granted for recording |
If your workspace uses [BYOK](/agents/voice-byok), cloned voices are created in your own provider account and tagged accordingly in the Saved tab (for example, **Your ElevenLabs**). This gives you full ownership and portability of your cloned voices.
## Cloning Step-by-Step
Open your agent → click the **Voice** field → in the **Saved** tab, click the **Clone a voice** banner at the top. The Clone Voice modal opens.
The Clone banner is hidden while the Saved tab search filter is active. Clear the filter text to see it again.
Enter a descriptive **Voice Name** (e.g. "Sarah, Sales US"). This is how the voice appears in your Saved tab.
Select the **Language** and **Gender** for the voice. These metadata fields help you filter and organize voices later.
Supported cloning languages: English, Spanish, French, German, Portuguese, Italian, Japanese, Korean, Chinese, Hindi, Dutch, Polish, Russian, Swedish, and Turkish.
Gender options: **Male**, **Female**, or **Not specified** (default).
**Option A, Record**: Click **Record Voice**. Speak naturally while the progress bar fills. Recording stops automatically at **20 seconds**, or click **Stop Recording** to end early. For best results, record the full 20 seconds.
**Option B, Upload**: Click **Upload Audio File** beneath the record button and select an audio file from your device.
After recording or uploading, an audio player lets you review the sample. Click **Discard Recording** to start over.
Click **Clone**. Processing typically takes 30 to 60 seconds. When complete, the modal switches to a results screen showing the voice name and a preview player.
Click **Done** to close the modal. Your new voice now appears in the **Saved** tab, ready to be assigned to any agent.
## Recording Best Practices
* **Quiet environment**: minimize background noise and echo
* **Quality microphone**: external mics give better results than built-in laptop mics
* **Consistent volume**: maintain a steady speaking level
* **Clear articulation**: speak naturally but avoid mumbling
* **Conversational style**: record in the tone you want agents to use
* **Complete sentences**: include full thoughts with natural pauses
* **Varied intonation**: demonstrate slight pitch and pacing variation
* **Full 20 seconds**: record the maximum duration for best results. For uploads, longer samples generally produce better clones.
* Grant microphone permissions when prompted by the browser
* Use Chrome or Edge for best recording compatibility
* Maintain a stable internet connection during upload and processing
## Managing Cloned Voices
After cloning, the voice is immediately available in the **Saved** tab of the Voice Selector alongside other saved voices and built-in defaults. You can:
* **Preview** it like any other voice (Play / Pause)
* **Assign** it to agents by clicking the voice row
* **Remove** it with the Bookmark icon or delete it from the results screen
### Workspace-Level Access
Cloned voices are scoped to your **workspace**:
* **Private**: not shared with other Thoughtly workspaces
* **Team-wide**: all workspace members can use cloned voices
* **Persistent**: voices remain until manually deleted
### Multi-Agent Usage
A single cloned voice can be assigned to **unlimited agents** simultaneously with no call-volume restrictions.
## Removing or Deleting a Cloned Voice
There are two ways to remove a cloned voice:
* **Delete** (permanent): On the results screen immediately after cloning, click **Delete**. This permanently destroys the voice.
* **Unsave** (remove from library): In the Saved tab, click the **filled Bookmark** icon on the cloned voice row. This removes it from your workspace's saved library.
Deleting or unsaving a cloned voice that is currently assigned to agents will cause those agents to fall back to the default voice.
## Legal and Ethical Considerations
**Consent is required.** Only clone voices from individuals who have explicitly authorized their voice to be used for AI synthesis in a business context.
* **Document consent**: keep written records of voice-use permissions
* **Professional use only**: limit usage to appropriate business contexts
* **Brand alignment**: ensure the voice represents your brand appropriately
## Data Storage and Privacy
* Raw audio is used for clone generation and stored securely within your workspace
* Cloned voice models are isolated per workspace. There is no cross-workspace access.
* Refer to Thoughtly's data retention policies for storage duration details
## Troubleshooting
* Check browser microphone permissions (Settings → Privacy → Microphone)
* Verify your microphone works in other apps
* Try a different browser (Chrome recommended)
* Re-record the **full 20 seconds** of clear, varied speech in a quiet room, or upload a longer audio file
* Use an external microphone if possible
* If uploading a file, ensure it's not heavily compressed or low-bitrate
* Allow up to 2 minutes for complex samples
* Check your network connection. The upload may have stalled
* Contact [support](/support/getting-help) with your Team ID if processing exceeds 5 minutes
* Confirm you reached the **results screen** (voice name + preview player shown)
* Close and reopen the Voice Selector panel
* Refresh the Agent Builder page
### Still stuck?
If none of the above resolves your issue:
1. Note your **Team ID** (found in workspace settings)
2. Describe the exact steps you took and what you expected to happen
3. [Contact support](/support/getting-help) with this information
## See Also
* [Agent Voices](/agents/voices): browse, preview, and assign voices
* [Agent Settings](/agents/settings): full agent configuration reference
* [Platform Billing](/platform/billing): understanding credit usage
# Voice optimization for natural speech
Source: https://docs.thoughtly.com/agents/voice-optimization
Improve agent voice quality in Thoughtly with accents, language selection, speaking-speed controls, and pronunciation overrides for tricky words and names.
## Match Accent to Market
Pick a voice accent that matches your caller's region. This improves trust and comprehension.
| Market | Recommended accent |
| ----------------- | -------------------- |
| **North America** | US English |
| **Europe** | UK English |
| **ANZ** | Australian English |
| **Mexico** | Mexican Spanish |
| **Spain** | Castilian Spanish |
| **Argentina** | Argentine Spanish |
| **Brazil** | Brazilian Portuguese |
| **Portugal** | European Portuguese |
Test with native speakers in your target market before going live.
## Language
Each agent has a **Language** dropdown in the conversation settings sidebar. Pick the language, then assign a voice in that same language. Mismatched voice/language pairs cause noticeable pronunciation problems.
Thoughtly supports 35 languages. If you need a language that is not listed in the dropdown, [contact support](/support/getting-help).
To serve callers in multiple languages, create a separate agent per language with matching voice and [Genius](/genius/getting-started) knowledge base.
## Speed (Cartesia)
Cartesia voices have a **Voice Speed** slider in the **Presence** section of the Agent Builder sidebar. The slider runs from 0 (slowest) to 100 (fastest), with 50 as the default. Small adjustments of 10 points are noticeable. The slider is disabled when a non-Cartesia voice is active.
## Volume (Coming Soon)
A volume slider for Cartesia voices is in development and will appear alongside the speed control in Presence settings.
## Pronunciation Fixes
If your agent mispronounces names, brands, or industry terms:
1. **Phonetic spelling in prompts**: write "Thought-lee" instead of "Thoughtly"
2. **Genius pronunciation guide**: add entries to your [Genius](/genius/getting-started) knowledge base with the correct spoken form
3. **Voice cloning**: [clone a voice](/agents/voice-cloning) that naturally handles your domain vocabulary
# Agent voices
Source: https://docs.thoughtly.com/agents/voices
Browse the Thoughtly voice library, preview samples, and assign a voice to your agent directly inside the Agent Builder across multiple languages and styles.
Voice selection in Thoughtly happens **inside the Agent Builder**. When you open an agent and click the **Voice** field in the right-hand sidebar, the Voice Selector panel opens with two tabs: **Saved** (shown by default) and **Explore**. This gives you everything you need to browse, preview, save, and assign voices without leaving the builder.
## Voice Platforms
Voices are sourced from two industry-leading providers:
Ultra-low-latency voice synthesis with expressive, professional voices. Features real-time generation, speed control, and advanced audio capabilities.
Natural-sounding voices with a wide selection of accents, styles, and personalities. A trusted choice for conversational AI.
### Saved Tab
Your personal voice library. Voices you have previously saved appear here, **grouped by language**. The active voice's language group is pinned to the top, and the active voice itself is highlighted within it.
Most workspaces connect their own voice provider account to access voices. See [Bring Your Own Key (BYOK)](/agents/voice-byok) for details on connecting your API key. A small number of enterprise workspaces use Thoughtly's built-in voice set instead and see 13 default English voices labeled **Built-in**.
| Element | What it does |
| --------------------- | ---------------------------------------------------------------------------------------------------- |
| **Voice row** | Shows avatar, name, platform, gender, and cost multiplier |
| **Play / Pause** | Instantly preview the voice audio |
| **Bookmark (filled)** | Remove the voice from your Saved library |
| **Clone a voice** | Opens the [Clone Voice](/agents/voice-cloning) modal (record or upload) |
| **Filter** | Click the search icon in the header to filter saved voices by name, language, accent, or description |
### Explore Tab
The **Explore** tab inside the Agent Builder's Voice Selector gives you access to thousands of professional voices from **Cartesia** and **ElevenLabs**. The **Expressive** toggle is enabled by default, prioritizing low-latency, expressive voices. Toggle it off to browse the full catalog across both platforms. You can search, filter, preview, and save, all without leaving the agent you're editing.
#### Filter Chips
| Filter | Behavior |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Expressive** | Enabled by default. Prioritizes low-latency, expressive voices optimized for real-time conversations. Toggle off to browse the full catalog across all platforms. |
| **Gender** | Select **Male** or **Female** to narrow results. |
| **Language** | Choose from 15 languages (with flag icons): English, Spanish, French, German, Portuguese, Italian, Japanese, Korean, Chinese, Hindi, Arabic, Polish, Dutch, Russian, Turkish. |
Filters can be combined. For example, enable **Expressive** + **Female** + **Spanish** to find low-latency female voices in Spanish.
#### Text Search
Click the **search icon** (🔍) in the panel header to open a search bar. Type a voice name or keyword and results update automatically as you type.
When no results match, a **Clear filters** link appears. Clicking it resets the Gender filter, Language filter, and search text. The **Expressive** toggle is separate and must be toggled off manually if you want to broaden results further.
#### Previewing Voices
Every voice row shows a **Play** button on hover. Click it to hear a sample. Click again (or click **Pause**) to stop. Only one preview plays at a time. Starting a new preview automatically stops the previous one.
#### Saving and Assigning a Voice
There are two ways to use a voice from Explore:
**Click to Save + Assign (Recommended)**
Click anywhere on a voice row. Thoughtly will:
1. **Save** the voice to your workspace library (if not already saved)
2. **Assign** it to the current agent
3. **Close** the Voice Selector and return you to the agent sidebar
This is the fastest path. One click does everything.
**Bookmark for Later**
If you want to save a voice **without** assigning it right now, click the **Bookmark** icon on hover. The voice appears in your **Saved** tab for future use across any agent.
To remove a bookmarked voice, click the **filled Bookmark** icon to unsave it from your library.
Voice availability depends on the vendor and can occasionally change. If a voice you rely on becomes unavailable, [contact our support team](/support/getting-help) and we will help you find a replacement.
#### Pagination
Results load 50 voices at a time. If more are available, a **Load more voices** button appears at the bottom. Click it to fetch the next page. Loading state is shown while fetching.
## Voice library behavior
The voice selector loads voices in pages. If more voices are available, use **Load more voices** to continue browsing. Voices should appear only once even when loading additional pages.
## ElevenLabs and Cartesia availability
Workspace voice availability can depend on your plan and whether Bring Your Own Key is enabled. If your workspace uses ElevenLabs BYOK, connect and test your ElevenLabs key before expecting ElevenLabs voices to appear in the selector.
# Get agents
Source: https://docs.thoughtly.com/api-reference/agent/get-agents
get /interview
This endpoint retrieves a list of **Agents** (formerly **Interviews**) available in your system. You can filter the list by status, search term, and sorting options.
# Search calls
Source: https://docs.thoughtly.com/api-reference/agent/search-calls
get /interview/{interview_id}/responses
Find calls made by an **Agent** (formerly **Interview**). You can filter and search calls based on various criteria.
# Call a contact
Source: https://docs.thoughtly.com/api-reference/contact/call-a-contact
post /contact/call
This endpoint allows you to initiate a call with a **Contact** using a specific **Agent**. The **Agent** will handle the conversation during the call.
# Create contact
Source: https://docs.thoughtly.com/api-reference/contact/create-contact
post /contact/create
This endpoint allows you to create a new **Contact**. A contact represents a person with whom you can interact via a phone call or other communication.
# Delete contact
Source: https://docs.thoughtly.com/api-reference/contact/delete-contact
delete /contact/{id}
This endpoint allows you to delete a **Contact** by ID. Deleting a contact will remove it from the system permanently.
# Get contact
Source: https://docs.thoughtly.com/api-reference/contact/get-contact
get /contact/{id}
Retrieve a single **Contact** by their unique ID. Returns the full contact record including name, phone number, email, tags, and any custom attributes associated with the contact.
# Get contacts
Source: https://docs.thoughtly.com/api-reference/contact/get-contacts
get /contact
This endpoint retrieves a list of **Contacts**. You can filter contacts by various criteria, such as tags, phone numbers, and more. Use the query parameters to narrow down your results.
# Update contact
Source: https://docs.thoughtly.com/api-reference/contact/update-contact
post /contact/{id}/update_info
Update an existing contact's name, phone number, email, tags, or custom attributes by ID using the Thoughtly contact update endpoint.
# Get user details
Source: https://docs.thoughtly.com/api-reference/user/get-user-details
get /user
Retrieve the details of the currently authenticated user. This includes information such as user ID, name, and email.
# Get currently active webhooks
Source: https://docs.thoughtly.com/api-reference/webhooks/get-currently-active-webhooks
get /webhooks
Retrieve a list of all active webhooks for the authenticated user. This allows you to see which webhook events you are currently subscribed to.
# Subscribe to webhook
Source: https://docs.thoughtly.com/api-reference/webhooks/subscribe-to-webhook
post /webhooks/subscribe
This endpoint allows you to subscribe to a specific webhook event (e.g., new call responses or phone transfers). You must provide the event type and a callback URL.
# Trigger automation with webhook
Source: https://docs.thoughtly.com/api-reference/webhooks/trigger-automation-with-webhook
post /webhook/automation/{automation_id}
This endpoint triggers an [Automation](/automations/getting-started) with a [Webhook](/automations/triggers#webhook) as the trigger.
# Unsubscribe from webhook
Source: https://docs.thoughtly.com/api-reference/webhooks/unsubscribe-from-webhook
delete /webhooks/unsubscribe
This endpoint allows you to unsubscribe from a previously subscribed webhook event. Provide the event type and the callback URL to unsubscribe.
# Automation actions and steps
Source: https://docs.thoughtly.com/automations/actions
Compose Thoughtly automations from steps for branching logic, outbound calls, scheduling, CRM updates, and integrations triggered before or after a call.
After you choose a ***Trigger***, **Steps** are where your automation does the work: branching, looping, calling people, writing to CRMs, scheduling, sending webhooks, and more.
Open an automation and add a **Step**.
## 1) Step anatomy and data mapping
Most steps share these tabs (similar to triggers).
Account / Configure
Output
Next step
Connect the account (if required) and configure step-specific options.
* **Account / Configure** - Connect the account (if required) and set step-specific options.
* **Output** - Preview the **result schema** this step produces (or expects). Click **Refresh** after a **Draft** run to update it.
* **Next step** - Choose the next node in the flow.
**Referencing earlier data**
* Click the lightning icon to open the data tree.
* Pick the **Trigger** or any previous **Step** as the source, then click fields to insert them.
* Click the **+** next to a branch to insert an entire sub-object (for example, the full contact).
**Examples**
* Map phone: `{{ trigger.payload.contact.phone }}`
* Map contact ID from an upsert step: `{{ steps.create_or_update_contact.contact_id }}`
* Map booking slot: `{{ steps.calendly_get_available_times.slots[0].start }}`
**Draft vs Live**
* **Draft:** run safely with test payloads; **Output -> Refresh** updates schemas.
* **Live:** runs on real events. Only switch to Live after your test pass.
## 2) Thoughtly steps (core)
These power calls, contacts, and internal data flow. They are the backbone of most automations.
### A) Call Phone Number
Call any phone number with a selected ***Agent***.
* **Inputs**
* **Agent** - choose which agent places the call.
* **Phone number** - map from Trigger/Step (for example, `{{ trigger.payload.contact.phone }}`).
* **Genius (optional)** - attach a specific knowledge base for this call. You can now select a single Genius source, which prevents context hallucinations and helps manage RAG database sizes.
* **Language / Voice (optional)** - override the agent defaults per call.
* **Metadata (optional)** - JSON key-values injected into the agent for this call only (see [Attributes vs Metadata](/automations/attributes-vs-metadata)).\
Example: `{"campaign":"q4","lead_source":"typeform","priority":2}`
* **Output** - `call_id`, status, timestamps, duration, provider metadata.
* **Warnings**
* **Refreshing Output places a real call** to the mapped number. Test with internal numbers.
* **Outbound calling restrictions**: If you select an agent whose connected phone number has outbound calling disabled, a warning will appear. Enable "Allow Outbound Calls" in the phone number settings to resolve this.
* **Typical uses** - ad-hoc callbacks, small pilot campaigns.
### B) Call Contact
Call a Thoughtly **Contact** by ID so you can track history and write **Attributes**.
* **Why this vs Call Phone Number?** Lets you persist traits as Attributes and reuse them across future calls.
* **Prerequisite** - obtain a `contact_id` via **Create or Update Contact** or **Get Contact by Phone Number**.
* **Inputs** - `contact_id`, optional Genius (can select a single source to prevent context hallucinations and manage RAG database sizes), Language/Voice, Metadata.
* **Output** - same call telemetry plus contact linkage.
* **Warnings**: If you select an agent whose connected phone number has outbound calling disabled, a warning will appear. Enable "Allow Outbound Calls" in the phone number settings to resolve this.
* **Create or Update Contact** - upsert a contact; returns `contact_id`.
* **Get Contact by Phone Number** - fetch to avoid duplicates or enrich calls.
* **Add Attributes to Contact** - set persistent key-values (plan, region, lifetime\_value).
* **Add Tags to Contact** - apply lightweight labels (vip, pilot).
* **Add Disposition** - write a post-call label or result for analytics.
* **Get All Contacts** - list contacts for batch processing or export.
### D) Messaging and inbound
* **Send SMS** - confirmations, links, follow-ups (map `to`, `body`).
* **Connect Inbound Call** - complete the inbound connection after [On Inbound Call](/automations/triggers#thoughtly-on-inbound-call) pre-checks.
### E) Genius source tools
Maintain the knowledge base your agents use:
* **Add Source to Genius** - add new content to a Genius source.
* **Edit Genius Source** - update a source's content or metadata.
* **Delete Genius Source** - remove a source from the Genius knowledge base.
* **Get Genius Source Content** - fetch the full content for a source.
## Recent action improvements
### Dynamic values in number and date fields
Many numeric and date-like fields now support dynamic values from previous triggers or steps. When a field exposes the data picker or custom-value mode, you can insert variables such as:
```text theme={null}
{{ steps.calculate_delay.delay_seconds }}
{{ trigger.payload.requested_date }}
```
Use dynamic values when call timing, delay duration, appointment date, quantity, or scoring depends on prior workflow data.
### Automatic retry for webhook rate limits
When a webhook action receives a `429` response, Thoughtly automatically respects the `Retry-After` header up to the supported retry window and retries once. If the retry succeeds, the automation continues. If it fails again, the run is marked failed.
For non-rate-limit errors such as `400` or `500`, design the receiving system and workflow to handle failure explicitly.
### Send Email
Use **Send Email** to send email from a connected email channel as part of an automation. Typical uses include confirmations, summaries, follow-ups, or internal notifications.
Before using Send Email, configure your email domain and connected addresses in [Email domains](/platform/settings/email-domains).
### Send SMS
Use **Send SMS** for confirmations, reminders, and short follow-up messages. If you want the contact to continue a two-way conversation with an agent, use an agent-led SMS conversation pattern rather than treating SMS as a one-off notification.
### Code
Use **Code** for advanced transformations and calculations. Code runs in a restricted sandbox and is best for last-mile customization such as normalizing phone numbers, scoring leads, or reshaping webhook payloads.
See [Code](/integrations/developer/code).
## 3) AI and logic steps
### A) AI
AI
✨
Extract Fields
✨
Custom Prompt
* **Extract Fields** - structured extraction from text. Example configuration:
* Input: `{{ steps.call_contact.transcript }}`
* Schema: `{"email":"text","budget":"number","callback_ok":"boolean"}`
* **Custom Prompt** - generate a summary, label, or next action; feed into **Conditions**.
### B) Conditions
Condition
🔀
Filter
🔀
If Else
🔀
Switch
🔀
Random Outcome
Deterministic branching and filtering.
* **Filter** - drop records that do not qualify. Example: `budget < 100000` -> drop.
* **If / Else** - binary branch. Example: `email` matches `/.+@.+\..+/` -> valid path; else ask to re-spell.
* **Switch** - multi-way branch. Example: plan in `[basic, pro, enterprise]`.
* **Random Outcome** - split traffic for experiments (for example, 80% A and 20% B).
### C) Loop
Iterate over a list (for example, CRM rows) and execute nested steps per item.
* **Loop on Items** - iterate over each item in an array and run nested steps.
* **Inputs:** array path (for example, `{{ steps.salesforce_query.records }}`), optional batch size, max items.
* **Loop variables:** `{{ loop.index }}` (zero-based), `{{ loop.item }}` (current object).
* **Example:** loop contacts -> **Call Contact** each -> **Add Disposition** on result.
* **Credit usage:** Each iteration of a loop step consumes 1 credit (for AppSumo plans) or counts as 1 automation step, the same as regular automation nodes.
#### Conditional logic inside loop nodes
You can now add **Conditions** (Filter, If/Else, Switch) directly inside a loop node. This lets you branch or skip steps on a per-item basis without needing a separate outer condition step.
**How it works**
1. Inside a **Loop on Items** node, add a **Conditions** step as you would anywhere else in the automation.
2. Reference `{{ loop.item }}` fields in your condition expressions to evaluate each item individually.
3. Each branch inside the loop runs only for items that match its condition; items that do not match follow the else/default branch or are skipped.
**Example: call only qualified leads**
```text theme={null}
Loop on Items → {{ steps.salesforce_query.records }}
└─ If / Else
├─ IF {{ loop.item.lead_score }} >= 80
│ └─ Call Contact
│ └─ Add Disposition
└─ ELSE (skip — no steps)
```
**Tips**
* Use **Filter** inside the loop to drop items early and avoid unnecessary downstream steps.
* Use **Switch** when items fall into more than two categories (for example, routing by `loop.item.region`).
* Nested conditions count toward the automation step total the same as any other condition node.
When the source app supports server-side filters (such as SOQL in Salesforce), filter upstream and keep automation logic simple. Reserve in-loop conditions for logic that depends on per-item data only available at runtime.
## 4) Time utilities
* **Delay For** - pause the workflow for a fixed duration (for example, `PT30S`).
* **Delay Until** - pause the workflow until a specific timestamp.
* **Get Current Time** - return the current time in the selected timezone.
* **Get Current Date** - return today's date.
* **Get Current Date and Time** - return the current timestamp.
* **Convert Timezone** - convert a timestamp between timezones.
* **Convert Date and Time Format** - reformat date/time strings (ISO to custom formats).
## 5) Webhook and utility
### Webhook
* **Send Webhook** - POST data to external systems.
* **Headers:** include auth (for example, `X-API-Token`).
* **Idempotency:** send an `event_id`; make downstream receivers idempotent.
* **Retries:** design your receiver for retries/backoff.
### Utility
* **Get Website Content** - fetch and parse HTML or JSON for enrichment.
## 6) Scheduling and booking integrations
Pick the tool your team uses; patterns are similar (availability -> choose slot -> schedule -> confirm).
### Acuity
* **Create Appointment** - create a new appointment.
* **Update Appointment** - update an existing appointment.
* **Cancel Appointment** - cancel an appointment.
* **Reschedule Appointment** - move an appointment to a new time.
* **Get Available Times** - return available time slots.
* **Get Available Dates** - return dates with availability.
* **Get Availability in Date Range** - return availability within a date range.
* **Get Availability in Date Range for Calendars** - return availability by calendar in a date range.
* **Search Appointments** - find appointments by filters.
* **Get Appointment Types** - list appointment types.
* **Get Calendars** - list calendars.
* **Get Forms** - list intake forms.
* **Get Form by Appointment Type ID** - fetch the form for a specific appointment type.
### Acuity Enterprise
* **Create Appointment** - create a new appointment.
* **Update Appointment** - update an existing appointment.
* **Cancel Appointment** - cancel an appointment.
* **Reschedule Appointment** - move an appointment to a new time.
* **Get Available Times** - return available time slots.
* **Get Available Dates** - return dates with availability.
* **Get Availability in Date Range** - return availability within a date range.
* **Get Availability in Date Range for Calendars** - return availability by calendar in a date range.
* **Search Appointments** - find appointments by filters.
* **Get Appointment Types** - list appointment types.
* **Get Calendars** - list calendars.
* **Get Forms** - list intake forms.
* **Get Form by Appointment Type ID** - fetch the form for a specific appointment type.
### Cal.com
* **Check Booking Availability** - check availability for a specific slot or event.
* **Create Booking** - create a booking for a selected slot.
### Calendly
* **Get Available Times** - fetch bookable times for an event type.
* **Schedule Appointment** - schedule a Calendly appointment.
* **Get Event Type Availability** - check availability for an event type.
* **Get Event Type Availability By Organization** - check availability across an organization.
* **Schedule Event** - schedule an event for a user.
* **Schedule Event By Organization** - schedule an event within an organization.
* **Check Availability** - check host availability for a time range.
* **Schedule Event With Reference** - schedule an event with an external reference ID.
### GoHighLevel (scheduling)
* **Get Available Times** - retrieve available appointment slots.
* **Schedule Appointment** - book an appointment.
### Mindbody
* **Get Bookable Times** - fetch available bookable times.
* **Get Bookable Time for All Session Types** - fetch availability across session types.
* **Add Appointment** - create an appointment.
* **Get Locations** - list locations.
* **Add Client** - create a client profile.
* **Get Client by Email** - find a client by email.
* **Get Client by Phone** - find a client by phone number.
### Zoho Bookings
* **Create Appointment** - create a new appointment.
* **Fetch Appointments** - list appointments by filter or date range.
* **Reschedule Appointment** - move an appointment to a new time.
* **Delete Appointment** - cancel an appointment.
* **Fetch Availability** - retrieve available time slots.
**Recipe:** lookup availability -> present or auto-select -> schedule -> **Send SMS** confirmation -> write **Attributes** such as `last_booking_at`.
## 7) CRM and marketing integrations
Manage contacts, leads, and deals across systems. Typical pattern: search -> create/update -> note -> follow-up.
### GoHighLevel
* **Create Contact** - create a contact record.
* **Search for Contact** - search contacts by fields.
* **Create Note** - add a note to a contact.
* **Retrieve Contact** - get a contact by ID.
* **Update Contact** - update contact fields.
* **Delete Contact** - delete a contact.
### HubSpot
* **Create Contact** - create a new contact.
* **Retrieve Contact** - fetch a contact by ID.
* **Update Contact** - update contact properties.
* **Delete Contact** - delete a contact.
* **Search Contact** - search contacts by criteria.
* **Get Deal** - retrieve a deal by ID.
* **Update Deal** - update deal properties.
### Keap
* **Create Contact** - create a new contact.
* **List Contacts** - list contacts with optional filters.
* **Retrieve Contact** - get a contact by ID.
* **Update Contact** - update contact details.
* **Delete Contact** - delete a contact.
### Pipedrive
* **Create Lead** - create a new lead.
* **Update Lead** - update lead details.
* **Get Lead** - retrieve a lead by ID.
* **Delete Lead** - delete a lead.
* **Get Leads** - list leads.
### Salesforce
* **Execute SOQL Query** - run a SOQL query and return records.
* **Create Object** - create a new object record.
* **Update Object** - update an existing object record.
* **Delete Object** - delete an object record.
* **Add Topic to Object** - add a topic/tag to an object.
* **Get Access Token** - generate an access token for API calls.
### Salesforce Sandbox
* **Execute SOQL Query** - run a SOQL query and return records.
* **Create Object** - create a new object record.
* **Update Object** - update an existing object record.
* **Delete Object** - delete an object record.
* **Add Topic to Object** - add a topic/tag to an object.
* **Get Access Token** - generate a sandbox access token for API calls.
### Zoho CRM
* **Search Record** - search records by criteria.
* **Create Record** - create a new record.
* **Update Record** - update a record.
* **Delete Record** - delete a record.
**Recipe:** trigger on new or changed record -> normalize fields -> **Conditions** route -> if qualified -> **Call Contact** with metadata `{"campaign":"q4"}` -> **Add Disposition** -> update the CRM.
## 8) Collaboration, sheets, and ops
### Slack
* **Send Message** - post a message to a channel.
* **Send Direct Message** - send a direct message to a user.
* **Delete Message** - delete a message.
### SmartSheet
* **Get Sheets** - list available sheets.
* **Get Row** - retrieve a row by ID.
* **Get Sheet** - fetch sheet details.
* **Search Sheet** - search rows by query.
* **Add Row** - add a row to a sheet.
* **Update Row** - update a row.
* **Search Column** - find columns by name or ID.
### Trello
* **Create Card** - create a card in a list.
* **Update Card** - update card fields.
### Zendesk
* **Create Ticket** - create a support ticket.
**Recipe:** on error or high intent, notify Slack, open a Zendesk ticket, add a SmartSheet row for audit.
## 9) Error handling and resilience
* **Happy path:** check explicit success flags (for example, `action_status == "ok"`).
* **Retryable:** if transient error and retries \< 2 -> **Delay For** `PT30S` -> retry the step.
* **Fallback:** after max retries -> **Send SMS** apology or leverage a ***Transfer node*** in the voice flow; create a ticket.
* **Timeouts:** if an action exceeds the SLA, branch to a graceful path and continue.
* **Idempotency:** ensure webhook and CRM writes are safe on retry.
## 10) Best practices
* Prefer **Call Contact** when you need persistent history and Attributes; use **Call Phone Number** for ad-hoc calls.
* Use **Metadata** for per-call context (temporary); use **Attributes** for persistent facts. See [Attributes vs Metadata](/automations/attributes-vs-metadata).
* Keep expressions simple; move heavy logic into upstream queries or dedicated **Conditions**.
* Add explicit **Else/Default** branches to avoid dead ends.
* Test in **Draft** with safe numbers. Remember: **Refreshing Output** on call steps places real calls.
## See also
* [Automations - Triggers](/automations/triggers) - where automations start.
* [Attributes vs Metadata](/automations/attributes-vs-metadata) - what to store and when.
* [Automations overview](/automations/getting-started) - preparing data and contacts before and after calls.
* [On Inbound Call trigger](/automations/triggers#thoughtly-on-inbound-call) - logic before connecting inbound calls.
# Attributes vs metadata in automations
Source: https://docs.thoughtly.com/automations/attributes-vs-metadata
Understand the difference between contact attributes and call metadata in Thoughtly so you know what data persists on a contact and what lives per call.
If you have built an agent already, you know about **in-agent variables** (from ***Variables*** extraction and mid-call ***Actions*** inside the Agent Builder). Automations add two more ways to pass data into calls and keep it around across calls: **Metadata** and **Attributes**.
| Feature | **Metadata** 📝 | **Attributes** 💾 |
| ------------------- | --------------------------------------------------- | ------------------------------------------ |
| **Scope** | Single call only | Persistent on contact |
| **Lifespan** | Temporary (discarded after call) | Permanent (survives across calls) |
| **Use cases** | Campaign labels, A/B testing, call-specific context | Customer preferences, status, demographics |
| **Set from** | Automation steps (Call Phone Number, Call Contact) | Automations, API, manual contact updates |
| **Access in agent** | `{{metadata.VARIABLE_NAME}}` | `{{attributes.VARIABLE_NAME}}` |
| **Example** | `campaign: "summer_promo"` | `preferred_language: "spanish"` |
| **Think of it as** | A sticky note on this one call | A sticky note on the contact record |
Think of them like sticky notes:
* **Metadata** = a sticky note **on this one call**. Use it, then toss it.
* **Attributes** = a sticky note **on the contact**. It stays for future calls.
## Metadata - short-lived, per-call context
You add **Metadata** in an automation step that **places a call** (***Call Phone Number*** or ***Call Contact***). It travels only with that call.
**When to use**
* Campaign labels you do not need long term (for example `campaign`, `utm_source`)
* A/B variant flags (for example `script_version: "B"`)
* Temporary hints just for the agent (for example `priority: 2`, `intent: "book_demo"`)
**Reference inside the agent**
```
{{metadata.VARIABLE_NAME}}
```
Example: `{{metadata.campaign}}` -> `q4`
**Set from automations**
In **Call Phone Number** or **Call Contact**, add a JSON object in **Metadata**:
```json theme={null}
{"campaign": "q4", "intent": "book_demo", "priority": 2}
```
**Lifecycle**
* Exists during the call only.
* Not written back to the contact automatically.
* If you want to keep it, log a summary or copy values into **Attributes** after the call.
## Attributes - persistent facts about a contact
**Attributes** live on the **Thoughtly Contact** record. They are created or updated by steps like **Create or Update Contact** or **Add Attributes to Contact**.
**When to use**
* Traits you will reuse: `region`, `plan`, `lifetime_value`, `last_booking_at`
* Routing decisions across many calls: `vip: true`, `do_not_call_until: "2025-11-01"`
* Data you need available for inbound logic (see [On Inbound Call](/automations/triggers#thoughtly-on-inbound-call))
**Reference inside the agent**
```
{{system.contact.attributes.ATTRIBUTE_NAME}}
```
Examples:
* `{{system.contact.attributes.region}}` -> `EU Central`
* `{{system.contact.attributes.vip}}` -> `true`
**Set from automations**
Use **Create or Update Contact** (upsert) or **Add Attributes to Contact**.
Example payload:
```json theme={null}
{"vip": true, "plan": "pro", "lifetime_value": 12450}
```
**Lifecycle**
* Sticks to the contact across all future calls (outbound and inbound).
* Overwrites on the next update if you send the same key.
## How they work together
A practical sequence might look like this:
1. ***Webhook*** trigger arrives with `{ phone, intent }`.
2. **Create or Update Contact** -> set Attributes `{source:"ads", region:"US"}`.
3. **Call Contact** with Metadata `{intent:"book_demo", campaign:"q4"}`.
4. Inside the agent prompt:
* "If `{{metadata.intent}}` is `book_demo`, offer times."
* "Mention support region `{{system.contact.attributes.region}}`."
5. Post-call (***On Call Completed*** automation, scoped to one agent, multiple agents, or All Agents):
* Write `last_called_at` and `last_outcome` as Attributes for reporting.
## Quick Do / Don't
**Do**
* Use **Metadata** to carry per-call flags (campaign, test group, intent, priority).
* Use **Attributes** for facts you will reuse (segment, plan, consent timestamps).
* Name keys in `lower_snake_case` (campaign, last\_purchase\_at).
* Keep values simple: strings, numbers, booleans, ISO dates.
**Don't**
* Do not store PII you do not need.
* Do not rely on Metadata to be available on future calls; it will not be.
* Do not pack huge JSON blobs into Attributes; keep them concise.
## Common patterns
* **Campaign calls:** Metadata `{campaign:"spring"}` + Attribute `last_called_at`
* **A/B testing:** Metadata `{variant:"B"}` + Attribute `last_variant:"B"` (for long-term tracking)
* **Inbound readiness:** Attributes `{plan:"pro", vip:true}` set ahead of time so inbound routing is instant
* **Compliance:** Attributes `{consent_sms:true, consent_recorded_at:"2025-10-07"}`
## FAQ
**Can I copy Metadata into Attributes?**\
Yes. After the call (***On Call Completed***), add a step to write selected Metadata keys into Attributes.
**Which wins if both exist?**\
They do not conflict. Metadata is read-only to the call; Attributes live on the contact. If both define something like `priority`, your prompt decides which to honor.
**Where do I see them?**\
Metadata appears in call context and logs. Attributes show on the contact record and can be searched or filtered.
## See also
* [Variables](/agents/variables) - in-agent extraction and prompts
* [Automations - Steps](/automations/actions) - call steps where you set Metadata and Attributes
* [Automations - Triggers](/automations/triggers) - where automations start
* [Automations overview](/automations/getting-started) - write results back into Attributes for reporting
# Get started with Thoughtly automations
Source: https://docs.thoughtly.com/automations/getting-started
Build automation workflows that trigger Thoughtly voice agents on a schedule, from CRM events or webhooks, and run post-call actions like tagging and sync.
**Prerequisites**: Complete [Agent Builder Overview](/agents/overview) first.
Automations are the [workflows](/resources/glossary#workflow) that trigger your Voice Agents, run actions prior to connecting a call, or perform actions after a call. By setting up Automations, you can connect your Voice Agents to any CRM, calendar, or other software within minutes.
Unlike the [generative](/resources/whitepapers/conversational-ai) and "human-like" nature of Voice Agents, Automations are fully deterministic, meaning you can rely on them to run exactly as you've set them up.
## What can Automations do?
The power of a Thoughtly Voice Agent comes from its ability to connect to other software and systems. Automations are the key to unlocking this power, allowing you to do a number of advanced tasks.
Here are just a few examples:
Automations can turn your CRM into a powerful "brain" that powers your Voice Agents, allowing them to access and update customer records in real-time.
When a new lead is added to your CRM, you can trigger an Automation to trigger your Voice Agents to make a call, who can then reach out to the lead and update the CRM with the outcome.
Using the [Inbound Call](/automations/triggers#thoughtly-on-inbound-call) trigger, when a call comes in, you can trigger an Automation to retrieve data from your CRM, Google Sheets, or other software. Once the data is retrieved, you can connect the call to your Voice Agents with all the information they need to have a productive conversation.
This allows your Voice Agents to have all the information they need to have a productive conversation with the caller, whether it's real-time stock prices, customer purchase history, or current inventory levels.
Using the [Recurring Schedule](/automations/triggers#time-recurring-schedule) trigger, you can set up an Automation to run at a specific time every day, week, or month. There are endless possibilities for what you can do with this, from sending out appointment reminders, making calls to new leads during business hours, or just checking in with customers on a regular basis.
When used in conjunction with other Actions, you can create complex workflows that run automatically, without any manual intervention.
Automations can be triggered by a wide variety of events, including form submissions. Using available [Integration Triggers](/automations/triggers#integration-triggers) that connect to form software like Typeform, Google Forms, Meta Ads, GoHighLevel Forms, or JotForm, you can trigger an Automation to call a lead immediately after they submit a form.
This allows you to reach out to leads while they're still engaged, increasing the likelihood of a successful conversation.
Automations have two main components:
1. **[Triggers](/automations/triggers)**: Events that start the automation (e.g., new CRM lead, call completed)
2. **[Actions](/automations/actions)**: Tasks the automation performs (e.g., make a call, send SMS, update CRM)
When you create an Automation, you'll first select a Trigger, then add one or more Actions. Variables are automatically created by steps and can be passed between actions using the field picker—see [data mapping](/automations/actions#step-anatomy-and-data-mapping) for details.
## Creating Your First Automation
To create a new Automation, open **Tools → Automations** in the primary navigation (or go directly to [Automations](https://app.thoughtly.com/automation)). From there, you can create a new Automation, or view and edit existing Automations.
When a new Automation is created, you'll first be prompted to select a [Trigger](/automations/triggers). This is what will start the Automation. For example, you could select the "Inbound Call" trigger to run an Automation every time a call is received, or the "New Lead" trigger to run an Automation every time a new lead is added to your CRM.
After selecting a Trigger, you'll be prompted to add one or more [Actions](/automations/actions). These are the tasks that the Automation will perform. For example, you could add an action to make a call, send an SMS, or update a record in your CRM.
When configuring integration actions, if you have multiple accounts connected for the same integration, you can select which account to use in the Account tab of the action configuration.
For detailed information on configuring steps, using variables, and data mapping, see the [Actions documentation](/automations/actions).
## Activating Your Automation
By default, Automations are created in a "draft" state, meaning they won't run until you activate them. To activate an Automation, simply click the "Activate" button in the top right corner of the Automation editor.
Once the Automation is activated, it will run every time the Trigger event occurs. Thoughtly will continuously monitor for the Trigger event, then run the subsequent Actions when the event occurs.
**Common Mistake**: Forgetting to activate an automation after testing. Draft automations never execute, even when trigger events occur. Always click "Activate" when ready for production.
## Troubleshooting
If your automation isn't working as expected:
* Verify automation is set to "Active" (not Draft)
* Check trigger event configuration in [Triggers documentation](/automations/triggers)
* Review data mapping and field paths in [Actions documentation](/automations/actions)
* Test steps individually using Draft mode
## See also
* [Triggers](/automations/triggers) - when and why automations run
* [Actions/Steps](/automations/actions) - what automations can do, variables, and data mapping
* [Attributes vs Metadata](/automations/attributes-vs-metadata) - data persistence patterns
* [Agent Actions](/agents/actions) - mid-call actions vs automation steps
* [Glossary: Workflow](/resources/glossary#workflow) - understanding automation concepts
To learn more about the different Triggers available in Thoughtly, continue to the [Triggers](/automations/triggers) section.
# Automation triggers
Source: https://docs.thoughtly.com/automations/triggers
Configure when Thoughtly automations run with schedules, webhooks, CRM events, post-call hooks, and integration-specific triggers from HubSpot and GoHighLevel.
**Triggers** are the starting point for any automation. Pick one on the canvas to decide **when** and **why** it runs.
Open an automation and click the canvas, then choose **Trigger**.
Trigger nodes cannot be deleted from an automation. To change the trigger type, use the **Change** option in the node's action menu instead of deleting and recreating.
## How triggers work (UI anatomy)
Most triggers share the same layout.
* **Account / Configure** - Connect an external account (Salesforce, HubSpot, etc.) and pick event options (object, list, form, and so on).
* **Output** - Shows the **sample payload** (schema) your trigger provides. When testing in **Draft** mode, click **Refresh** after firing a sample to update the schema so field mapping stays accurate.
* Copy the field paths you will need later (for example `contact.email`, `deal.amount`).
* If a field is missing, send another sample event and click **Refresh** again.
* **Next step** - Choose what runs after the trigger (Thoughtly steps such as **AI**, **Conditions**, **Loop**, or an integration action such as `Create Contact`).
Draft mode lets you fire safe test events. Live mode executes real downstream steps. Only flip to Live when everything is tested.
## Thoughtly triggers (built-in)
Built-in triggers do not require external accounts and cover the core orchestration cases.
### 1) Time -> Recurring Schedule
* **Use cases:** business-hours call campaigns, nightly CRM sweeps, weekly no-show follow-ups.
* **Key options:** timezone, days of week, start time, repeat cadence.
* **Best practices:** keep schedules narrow (for example Mon-Fri 09:00-18:00) to avoid after-hours calling. Pair with **Conditions** to skip contacts without phone/email.
**Example:** "Every weekday at 10:00 Kyiv time, pull today's book-now contacts and queue outbound calls."
### 2) Webhook -> Incoming Webhook
* **Use cases:** kick off campaigns from your CRM, respond to cart-abandon events, start follow-ups when a form submits.
* **How to use:**
1. Copy the unique URL.
2. Send a JSON `POST` with your payload.
3. In **Output**, click **Refresh** to lock the schema.
* **Security tips:** enable webhook verification under Settings -> Developer, generate an API key, and send it in the `x-api-token` header.
**Example payload**
```json theme={null}
{
"event_id": "abc-123",
"contact": {
"first_name": "Iryna",
"phone": "+18001234567"
},
"intent": "car_purchase"
}
```
### 3) Thoughtly -> On Inbound Call (special)
* Fires **before** an inbound call connects to an agent-the entry point for pre-call inbound automations.
* **Use cases:** identity/CRM lookup, spam or fraud checks, VIP routing, setting attributes for downstream logic.
* **Output:** caller number, dialed number, timestamp, and available carrier metadata.
* **Pattern:** Trigger -> **AI** or **Conditions** -> set **Attributes**/**Metadata** -> continue inbound flow.
### 4) Thoughtly -> On Call Completed (special)
* Fires **after** a call ends for post-call automations.
* **Use cases:** dispositions, summaries, sentiment scoring, CRM updates, notifications, analytics.
* **Output:** rich call data-durations, outcomes, variables captured, action flags, transfers, voicemail detection.
* **Pattern:** Trigger -> parse payload with **Conditions** -> write to CRM, spreadsheets, or BI.
**Trigger scope:** Choose which agents trigger this automation:
* **Specific Agents** - Select one or more agents from the multi-select dropdown. The automation triggers only when calls complete for the selected agents. Output variables are generated based on the structure of the first selected agent. You can select multiple agents to monitor several agents with a single automation.
* **Outbound calling restrictions**: If you select an agent whose connected phone number has outbound calling disabled, a warning will appear dynamically based on the selected option's `outbound_enabled` property from the integration payload. This trigger can still monitor calls from agents with restricted numbers, but those agents won't be able to make outbound calls through automation steps.
* **All Agents** - The automation triggers whenever a call is completed by any current or future agent. Use this for global monitoring, analytics, or workflows that apply across your entire team. This option is ideal for organization-wide reporting, compliance logging, or universal post-call workflows.
**Backwards compatibility:** Existing automations created before this feature will continue to work without modification. They automatically use the "Specific Agents" scope with their originally selected agent.
If you're trying to capture **post-call data** and currently rely on a “call completed” webhook endpoint (for example from the Developers page), prefer **Thoughtly -> On Call Completed** instead. Add a **Send Webhook** step only when you need to push results to your own server.
When testing the trigger output with the "Generate response" button, the system will use the most recent completed call from your selected agents (or any agent if "All Agents" is selected) to generate sample data. If no calls are available, a mock response will be generated.
**Transcript structure:** The transcript is provided as a structured array of objects, not a plain string. Each entry includes:
* `transcript` - The spoken content
* `speaker` - Either `"ai"` or `"user"`
* `createdAt` - ISO 8601 timestamp when the message was created
* `step` - (AI messages only) The step number in the conversation
* `node_id` - (AI messages only) The node ID from the agent builder
**Example transcript structure:**
```json theme={null}
[
{
"transcript": "Hello, how can I help you today?",
"speaker": "ai",
"createdAt": "2025-11-03T19:33:18.330Z",
"step": 1,
"node_id": "node_abc123"
},
{
"transcript": "I'd like to schedule an appointment",
"speaker": "user",
"createdAt": "2025-11-03T19:33:25.120Z"
}
]
```
See [Post-call automations](/automations/getting-started#building-your-first-automation) for payload deep dives and filtering examples.
## Integration triggers (by app)
Integration triggers start automations when events occur in other tools. The flow is consistent: connect account -> choose event -> inspect **Output** -> configure the **Next step**.
**Supported triggers:**
### GoHighLevel
* **On Contact Created** - Triggered when a contact is created.
### HubSpot
* **On Contact Created** - Triggered when a contact is created.
### Keap
* **On Contact Created** - Triggered when a contact is created.
### Salesforce
* **New Contact** - Triggered when a new contact is created in Salesforce.
* **New Object** - Triggered when a new object is created in Salesforce.
### Salesforce Sandbox
* **New Contact** - Triggered when a new contact is created in Salesforce Sandbox.
* **New Object** - Triggered when a new object is created in Salesforce Sandbox.
### SmartSheet
* **On Row Created** - Triggered when a row is created.
* **On Column Updated** - Triggered when a column is updated.
### Thoughtly
* **On Call Completed** - Triggered when a call is completed.
* **On Inbound Call** - Triggered when an inbound call is received.
### Time
* **Recurring Schedule** - Triggered on the schedule you define.
### Trello
* **On Card Moved to List** - Triggers when a card is moved to a list.
### Typeform
* **New Form Response** - Triggers when a new form response is created.
### Webhook
* **Incoming Webhook** - Triggered when a webhook is received.
### Zoho CRM
* **On Contact Created** - Triggered when a contact is created.
Time and Webhook are built-in triggers, listed here for quick reference.
**Typical next steps by tool**
* *HubSpot / Keap / GoHighLevel / Zoho:* new contact -> Thoughtly agent call or SMS -> update contact with attributes.
* *Salesforce:* new object (Lead) -> lookup phone/email -> route via **Conditions**; if qualified -> create task and start call flow.
* *Typeform:* new response -> map answers to attributes -> enqueue outbound calls.
* *SmartSheet / Trello:* row or card moved -> notify the team, set attributes, call back if the SLA is breached.
**Permissions:** some apps require enabling webhooks or additional scopes. If data is not flowing, check the source app's webhook or permissions configuration.
## Choosing the right trigger (quick guide)
* Run on a schedule -> **Time** (Recurring Schedule)
* React to an external event -> **Webhook** or the app's native trigger
* Pre-call logic before inbound connects -> **On Inbound Call**
* Work after a call ends -> **On Call Completed**
## Best practices
* **Name and tag clearly.** Example: `gohighlevel_on_contact_created_q4_campaign`
* **Test in Draft and refresh Output.** Avoid mapping fields you have not seen in a sample payload.
* **Keep payloads lean.** Map only the data you need into attributes or downstream steps.
* **Plan for idempotency.** Especially for webhooks and external systems that retry events.
## See also
* [Automation steps](/automations/actions) - Thoughtly steps (AI, Conditions, Loop) vs. integration actions.
* [Attributes vs Metadata](/automations/attributes-vs-metadata) - what to store before vs. after calls.
* [Automations overview](/automations/getting-started) - enrich contacts before and after calls.
* [On Inbound Call trigger](#thoughtly-on-inbound-call) - logic before connecting inbound calls.
## Webhook trigger validation
Thoughtly validates that an automation can be triggered by a webhook before accepting external trigger requests. Only automations with webhook-compatible trigger types can be executed through the automation webhook endpoint.
Webhook-compatible triggers include:
* Incoming Webhook
* Salesforce new contact or object triggers
* Zoho CRM contact triggers
* Google Sheets row-created triggers
Requests to trigger automations with incompatible trigger types are rejected. This prevents external requests from executing workflows that were not designed for webhook invocation.
## Manual trigger requirements
The **Manual Trigger** button is enabled only after the automation has a trigger node. If you see a message asking you to add a trigger, add and configure the trigger before testing manually.
# Troubleshoot Thoughtly automations
Source: https://docs.thoughtly.com/automations/troubleshooting
Diagnose and resolve common automation issues in Thoughtly, including triggers not firing, failed steps, missing variables, and CRM sync errors during runs.
## Common Issues
### Automation Not Triggering
If your automation isn't triggering:
* Verify the automation is set to "Live" mode (not Draft)
* Check that the trigger is properly configured
* Review the [Triggers](/automations/triggers) documentation
* Test the trigger event manually if possible
### Action Failures
For action execution failures:
* Check that all required fields are filled
* Verify API credentials for integrated services
* Review variable mappings for data availability
* Check the [Actions](/automations/actions) documentation
#### Outbound Call Failures
If outbound calls are failing with "Outbound calling is disabled" error:
* Verify that outbound calling is enabled for the phone number in [Phone Number Settings](/phone-number/configuration)
* Check that the agent has an outbound phone number assigned
* The automation editor will display a warning when selecting an agent with disabled outbound calling in select or multi-select inputs on outbound nodes
* The warning appears dynamically based on the selected option's `outbound_enabled` property from the integration payload
* Enable outbound calling in the phone number configuration or assign a different phone number to the agent
### Variable Errors
If you're experiencing variable issues:
* Ensure variables are created before they're used
* Verify variable names match exactly (case-sensitive)
* Check that data is available from previous steps
* Review the [Getting Started](/automations/getting-started#variables) guide
### UI Issues
#### Multi-select dropdown stays open when disabled
If you notice that multi-select dropdowns (such as the agent selector in the On Call Completed trigger) remain open even when the automation is in Live mode or the field is disabled:
* This issue has been resolved in recent updates
* The dropdown now properly closes when the automation is set to Live mode
* The dropdown respects disabled and read-only states
* If you continue to experience this issue, try refreshing the page or contact support
### Timing Issues
For automation timing problems:
* Review trigger timing configurations
* Check for rate limits on integrated services
* Verify webhook delivery timing
* Consider adding delays between actions if needed
For additional assistance, visit our [Support Center](/support/getting-help).
# Developer documentation
Source: https://docs.thoughtly.com/developers
Integrate Thoughtly with the REST API and webhooks — authenticate, list agents, trigger calls, manage contacts, and stream live call events.
After [building a Voice Agent](/getting-started/quick-start) using our no-code interface, deploy it using our RESTful API to integrate with your existing systems or build custom solutions.
## Two Approaches to Triggering Calls
### 1. API-Based Triggering (Programmatic)
Trigger calls programmatically from your application code.
**Process**:
1. Create a Contact using `/contact/create`
2. Trigger a call using `/contact/call` with the Contact ID
3. Receive webhook notifications about call status
**Best For**:
* Custom applications
* Direct system integration
* Real-time call triggering
* Fine-grained control
**Example**:
```javascript theme={null}
// Create a contact
const contact = await fetch('https://api.thoughtly.com/contact/create', {
method: 'POST',
headers: {
'x-api-token': 'your_api_token',
'team_id': 'your_team_id',
'Content-Type': 'application/json'
},
body: JSON.stringify({
phone_number: '+15551234567',
name: 'John Doe',
email: 'john@example.com'
})
});
// Trigger the call
const call = await fetch('https://api.thoughtly.com/contact/call', {
method: 'POST',
headers: {
'x-api-token': 'your_api_token',
'team_id': 'your_team_id',
'Content-Type': 'application/json'
},
body: JSON.stringify({
contact_id: contact.id,
agent_id: 'your_agent_id'
})
});
```
### 2. Automation-Based Triggering (Recommended)
Use [Automations](/automations/getting-started) to trigger calls via webhooks.
**Process**:
1. Set up an Automation with a webhook trigger
2. Send webhook POST requests to trigger calls
3. Configure workflow logic in the Thoughtly UI
**Best For**:
* Team collaboration (non-engineers can modify logic)
* Complex workflows
* No-code/low-code solutions
* Rapid iteration
**Benefits**:
* **Non-technical teams** can modify call logic
* **No code changes** required for workflow updates
* **Visual workflow builder** for complex scenarios
* **Flexible webhook payload** for dynamic data
**Learn More**: [Automations Documentation →](/automations/getting-started)
## A Note on Naming
In the API, Voice Agents are referred to as **interviews** (e.g., `/interview/{interview_id}`). This is an internal naming convention — "interview" and "Voice Agent" mean the same thing. All dashboard and documentation references use "Voice Agent," but API paths and response payloads use `interview`.
## Authentication
All API requests require two headers:
```javascript theme={null}
{
'x-api-token': 'your_api_token', // Found in dashboard settings
'team_id': 'your_team_id' // Your team identifier
}
```
**Find Your Credentials**:
1. Log into [Thoughtly Dashboard](https://app.thoughtly.com)
2. Navigate to **[Settings → Developer](/platform/settings/developer)**
3. Copy your API token and Team ID
**Security Best Practices**:
* Never expose your API token in client-side code. Always make API calls from your backend server.
* If an API token is compromised, revoke it immediately through the dashboard to prevent unauthorized access.
* Regularly rotate API tokens as part of your security practices.
## Rate Limits
* **Limit**: 100 requests per minute
* **Response**: `429 Too Many Requests` if exceeded
* **Best Practice**: Implement exponential backoff for retries
```javascript theme={null}
async function apiCallWithRetry(url, options, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
const response = await fetch(url, options);
if (response.status === 429) {
// Wait before retrying
await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
continue;
}
return response;
}
throw new Error('Max retries exceeded');
}
```
## Common Integration Patterns
### Pattern 1: CRM-Triggered Calls
When a new lead is added to your CRM, trigger a qualification call:
```javascript theme={null}
// Webhook from CRM (e.g., Salesforce)
app.post('/webhook/new-lead', async (req, res) => {
const { phone, name, email, company } = req.body;
// Create contact in Thoughtly
const contact = await thoughtly.createContact({
phone_number: phone,
name: name,
email: email,
custom_fields: { company }
});
// Trigger call with qualification agent
await thoughtly.triggerCall({
contact_id: contact.id,
agent_id: 'qualification_agent_id'
});
res.status(200).send('Call triggered');
});
```
### Pattern 2: Calendar-Based Reminders
Send appointment reminders 24 hours before scheduled appointments:
```javascript theme={null}
// Daily cron job
cron.schedule('0 9 * * *', async () => {
const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);
// Get appointments for tomorrow
const appointments = await getAppointments(tomorrow);
// Trigger reminder call for each
for (const apt of appointments) {
await thoughtly.triggerAutomation({
webhook_url: 'your_automation_webhook',
payload: {
contact_phone: apt.phone,
appointment_time: apt.time,
service_name: apt.service
}
});
}
});
```
### Pattern 3: Real-Time Customer Support
Connect voice agent to your support queue:
```javascript theme={null}
// When customer requests callback
app.post('/request-callback', async (req, res) => {
const { phone, issue_type, priority } = req.body;
// Create contact with context
const contact = await thoughtly.createContact({
phone_number: phone,
custom_fields: {
issue_type,
priority,
timestamp: new Date().toISOString()
}
});
// Trigger immediate callback
await thoughtly.triggerCall({
contact_id: contact.id,
agent_id: 'support_agent_id',
priority: priority === 'urgent' ? 'high' : 'normal'
});
res.json({ message: 'Callback initiated' });
});
```
## Webhooks: Receiving Call Data
If your goal is to get structured data **after a call ends**, use an Automation with the **Thoughtly -> On Call Completed** trigger. It supports scoping to **one agent, multiple agents, or All Agents**, and keeps the workflow in Thoughtly (no webhook server required). See [Triggers](/automations/triggers#thoughtly-on-call-completed).
If you need server-to-server delivery to your own infrastructure, configure webhooks to receive real-time updates about calls:
```javascript theme={null}
// Webhook endpoint to receive call completion data
app.post('/webhook/call-completed', async (req, res) => {
const {
call_id,
agent_id,
duration,
outcome,
transcript,
variables
} = req.body;
// Update your CRM
await crm.updateLead({
phone: variables.phone,
call_outcome: outcome,
call_duration: duration,
last_contacted: new Date()
});
// Send notification to sales team
if (outcome === 'qualified') {
await slack.notify('#sales', `New qualified lead: ${variables.name}`);
}
res.status(200).send('Webhook processed');
});
```
**Learn More**: [Webhooks Documentation →](/integrations/webhooks)
## API Reference
For complete API documentation, see:
Complete endpoint documentation with examples
Receive real-time notifications about events
Build workflows without code
Connect with popular platforms
## Best Practices
### 1. Always Validate Phone Numbers
```javascript theme={null}
function isValidPhone(phone) {
// E.164 format: +[country code][number]
const regex = /^\+[1-9]\d{1,14}$/;
return regex.test(phone);
}
```
### 2. Handle Errors Gracefully
```javascript theme={null}
try {
await thoughtly.triggerCall({ contact_id, agent_id });
} catch (error) {
if (error.status === 429) {
// Rate limited - retry later
await queueForRetry({ contact_id, agent_id });
} else if (error.status === 403) {
// Forbidden - check if outbound calling is disabled
logger.error('Outbound calling may be disabled for this agent', error);
} else if (error.status === 400) {
// Invalid request - log and alert
logger.error('Invalid API request', error);
} else {
// Unexpected error
throw error;
}
}
```
### 3. Use Environment Variables
```javascript theme={null}
// .env file
THOUGHTLY_API_TOKEN=your_token_here
THOUGHTLY_TEAM_ID=your_team_id_here
THOUGHTLY_AGENT_ID=your_agent_id_here
// In your code
const config = {
apiToken: process.env.THOUGHTLY_API_TOKEN,
teamId: process.env.THOUGHTLY_TEAM_ID,
agentId: process.env.THOUGHTLY_AGENT_ID
};
```
### 4. Implement Logging
```javascript theme={null}
const logger = winston.createLogger({
level: 'info',
format: winston.format.json(),
transports: [
new winston.transports.File({ filename: 'thoughtly.log' })
]
});
logger.info('Call triggered', {
contact_id,
agent_id,
timestamp: new Date()
});
```
## Support & Resources
* **API Reference**: [Complete documentation →](/api-reference)
* **Email**: [support@thoughtly.com](mailto:support@thoughtly.com)
# Bind Genius knowledge to agents
Source: https://docs.thoughtly.com/genius/agent-binding
Connect a Genius knowledge base to one or more Thoughtly voice agents so agents can answer questions using RAG-powered retrieval from your own content.
Once you've created and populated your Genius knowledge base, the next step is to connect it to your Voice Agents. This process, called "binding," enables your Voice Agent to access the knowledge base during conversations.
## Connecting a Voice Agent
To connect a Voice Agent to a Genius, head to the [Agent Builder](/agents/overview) and click on the **Genius** tab. From here, you can select the Genius you want to connect to your Voice Agent.
## Multiple Agents, One Genius
You can connect the same Genius knowledge base to multiple Voice Agents. This is useful when:
* You have different agents for inbound and outbound calls
* You want specialized agents that share a common knowledge base
* You're testing different agent configurations with the same information
### Example Use Cases
**Customer Service Team**
```
- General Support Agent → Connected to "Company Knowledge Base"
- Technical Support Agent → Connected to "Company Knowledge Base"
- Billing Support Agent → Connected to "Company Knowledge Base"
```
All three agents share the same foundational knowledge but have different conversation flows and specializations.
**Sales Team**
```
- Lead Qualification Agent → Connected to "Product Catalog"
- Demo Scheduler Agent → Connected to "Product Catalog"
- Follow-up Agent → Connected to "Product Catalog"
```
## Switching Genius Connections
You can change which Genius is connected to a Voice Agent at any time:
1. Navigate to the Agent Builder
2. Select the Voice Agent you want to modify
3. Click on the **Genius** tab
4. Choose a different Genius from the dropdown
5. Save your changes
When you switch Genius connections, the Voice Agent will immediately start using the new knowledge base. Make sure the new Genius has all necessary information before switching in a production environment.
## Disconnecting Genius
To disconnect a Genius from a Voice Agent:
1. Go to the Agent Builder
2. Select the Voice Agent
3. Click on the **Genius** tab
4. Select "None" or "No Genius" from the dropdown
5. Save your changes
The Voice Agent will no longer have access to any knowledge base and will rely solely on its prompts and conversation flow.
## Testing Your Connection
After connecting a Genius to a Voice Agent, test it by:
1. Making a test call to the agent
2. Asking questions that should be answered from the Genius
3. Verifying the responses are accurate and relevant
4. Checking that the agent retrieves information correctly
## Troubleshooting
### Agent not using Genius information
**Possible causes:**
* Genius is not properly connected
* The information exists but isn't formatted clearly
* The question doesn't match content in the knowledge base
* Too much information making retrieval difficult
**Solutions:**
* Verify the connection in Agent Builder
* Review and reformat your data sources
* Add more specific Q\&A content
* Reduce irrelevant or redundant information
### Agent providing incorrect information
**Possible causes:**
* Conflicting information across data sources
* Outdated content in the knowledge base
* Ambiguous or unclear content
**Solutions:**
* Review all data sources for contradictions
* Update or remove outdated information
* Clarify content using Q\&A format
## Genius Updates and Agent Behavior
When you update content in a Genius:
* Changes are reflected immediately
* All connected agents will use the updated information
* No need to restart or reconfigure agents
* Test after updates to verify changes work as expected
# Genius knowledge base best practices
Source: https://docs.thoughtly.com/genius/best-practices
Strategies for structuring sources, chunking content, and curating answers so your Thoughtly Genius knowledge base delivers accurate, low-latency answers.
Building an effective Genius knowledge base requires careful planning and ongoing maintenance. Follow these best practices to ensure your Voice Agent has access to accurate, relevant information.
## Content Organization
### Use Q\&A Format
When adding information to your Genius, try to use a question-and-answer format. This will help your Voice Agent find the right information faster based on the caller's question.
**Example:**
```
Q: What are your business hours?
A: We're open Monday through Friday from 9 AM to 5 PM EST, and closed on weekends.
Q: How much does a haircut cost?
A: Our standard haircut starts at $45. Premium styling services range from $65 to $120.
```
### Keep It Up-to-Date
Make sure your Genius is always up-to-date with the latest information. For example, if you upload old call recordings where an agent mentions outdated information, your Voice Agent may provide incorrect information to callers.
**Regular maintenance tasks:**
* Review content monthly
* Remove seasonal or time-sensitive information when no longer relevant
* Update pricing, policies, and procedures immediately when they change
* Archive old recordings that may contain outdated information
### Use Diverse Data Sources
Don't just rely on one type of data source. Use a mix of text, audio, PDF, and URL data sources to provide a wide range of information to your Voice Agent.
This diversity helps your Voice Agent:
* Access information in multiple formats
* Cross-reference details for accuracy
* Provide comprehensive answers
## Content Quality
### Keep It Simple
While you can add a vast amount of information to your Genius, try to keep it simple. The more information you add, the less likely your Voice Agent will be able to find the right information quickly.
**Guidelines:**
* Aim for clarity over comprehensiveness
* Break complex topics into smaller, focused entries
* Remove irrelevant or rarely-accessed information
* Prioritize the most frequently asked questions
### Be Specific and Detailed
When adding information, be specific and provide enough detail for the Voice Agent to give complete answers.
**Poor example:**
```
We offer various services at different prices.
```
**Good example:**
```
Our services include:
- Standard Haircut: $45 (30 minutes)
- Color Treatment: $85-$150 (1-2 hours)
- Full Style Package: $120 (2 hours)
All prices include consultation.
```
### Use Consistent Terminology
Ensure that terminology is consistent across all data sources. If you refer to the same thing in different ways, it may confuse the retrieval system.
## Performance Optimization
### Test Regularly
Regularly test your Genius by:
* Making test calls to your Voice Agent
* Asking common questions
* Verifying accuracy of responses
* Identifying gaps in knowledge
### Monitor Call Outcomes
Pay attention to calls where the Voice Agent couldn't answer questions or provided incorrect information. Use these as opportunities to:
* Add missing information
* Clarify existing content
* Remove confusing or contradictory data
### Size Considerations
While there's no strict limit, consider:
* **Sweet spot**: 10-50 well-organized data sources
* **Maximum recommended**: 100 sources for optimal performance
* **Quality over quantity**: 10 excellent sources beat 100 mediocre ones
## Content Examples
### Good Content Structure
```
Product: Premium Voice Agent Package
Description: Our Premium package includes unlimited calls,
advanced integrations, and priority support.
Pricing: $299/month with annual billing, or $349/month
when billed monthly.
Features:
- Unlimited inbound and outbound calls
- All native integrations included
- Priority 24/7 support
- Custom voice cloning
- Advanced analytics dashboard
Ideal for: Businesses making 1,000+ calls per month
```
### Poor Content Structure
```
We have a premium thing that costs money and has stuff.
```
## Common Pitfalls to Avoid
* **Information overload**: Adding too much irrelevant information
* **Outdated content**: Failing to remove old information
* **Vague answers**: Not providing enough detail
* **Contradictory information**: Having conflicting data across sources
* **Poor formatting**: Using unclear or confusing structure
# Get started with Genius knowledge bases
Source: https://docs.thoughtly.com/genius/getting-started
Set up a Thoughtly Genius knowledge base to augment voice agents with retrieval-augmented generation (RAG) over your own docs, sites, and uploaded files.
**Prerequisites**: Have your business content ready (FAQs, product docs, policies). See [Best Practices](/genius/best-practices) first.
Augment your voice agents with specialized knowledge through AI-powered [retrieval augmented generation (RAG)](/resources/glossary#rag), ensuring agents have access to your business information during every call.
## What is Genius?
Genius databases serve as intelligent knowledge repositories that inform your voice agents about your business, services, and any domain-specific information. Using retrieval augmented generation technology, Genius transforms your source materials into optimized question-and-answer formats that agents can easily understand and reference during calls.
### How Genius Works
1. **Content Ingestion**: You upload various file types or provide URLs containing your business information
2. **AI Processing**: The system analyzes and transforms content into structured Q\&A format
3. **Agent Integration**: Genius databases are connected to specific agents through Automations or Agent Builder
4. **Call Enhancement**: During calls, agents access relevant information to provide accurate, informed responses
## Supported Content Types
Genius accepts multiple content formats to accommodate different information sources:
### File Types
* **Text files**: Plain text documents with business information
* **PDF documents**: Reports, manuals, guides, and formatted documents
* **Audio files**: Recorded training materials or information sessions
* **CSV files**: Structured data (see best practices below for optimal usage)
### Web Content
* **URLs**: Website pages, documentation sites, and online resources
* **Static content**: Information is fetched once during setup and not automatically updated
## Best Practices for Content Types
### Recommended: Unstructured Data
**Why Unstructured Works Better**: RAG technology excels at processing natural language content and converting it into contextual knowledge that agents can understand intuitively.
**Ideal Content Formats**:
* Narrative descriptions of business processes
* Customer service scripts and guidelines
* Product documentation written in conversational style
* FAQ documents with natural language questions and answers
### Use with Caution: Structured Data
**CSV and Spreadsheet Limitations**: While CSV files are supported, they can lead to higher rates of [hallucinations](/resources/glossary#hallucination) or inaccurate responses due to the structured nature conflicting with RAG processing.
**Common Mistake**: Uploading large spreadsheets with complex data relationships. RAG works best with natural language. Convert structured data into Q\&A format instead: "Q: What's the price for Product A? A: \$299."
**When to Use CSV**:
* Simple lookup tables with clear key-value relationships
* Small datasets with straightforward information
* Data that supplements rather than replaces unstructured content
**CSV Best Practices**:
* Keep data simple and avoid complex relationships
* Include descriptive headers that provide context
* Combine with unstructured explanations when possible
```mermaid theme={null}
%%{init: {'theme':'base', 'themeVariables': { 'fontSize':'16px'}}}%%
graph LR
subgraph Recommended["✅ RECOMMENDED: Unstructured Data"]
A["📝 FAQs & Documentation"]
B["💬 Conversational Text"]
C["📄 Natural Language PDFs"]
D["🎙️ Audio Content"]
style A fill:#e8f5e9,stroke:#388e3c,stroke-width:3px
style B fill:#e8f5e9,stroke:#388e3c,stroke-width:3px
style C fill:#e8f5e9,stroke:#388e3c,stroke-width:3px
style D fill:#e8f5e9,stroke:#388e3c,stroke-width:3px
end
subgraph Caution["⚠️ USE WITH CAUTION: Structured Data"]
E["📊 CSV Files"]
F["📈 Spreadsheets"]
G["🗂️ Tables"]
style E fill:#fff3e0,stroke:#f57c00,stroke-width:3px
style F fill:#fff3e0,stroke:#f57c00,stroke-width:3px
style G fill:#fff3e0,stroke:#f57c00,stroke-width:3px
end
Recommended -->|"Best for RAG Low hallucination risk"| H["🤖 Genius Knowledge Base"]
Caution -->|"Higher risk Convert to Q&A format"| H
style H fill:#e3f2fd,stroke:#1976d2,stroke-width:4px
style Recommended fill:#f1f8f4,stroke:#388e3c,stroke-width:2px
style Caution fill:#fff8e1,stroke:#f57c00,stroke-width:2px
```
## Getting Started
### Step 1: Create a Genius Database
1. **Navigate** to **Tools → Genius** in the primary navigation
2. **Click** "Create New Genius" button
3. **Enter** a descriptive database name
4. **Save** to create your new knowledge base
The new database appears in the Genius list and is ready for content addition.
### Step 2: Add Content Sources
1. **Select** your newly created database from the Genius list
2. **Choose** content type (Text, Audio, PDF, CSV, or URL)
3. **Provide** a descriptive name for the source
4. **Upload file** or **enter URL** as appropriate
5. **Save** to begin processing
### Processing Time
Content processing typically takes **2-10 minutes** depending on:
* File size and complexity
* Content type (text processes faster than audio)
* Current system load
A progress indicator shows processing status in the Genius source table.
## Content Management
### Viewing Processed Content
After processing completes:
1. **Click** the three-dot menu next to any source in the table
2. **Select** "View" to see processed content
3. **Review** how your content was transformed into Q\&A format
The processed format shows how agents will understand and access your information during calls.
### Managing Sources
**Edit Sources**: Use the three-dot menu to modify source names or settings
**Delete Sources**: Remove outdated or incorrect content sources
**Add Multiple Sources**: Build comprehensive databases with diverse content types
### Database Management
**Database Settings**: Click the gear icon to modify database name or settings
**Delete Database**: Permanently remove entire databases and all contained sources
**Duplicate Content**: The same source can be added to multiple databases if needed
## Agent Integration
### Connecting to Agents
Genius databases must be explicitly connected to agents through:
**Automations Interface**:
* Select Genius database within automation workflows
* Configure how knowledge is accessed during automated processes
**Agent Builder Interface**:
* Choose Genius database for specific agent configurations
* Set up when and how knowledge is retrieved during calls
### Multiple Database Support
* **Different agents** can use different Genius databases
* **Single agents** can access multiple databases if configured
* **Scope selection** happens during automation or agent setup
## Content Optimization
### Writing for RAG Processing
**Use Natural Language**: Write content as if explaining to a knowledgeable colleague
**Include Context**: Provide background information that helps agents understand when to use specific information
**Ask Questions**: Include common customer questions and comprehensive answers
**Be Specific**: Avoid vague statements that could lead to ambiguous agent responses
### Example Optimization
**Less Effective**:
```
Product A: $50
Product B: $75
Product C: $100
```
**More Effective**:
```
Our product pricing is structured to meet different customer needs:
Product A is our entry-level solution at $50, ideal for small businesses just getting started with our service. It includes basic features and email support.
Product B at $75 represents our most popular package, offering advanced features, phone support, and integration capabilities that most growing businesses require.
Product C at $100 is our enterprise solution with all premium features, dedicated account management, and custom integration support for large organizations.
```
## URL Content Considerations
### Static Content Only
**Important Limitation**: URLs are fetched **once** during setup and are not automatically refreshed or updated.
**Best Practices for URLs**:
* Use stable, long-term content sources
* Avoid frequently changing pages
* Consider downloading and uploading as files for content you control
* Plan to manually update URL sources when content changes significantly
### URL Content Quality
**Choose High-Quality Sources**: Select comprehensive, well-written pages that provide complete information
**Avoid Dynamic Content**: Pages with frequently changing information may become outdated
**Test Accessibility**: Ensure URLs are publicly accessible and not behind authentication
## Safety and Accuracy
### Source Citation
Genius provides **both approaches** for information delivery:
* **Behind-the-scenes processing**: Enhanced agent knowledge without explicit citation
* **Source attribution**: Agents can reference specific sources when appropriate
### Content Grounding
The system is designed to **ground agent responses** in provided source material, reducing hallucinations and ensuring accuracy. However, content quality directly impacts response quality.
### Quality Control
**Review Processed Content**: Always check how your sources were transformed
**Test Agent Responses**: Verify agents provide accurate information from your sources
**Update Regularly**: Remove outdated sources and add current information
**Monitor Performance**: Track how well agents utilize Genius knowledge in real calls
## Expected Results
After successful Genius setup and integration:
**Enhanced Agent Knowledge**:
* Agents provide accurate, company-specific information during calls
* Consistent responses across all agents using the same database
* Reduced need for agent training on factual information
**Improved Call Quality**:
* Faster resolution of customer questions
* More detailed and accurate responses
* Professional handling of complex or specialized inquiries
**Operational Benefits**:
* Centralized knowledge management across all agents
* Easy updates to business information affecting multiple agents
* Scalable knowledge distribution for growing teams
## Limitations
### Current Limitations
* **URL content** is not automatically refreshed
* **Processing time** varies based on content complexity
* **No real-time content updates** for existing sources
### Content Processing Considerations
* **CSV hallucination risk** with complex structured data
* **Processing capacity** may affect upload times during peak usage
* **File size limits** may apply (specific limits not currently published)
Genius is not used to provide prompts or instructions to your Voice Agent. Instead, it is used to provide detailed, unstructured information to callers. For special prompting or instructions, use the Custom Prompt setting in the Agent Builder.
## Troubleshooting
**Agent not using Genius information**
* Verify Genius is connected in [Agent Builder](/agents/settings#genius-tab)
* Check that content has finished processing (status: Complete)
* Test with direct questions that match your content
* Review [Agent Binding](/genius/agent-binding) guide
**Inaccurate or inconsistent answers**
* Review source content for contradictions or outdated info
* Simplify content structure (prefer Q\&A format)
* Remove duplicate or redundant information
* See [Best Practices](/genius/best-practices) for content optimization
**Processing stuck or failed**
* Check file format is supported (PDF, TXT, audio, CSV, URL)
* Verify file size isn't excessive (contact support for limits)
* For URLs, ensure page is publicly accessible
* Try re-uploading the source
**CSV causing hallucinations**
* Convert spreadsheet data to natural language format
* Use simple key-value tables only
* Consider creating text-based Q\&A instead
* See [Best Practices: Structured Data](/genius/best-practices#content-quality)
## See also
* [Genius Sources](/genius/sources) - managing your content
* [Best Practices](/genius/best-practices) - optimizing knowledge bases
* [Agent Binding](/genius/agent-binding) - connecting to agents
* [Agent Settings](/agents/settings#genius-tab) - Genius configuration in agents
* [Glossary: RAG](/resources/glossary#rag) - understanding retrieval augmented generation
# Data sources for Genius
Source: https://docs.thoughtly.com/genius/sources
Add websites, PDFs, text snippets, and uploaded files as data sources to your Thoughtly Genius knowledge base so voice agents can retrieve and answer from them.
Data sources are the foundation of your Genius knowledge base. By adding different types of data, you can ensure your Voice Agent has access to comprehensive information to answer caller questions accurately.
## Available Data Sources
To add data to your Genius, click on the **Add Data Source** button. From here, you can add a new data source. Available data sources include:
### Text
Add unstructured text data to your Genius. This is ideal for:
* Company policies and procedures
* Product descriptions
* FAQs and common questions
* Scripts and call guidelines
Simply paste or type your text content, and Genius will index it for quick retrieval.
### Audio
Add audio data to your Genius, such as recorded calls to train your Voice Agent. This is useful for:
* Training on successful call examples
* Learning from customer interactions
* Understanding tone and phrasing
Genius will transcribe and analyze the audio to extract relevant information.
### PDF
Add PDF documents to your Genius, such as:
* Sales brochures
* Product manuals
* Technical documentation
* Company handbooks
Genius will extract text and structure from your PDFs automatically.
### URL
Add a URL to your Genius to scrape information from a website. Keep in mind that this only provides the text from the page you provide, not the entire website.
This is great for:
* Product pages
* Pricing information
* Terms and conditions
* Blog posts with important information
## Managing Data Sources
### Updating a Data Source
To update a Data Source, click on the three dots next to the Data Source you want to update. From here, you can click **View** to see the data, then click **Edit** to make changes.
### Deleting a Data Source
To delete a Data Source, click on the three dots next to the Data Source you want to delete. From here, click **Delete** to remove the data source.
## Data Source Best Practices
* **Keep content current**: Remove outdated information to prevent incorrect responses
* **Organize by topic**: Group related information together for better retrieval
* **Use clear language**: Write content in clear, conversational language
* **Avoid redundancy**: Don't duplicate the same information across multiple sources
## Editing and deleting sources
When you edit a Genius source, Thoughtly re-indexes the updated content and removes the prior indexed version. Wait for processing to complete before testing the agent against the new content.
When you delete a source, its indexed content is removed so agents no longer reference it.
# Troubleshoot Genius knowledge bases
Source: https://docs.thoughtly.com/genius/troubleshooting
Diagnose and resolve common Genius issues in Thoughtly, including failed source crawls, missing answers, stale content, and unexpected RAG retrieval results.
## Common Issues
### Genius Not Responding Accurately
If Genius isn't providing accurate responses:
* Verify your sources are up to date
* Check that source documents are properly formatted
* Review the [Best Practices](/genius/best-practices) guide
* Ensure the Genius instance is properly bound to your agent
### Source Upload Failures
For source upload issues:
* Verify file format is supported (PDF, TXT, CSV, or Audio)
* Check file size limits
* Ensure the document is not password-protected
* Review the [Sources](/genius/sources) documentation
### Agent Not Using Genius
If your agent isn't utilizing Genius:
* Verify Genius is enabled in agent configuration
* Check the [Agent Binding](/genius/agent-binding) setup
* Ensure the Genius instance is properly configured
* Test with simple queries to verify functionality
For additional assistance, visit our [Support Center](/support/getting-help).
## Stale content after editing a source
If an agent appears to reference old Genius content after you edit a source:
1. Wait until the source status is complete.
2. Test again with a fresh interaction.
3. If stale content persists, delete and re-add the source.
4. Contact support if the deleted content continues to appear.
# Introduction to Thoughtly
Source: https://docs.thoughtly.com/getting-started/introduction
Welcome to Thoughtly — build, test, and deploy AI voice agents in minutes for inbound and outbound calls across sales, support, and operations workflows.
Thoughtly is the leading platform for building and deploying [AI-powered Voice Agents](/resources/glossary#voice-agent) that can handle phone calls, answer questions, book appointments, and integrate with your existing systems.
Build and deploy fully-functional voice agents in under 15 minutes—no coding required.
## How Thoughtly Works
Building with Thoughtly revolves around three core concepts:
Design conversation flows and train your AI agent
Integrate with your CRM, calendar, and other tools
Get a phone number and start taking calls
## What is a Voice Agent?
A **Voice Agent** is a conversational AI that interacts with customers over the phone, providing a human-like experience. Voice Agents can:
* **Answer questions** using your knowledge base
* **Schedule appointments** with your calendar integrations
* **Qualify leads** and route them appropriately
* **Collect information** through natural conversation
* **Transfer calls** to human agents when needed
* **Send SMS messages** for follow-ups and confirmations
## Common Use Cases
### Inbound Calls
When customers call your [Thoughtly phone number](/phone-number/getting-started), your Voice Agent answers and interacts naturally:
Provide existing customers with help and support
Answer calls and route them to the right department
Build an SDR that qualifies leads and sets appointments
Allow customers to call in and schedule appointments
### Outbound Calls
Your Voice Agent can proactively call customers, clients, or leads:
Call leads, qualify them, and book meetings
Confirm or reschedule upcoming appointments
## Common Questions
**Do I need coding experience?**\
No! Thoughtly is built for non-developers. Our drag-and-drop [Agent Builder](/agents/overview) requires zero coding.
**How long does it take to build an agent?**\
You can build a basic agent in [15 minutes](/getting-started/quick-start). Complex agents with integrations may take a few hours.
**What integrations are available?**\
We support [20+ native integrations](/integrations/getting-started) including Salesforce, HubSpot, Calendly, and more.
**Can I use my own phone number?**\
Yes! You can [purchase or import numbers](/phone-number/byoc) through Thoughtly's BYOC (Bring Your Own Carrier) feature, supporting Twilio and Telnyx.
**How much does it cost?**\
See our [pricing page](https://thoughtly.com/pricing) for current plans and credit-based billing information.
## See also
* [Quick Start Guide](/getting-started/quick-start) - build your first agent
* [Use Cases](/getting-started/use-cases) - industry-specific examples
* [Platform Overview](/platform/overview) - understanding the Thoughtly platform
* [FAQ](/resources/faq) - frequently asked questions
* [Glossary](/resources/glossary) - AI voice terminology
## Next Steps
Ready to get started? Here are some helpful resources:
Build your first voice agent in 15 minutes
Explore what's possible with Thoughtly
Learn how to build sophisticated voice agents
Get help from our team
Integrate Thoughtly with your applications
## Need Help?
* **Chat with us**: Click the chat bubble in the bottom right corner
* **Email support**: [support@thoughtly.com](mailto:support@thoughtly.com)
* **Watch tutorials**: [Video Library](/resources/video-library)
# Quick start guide
Source: https://docs.thoughtly.com/getting-started/quick-start
Build, test, and launch your first Thoughtly voice agent in about 15 minutes — create an agent, configure a voice and phone number, then run a live test call.
This quick start guide will walk you through creating your first voice agent from scratch. By the end, you'll have a fully-functional voice agent that can answer calls and interact with customers—in under 15 minutes, no coding required.
## Prerequisites
Before you begin, make sure you have:
* ✅ A Thoughtly account ([sign up free](https://app.thoughtly.com))
* ✅ A clear use case in mind (e.g., receptionist, appointment booking)
* ✅ Basic information about your business
## Step 1: Create Your First Agent
Log into your [Thoughtly dashboard](https://app.thoughtly.com) and click **"Create Agent"** from the main navigation.
Select a template that matches your use case, or start from scratch with a blank agent. Popular templates include:
* **Receptionist** - Answer and route calls
* **Appointment Scheduler** - Book meetings automatically
* **Customer Service** - Handle support inquiries
Set up your agent's basic information:
* **Name**: Give your agent a descriptive name
* **Voice**: Choose from thousands of AI voices in the [Voice Selector](/agents/voices)
* **Language**: Select your primary language
* **Personality**: Adjust tone (friendly, professional, assertive)
## Step 2: Design the Conversation Flow
Every conversation starts with a greeting. Type in your opening message in **"Start node"**. Then click **"Add Node"** to select **"Message Node"** to create your first message.
Example greeting:
```
"Hi! Thanks for calling [Your Business]. My name is [Agent Name]. How can I help you today?"
```
Add decision nodes to handle different customer responses:
* **Question nodes** to gather information
* **Decision nodes** to branch conversations
* **Action nodes** to perform tasks (book appointments, transfer calls)
Set up call outcomes to track performance:
* Appointment booked
* Question answered
* Transferred to human
* Call back requested
## Step 3: Add Knowledge with Genius
Navigate to **Tools → Genius** in the primary navigation and click **"Create New Genius"**. This is where you'll store information your agent needs to know.
Click **"Add Data Source"** and choose a source type:
* **Text**: Paste FAQs, policies, or product info
* **URL**: Scrape information from your website
* **PDF**: Upload product catalogs or manuals
* **Audio**: Upload call recordings for training
Return to your agent in the Agent Builder. In the Settings panel, open the **Genius** tab and select your knowledge base from the dropdown to assign it to this agent.
## Step 4: Get a Phone Number
Navigate to **Settings → Phone Numbers** in the platform navigation and click **Add a Number**.
Choose one of the available options:
* **Purchase from Thoughtly** — search by country and area code, then buy a number directly
* **Import from your carrier** — connect your Twilio or Telnyx account to bring existing numbers into Thoughtly
For a full walkthrough, see [BYOC](/phone-number/byoc).
After the number is provisioned, open your agent in the Agent Builder. In the **Settings** panel, assign the new number so it can receive and place calls.
## Step 5: Test Your Agent
Call your Thoughtly phone number to test your agent. Listen for:
* Clear audio quality
* Natural conversation flow
* Accurate responses from Genius
* Proper call routing
After your test call, go to **History** in the primary navigation to:
* Listen to the recording
* Read the transcript
* Check which outcome was logged
* Review response times
Based on your test:
* Adjust conversation flow
* Add more knowledge to Genius
* Refine voice settings
* Update personality settings
## Next Steps
Congratulations! You've built your first voice agent. Now enhance it:
Connect your CRM, calendar, and other tools
Trigger calls and automate workflows
Create a custom voice that sounds like you
See detailed implementation examples
## Common Issues & Solutions
### Agent isn't answering calls
* ✅ Verify phone number is connected in [Agent Settings](/agents/settings)
* ✅ Ensure agent has a greeting [Start node](/agents/nodes#start-node) configured
* ✅ Test by calling from a different phone
### Agent gives incorrect information
* ✅ Review and update your [Genius knowledge base](/genius/getting-started)
* ✅ Remove outdated or conflicting information
* ✅ Use Q\&A format for better accuracy
* ✅ Verify Genius is connected to your agent
### Voice quality issues
* ✅ Try a different voice from the [Voice Selector](/agents/voices)
* ✅ Check your microphone during test calls
* ✅ Verify network connection is stable
* ✅ Adjust [presence settings](/agents/settings#presence-tab)
**Common Mistake**: Skipping the testing step. Always use [Test Agent](/agents/testing) before making real calls. This catches conversation flow issues, missing variables, and broken outcomes before they affect customers.
## Need Help?
* **Chat Support**: Click the bubble in the bottom right
* **Email**: [support@thoughtly.com](mailto:support@thoughtly.com)
## See also
* [Agent Builder](/agents/overview) - comprehensive agent documentation
* [Genius](/genius/getting-started) - adding knowledge to agents
* [Phone Numbers](/phone-number/getting-started) - managing phone numbers
* [Testing](/agents/testing) - validating agent behavior
* [Use Cases](/getting-started/use-cases) - industry-specific examples
# Voice agent use cases and examples
Source: https://docs.thoughtly.com/getting-started/use-cases
Common Thoughtly voice agent scenarios and implementation patterns — inbound support, outbound sales, appointment booking, qualification, and surveys.
Build advanced Voice Agents for a wide variety of use cases across industries.
## Outbound Call Use Cases
### Lead Follow-up
**Overview**: Call leads to qualify them, answer questions, and set appointments with your sales team.
**Key Features**:
* Call leads from your CRM
* Qualify interest level
* Handle objections
* Schedule meetings
* Update CRM with results
* Send follow-up SMS if no answer
**Recommended Integrations**:
* CRM: [Salesforce](/integrations/crm/salesforce), [HubSpot](/integrations/crm/hubspot)
* Scheduling: [Calendly](/integrations/scheduling/calendly)
* SMS: Built-in SMS capabilities]\(/agents/deployment#sms)
**Important**: Outbound calling requires compliance with regulations like TCPA (U.S.) and similar laws in other countries. Ensure you have proper consent before calling. [Learn more about compliance →](/resources/faq#compliance)
***
### Appointment Reminders
**Overview**: Call customers 24 hours before appointments to confirm or reschedule, reducing no-shows.
**Key Features**:
* Automated reminder calls
* Real-time rescheduling
* Confirmation via SMS
* Calendar integration
* No-show reduction
**Recommended Integrations**:
* Scheduling: [Calendly](/integrations/scheduling/calendly), [Acuity](/integrations/scheduling/acuity), [Mindbody](/integrations/scheduling/mindbody)
* Automation: [Automations](/automations/getting-started) for triggering calls
***
### Business Data Collection
**Overview**: Call businesses to collect operational data, verify information, or conduct surveys.
**Key Features**:
* Structured data collection
* Multi-question surveys
* Data validation
* Export to spreadsheets
* Follow-up sequences
**Recommended Integrations**:
* Spreadsheets: [Smartsheet](/integrations/productivity/smartsheet)
* Project Management: [Trello](/integrations/productivity/trello)
## Industry-Specific Examples
### Healthcare
* **Appointment scheduling** for medical practices
* **Prescription reminders** for pharmacies
* **Patient intake** for new patient information
### Real Estate
* **Lead qualification** for property inquiries
* **Showing scheduling** for property tours
* **Follow-up** for interested buyers
### Hospitality
* **Reservation management** for restaurants
* **Concierge services** for hotels
* **Event booking** for venues
### Professional Services
* **Consultation scheduling** for lawyers, accountants
* **Client intake** for new clients
* **Follow-up calls** for proposal submissions
### Automotive
* **Service appointment booking** for auto repair
* **Test drive scheduling** for dealerships
* **Follow-up** for sales inquiries
## Inbound Call Use Cases
### Customer Service
**Overview**: Provide existing customers with help and support 24/7, reducing wait times and improving satisfaction.
**Key Features**:
* Answer common questions using [Genius knowledge base](/genius/getting-started)
* Look up customer information from your [CRM](/integrations/getting-started)
* Create support tickets in [Zendesk](/integrations/ticketing/zendesk)
* Transfer to human agents when needed
**Recommended Integrations**:
* CRM: [Salesforce](/integrations/crm/salesforce), [HubSpot](/integrations/crm/hubspot)
* Ticketing: [Zendesk](/integrations/ticketing/zendesk)
* Communication: [Slack](/integrations/communication/slack), [Gmail](/integrations/communication/gmail)
***
### Receptionist
**Overview**: Answer calls and route them to the right department or person, just like a human receptionist.
**Key Features**:
* Greet callers professionally
* Identify caller intent
* Route to appropriate department
* Take messages when unavailable
* Handle after-hours calls
**Recommended Integrations**:
* Calendar: [Calendly](/integrations/scheduling/calendly), [Cal.com](/integrations/scheduling/cal-com)
* CRM: [GoHighLevel](/integrations/crm/highlevel)
* Communication: [Slack](/integrations/communication/slack)
***
### Sales (SDR)
**Overview**: Build an AI Sales Development Representative that qualifies leads and sets appointments automatically.
**Key Features**:
* Qualify inbound leads
* Answer product questions
* Handle objections
* Schedule appointments with sales team
* Update CRM with call outcomes
**Recommended Integrations**:
* CRM: [Salesforce](/integrations/crm/salesforce), [HubSpot](/integrations/crm/hubspot), [Pipedrive](/integrations/crm/pipedrive)
* Scheduling: [Calendly](/integrations/scheduling/calendly), [Cal.com](/integrations/scheduling/cal-com)
***
### Appointment Scheduling
**Overview**: Allow customers to call in and schedule, reschedule, or cancel appointments through natural conversation.
**Key Features**:
* Check real-time availability
* Book appointments instantly
* Handle rescheduling requests
* Send confirmation via SMS
* Integrate with calendar systems
**Recommended Integrations**:
* Scheduling: [Calendly](/integrations/scheduling/calendly), [Acuity](/integrations/scheduling/acuity), [Mindbody](/integrations/scheduling/mindbody)
* CRM: [GoHighLevel](/integrations/crm/highlevel)
***
### Preliminary Intake
**Overview**: Collect information from customers before they speak to a human agent, streamlining the intake process.
**Key Features**:
* Gather customer information
* Collect case details
* Qualify urgency
* Route appropriately
* Pre-populate forms
**Recommended Integrations**:
* Forms: [Typeform](/integrations/productivity/typeform)
* CRM: [Salesforce](/integrations/crm/salesforce), [Zoho](/integrations/crm/zoho)
* Spreadsheets: [Smartsheet](/integrations/productivity/smartsheet)
## SMS Integration
Your voice agents can also **send and receive SMS messages** for enhanced customer engagement:
* **During calls**: Send links, confirmation codes, or additional information
* **After calls**: Follow up with summaries or next steps
* **If no answer**: Send text message as alternative contact method
* **Two-way SMS**: Handle conversational text messaging
**Learn More**: [SMS Documentation →](/agents/deployment#sms)
## Getting Started with Your Use Case
Start with a use case that matches your needs, or customize from scratch.
Each use case page includes detailed implementation steps and best practices.
Connect your CRM, calendar, and other tools following our [integration guides](/integrations/getting-started).
Build your knowledge base with relevant business information using [Genius](/genius/getting-started).
Make multiple test calls to refine conversation flow and responses.
Start with low-stakes scenarios before handling critical customer interactions.
## Need a Custom Solution?
Can't find your exact use case? We can help:
* **Support Team**: [Email us](mailto:support@thoughtly.com) with your requirements
* **Referral Program**: [Join our referral program](/support/referral-program) to connect with experts
# Thoughtly AI integration
Source: https://docs.thoughtly.com/integrations/ai/thoughtly
Use the native Thoughtly integration to call other Thoughtly agents, share context across workflows, and chain voice interactions without external glue code.
# Make integration
Source: https://docs.thoughtly.com/integrations/automations/make
Connect Make (formerly Integromat) to Thoughtly to trigger voice agents, sync call outcomes, and orchestrate multi-step workflows across hundreds of apps.
# Zapier integration
Source: https://docs.thoughtly.com/integrations/automations/zapier
Connect Thoughtly to Zapier to trigger voice agents from any Zap, push call outcomes to thousands of apps, and automate workflows without writing code.
# Gmail integration
Source: https://docs.thoughtly.com/integrations/communication/gmail
Connect Gmail to Thoughtly so your voice agents can send personalized follow-up emails, share recordings, and route email replies into agent workflows.
# iMessage / Linq
Source: https://docs.thoughtly.com/integrations/communication/imessage-linq
Route supported iMessage messaging numbers through Linq to Thoughtly agents so the same omnichannel agent can handle text-based conversations alongside other channels.
iMessage support lets eligible messaging numbers connect to Thoughtly agents through Linq for two-way message conversations.
iMessage numbers are messaging-only in Thoughtly. They cannot be used for inbound or outbound voice calls.
## When to use it
Use iMessage when you want supported messaging numbers to:
* Receive inbound messages
* Send replies through a Thoughtly agent
* Continue conversations in a channel contacts already use
* Apply Thoughtly suppression and opt-out handling where supported
## Setup overview
1. Connect your Linq or supported messaging account.
2. Add the required integration token or webhook secret.
3. Copy the Thoughtly webhook URL.
4. Paste the webhook URL into your Linq configuration.
5. Enable supported webhook events such as message sent and message received.
6. Sync or import eligible numbers.
7. Assign numbers to Thoughtly agents for messaging.
## Suppression behavior
Some messaging providers do not provide native suppression-list enforcement. In those cases, Thoughtly enforces suppression internally before sending agent replies.
Review [Consent and suppression](/platform/settings/audiences) before using iMessage for outbound or follow-up workflows.
## Troubleshooting
### Messages are not routing to the agent
Check that:
* The webhook URL is configured in Linq.
* Required webhook events are enabled.
* The number is synced into Thoughtly.
* The number is assigned to an agent.
* The contact is not suppressed for the channel.
### Calls are not working
This is expected. iMessage numbers are messaging-only and do not support voice calls in Thoughtly.
# Slack integration
Source: https://docs.thoughtly.com/integrations/communication/slack
Post call summaries, transfer alerts, and automation outcomes from Thoughtly into Slack channels so your team gets real-time updates on every conversation.
# WhatsApp Business
Source: https://docs.thoughtly.com/integrations/communication/whatsapp-business
Connect WhatsApp Business numbers to Thoughtly so the same omnichannel agent can handle WhatsApp conversations alongside voice, SMS, and email channels.
WhatsApp Business lets Thoughtly agents send and receive WhatsApp messages through connected business numbers. Use it for mobile-first conversations, international follow-up, appointment reminders, and ongoing customer engagement.
WhatsApp has strict messaging rules. Outside the customer-service window, outbound messages generally require approved message templates. Make sure your workflow follows WhatsApp and local messaging rules.
## Prerequisites
Before connecting WhatsApp, make sure you have:
* A WhatsApp Business account
* A business portfolio or Meta Business setup where required
* A phone number eligible for WhatsApp Business messaging
* Any required approved message templates for outbound outreach
* Admin access in Thoughtly
## Connect WhatsApp
1. Go to the WhatsApp or Channels page in Thoughtly.
2. Choose **Connect WhatsApp Business**.
3. Follow the authorization flow for your WhatsApp Business account.
4. Select or import the phone numbers you want to use.
5. Assign each number to the appropriate Thoughtly agent.
After a number is connected, incoming WhatsApp messages can be routed to the linked agent where supported.
## 24-hour customer-service window
WhatsApp allows businesses to send freeform replies within the customer-service window after a user messages the business. Outside that window, outbound messages generally need to use approved templates.
| Message type | When to use |
| ---------------- | -------------------------------------------------------- |
| Freeform message | Responding within the active customer-service window |
| Template message | Starting or re-opening a conversation outside the window |
## Automation actions
Depending on your workspace configuration, WhatsApp actions may include:
* **Start WhatsApp Conversation** — start or continue a conversation with a selected agent and WhatsApp number.
* **Send WhatsApp Message** — send a freeform message when allowed.
* **Send WhatsApp Template** — send an approved template with variables.
## Template variables
When sending a template, map Thoughtly variables into the template fields. For example:
```text theme={null}
Hi {{ contact.first_name }}, this is a reminder for your appointment on {{ appointment.date }}.
```
Use the data picker to insert fields from triggers, previous steps, contact attributes, or agent variables.
## Troubleshooting
### Message appears sent but later fails
WhatsApp and messaging providers may accept a request first and send a failure webhook later. Check the run logs, History, or message status to see the final delivery result.
### Template is rejected
Confirm the template is approved in WhatsApp Manager and that all required variables are provided.
### Contact does not receive freeform messages
The customer-service window may have expired. Use an approved template to re-open the conversation.
## See also
* [Omnichannel agents](/platform/omnichannel)
* [Consent and suppression](/platform/settings/audiences)
* [Automations actions](/automations/actions)
# Attio CRM integration
Source: https://docs.thoughtly.com/integrations/crm/attio
Sync contacts and call outcomes between Thoughtly and Attio so voice agents can log activity, update records, and trigger workflows from your CRM data.
# CRM sync
Source: https://docs.thoughtly.com/integrations/crm/crm-sync
Sync contacts and attributes inbound from your CRM into Thoughtly audiences so agents and automations work from current CRM data. Write outcomes back to your CRM using automation actions.
CRM sync connects Thoughtly with systems such as HubSpot and Salesforce so your agents can work from current CRM data. Sync pulls CRM records into Thoughtly so they are available in Audiences and workflows without manual imports or fragile one-off automations.
CRM sync capabilities can vary by CRM and workspace. If a sync option is not visible, contact support or your account team.
## What CRM sync does
CRM sync is an **inbound** sync: it pulls CRM records (contacts, deals, and their attributes) into Thoughtly, where they become contacts you can target in Audiences and use in automations and calls. The sync keeps Thoughtly attributes aligned with the source CRM on a recurring basis.
| Direction | What it does |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Inbound sync (CRM → Thoughtly) | Pulls CRM records into Thoughtly so contacts are available in Audiences and workflows. |
| Outbound updates (Thoughtly → CRM) | Handled by **automation actions** such as *Update Contact* or *Update Object*, not the sync itself. See [Automation actions](/automations/actions). |
## Common use cases
* Import leads from Salesforce or HubSpot into Thoughtly Audiences.
* Keep contact attributes aligned from the CRM into Thoughtly.
* Trigger outreach from CRM segments.
* Write call outcomes, qualification data, or appointment results back to CRM records using automation actions.
* Replace manual CSV uploads with a repeatable sync.
## Setup overview
1. Connect the CRM integration.
2. Choose the object or list you want to sync.
3. Configure field mapping.
4. Select sync criteria or filters.
5. Run a test sync.
6. Review synced contacts in [Audiences](/platform/audiences).
7. To write results back to the CRM, add the CRM's automation actions (for example, *Update Contact* or *Update Object*) to your workflows. See [Automation actions](/automations/actions).
## Field mapping
Map CRM fields to Thoughtly contact attributes. For example:
| CRM field | Thoughtly field |
| --------------- | ----------------- |
| First name | `first_name` |
| Phone | `phone` |
| Lead source | `lead_source` |
| Lifecycle stage | `lifecycle_stage` |
Use stable, descriptive attribute names so agents and automations can reference them later.
## Error handling
If sync fails:
* Confirm the CRM integration is still connected.
* Check that required fields are present.
* Verify field types match the expected format.
* Review CRM API limits or permission errors.
* Reconnect the integration if authentication has expired.
## Related integration notes
* [Salesforce](/integrations/crm/salesforce)
* [HubSpot](/integrations/crm/hubspot)
* [Audiences](/platform/audiences)
# GoHighLevel integration
Source: https://docs.thoughtly.com/integrations/crm/highlevel
Connect GoHighLevel to Thoughtly to trigger calls from sub-accounts, sync contacts and tags, and push call outcomes and recordings back to HighLevel pipelines.
***
## Working with Multiple Locations
GoHighLevel supports multiple sub-accounts (locations) within a single agency account. When connecting GoHighLevel to Thoughtly:
1. **Each location appears as a separate account** in your integrations list, labeled with the location name
2. **Select the correct location** when configuring actions in Automations or Agent Builder
3. **Use the search feature** to quickly find specific locations if you have many connected
When you connect a GoHighLevel location, Thoughtly automatically retrieves and displays the location name to help you identify the correct account.
## Troubleshooting
### Appointment Booking Issues
If you're experiencing issues with appointment search or booking:
* **Verify the correct location is selected** in the Account tab
* **Check that the location has active calendars** configured in GoHighLevel
* **Ensure the service/calendar permissions** are properly set in GoHighLevel
* **Test the connection** by retrieving available times before attempting to book
### Wrong Location Data
If you're seeing data from the wrong location:
* **Confirm you've selected the correct location** in the Account tab when setting up the action
* **Reconnect the location** if the issue persists
* **Check that the location hasn't been renamed** in GoHighLevel (you may need to reconnect)
## Reconnect stale connections
If a GoHighLevel action fails because the connected account is stale or expired, reconnect the integration from the Integrations page and rerun the workflow.
Common signs of a stale connection include authentication errors, missing account data, or actions that previously worked but now fail without configuration changes.
# HubSpot integration
Source: https://docs.thoughtly.com/integrations/crm/hubspot
Connect HubSpot to Thoughtly to trigger calls from workflows, sync contacts and properties, and push call outcomes and recordings back to HubSpot deals.
## Empty field filtering
When updating HubSpot records, Thoughtly avoids sending empty fields where supported. This helps prevent accidental overwrites with blank values.
Review field mappings carefully when using optional data from calls, forms, or webhook payloads.
# Keap CRM integration
Source: https://docs.thoughtly.com/integrations/crm/keap
Connect Keap to Thoughtly to trigger outbound calls from automations, sync contact records, and log call outcomes and recordings back to the Keap CRM.
# Pipedrive integration
Source: https://docs.thoughtly.com/integrations/crm/pipedrive
Connect Pipedrive to Thoughtly to trigger calls from pipeline stages, sync deals and contacts, and write call outcomes and activities back to Pipedrive.
# Salesforce integration
Source: https://docs.thoughtly.com/integrations/crm/salesforce
Connect Salesforce to Thoughtly to trigger calls from flows, sync leads and contacts, and write call outcomes, recordings, and activities back to Salesforce.
***
## Update Object record ID requirement
When using Salesforce **Update Object**, provide the Salesforce record `Id` for the object you want to update. The action uses this ID to update the existing record rather than creating or searching for one.
If you do not have the record ID yet, add a lookup or sync step earlier in the workflow and map the returned `Id` into the update action.
## API rate limits
Salesforce API limits can affect high-volume workflows. If an action fails because of rate limiting, reduce concurrency, batch updates where possible, or retry after the limit window resets.
# Salesforce Sandbox integration
Source: https://docs.thoughtly.com/integrations/crm/salesforce-sandbox
Connect a Salesforce sandbox to Thoughtly so you can safely test voice agent workflows, contact syncs, and outcome writebacks before promoting to production.
# Zoho CRM integration
Source: https://docs.thoughtly.com/integrations/crm/zoho
Connect Zoho CRM to Thoughtly to trigger calls from workflows, sync leads and contacts, and log call outcomes, notes, and activities back to Zoho records.
# Code
Source: https://docs.thoughtly.com/integrations/developer/code
Run sandboxed JavaScript inside Thoughtly automations for last-mile data transformation, custom API calls, and dynamic logic in agent and automation flows.
The Code integration lets advanced users run small JavaScript snippets inside automation flows or live agent actions. Use it for last-mile customization when built-in steps almost solve the workflow but you need to transform, validate, format, or calculate something first.
Examples:
* Normalize phone numbers before dialing.
* Convert a webhook response into fields an agent can use.
* Calculate a lead score.
* Choose a local-presence number based on area code.
* Route by date, time window, or custom business rules.
Code is not a general-purpose serverless environment. It runs in a restricted sandbox with time, memory, network, and security limits.
## How it works
A Code step receives prior node outputs through an `inputs` object. Your script returns a JSON-serializable value. That return value becomes the step output and can be mapped into later steps or agent actions.
```javascript theme={null}
const phone = inputs['trigger'].phone
const digits = phone.replace(/\D/g, '')
return {
e164: digits.startsWith('1') ? `+${digits}` : `+1${digits}`,
}
```
## Configuration
| Field | Required | Description |
| ------- | -------- | --------------------------------------------------------------------------------------- |
| Code | Yes | JavaScript to execute. Must return a JSON-serializable value. |
| Timeout | No | Maximum execution time. Shorter limits apply during live calls to protect call quality. |
## Use variables from prior steps
Use the data picker to insert references to previous outputs. References are inserted as `inputs['nodeId'].fieldName` paths.
Example:
```javascript theme={null}
const firstName = inputs['create_contact'].first_name
const appointmentDate = inputs['check_availability'].selected_time
return {
message: `Hi ${firstName}, your appointment is confirmed for ${appointmentDate}.`,
}
```
## Limits
Typical limits include:
| Limit | Why it exists |
| ------------------ | ------------------------------------------------------------ |
| Execution timeout | Prevents slow scripts from blocking workflows or live calls. |
| Memory cap | Protects platform stability. |
| Code size cap | Keeps snippets small and reviewable. |
| Console output cap | Prevents excessive logs. |
| Concurrency cap | Prevents one workspace from consuming all runner capacity. |
## Blocked capabilities
The sandbox blocks risky or platform-level operations, including:
* Network calls such as `fetch`, `XMLHttpRequest`, or `WebSocket`
* Node.js built-ins such as `require` or `process`
* Code generation such as `eval`, `new Function`, or dynamic `import()`
* Known sandbox escape patterns
* Obvious infinite loops
If your workflow needs external API access, use a webhook or integration step before or after the Code step.
## Examples
### Validate an email address
```javascript theme={null}
const email = inputs['trigger'].email
const valid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
return { email, valid }
```
### Calculate a lead score
```javascript theme={null}
const lead = inputs['create_or_update_contact']
const score =
(lead.budget >= 50000 ? 40 : 20) +
(lead.timeline === 'immediate' ? 30 : 10) +
(lead.company_size >= 100 ? 30 : 10)
return {
score,
qualified: score >= 70,
}
```
### Route by area code
```javascript theme={null}
const digits = inputs['trigger'].phone.replace(/\D/g, '')
const areaCode = digits.length === 11 ? digits.slice(1, 4) : digits.slice(0, 3)
const region = {
'212': 'new_york',
'646': 'new_york',
'415': 'san_francisco',
}[areaCode] || 'default'
return { areaCode, region }
```
## Best practices
* Keep scripts short and focused.
* Return structured JSON objects, not long strings.
* Use webhooks or CRM steps for external API calls.
* Test with realistic sample data before going live.
* Avoid putting secrets in code.
# MCP Server
Source: https://docs.thoughtly.com/integrations/developer/mcp
Connect AI assistants like Claude and ChatGPT to your Thoughtly conversation data with the Thoughtly MCP server. Query calls, SMS, and email transcripts using natural language through the Model Context Protocol.
The Thoughtly MCP server lets you connect your favorite AI tools, including Claude, ChatGPT, and Claude Code, directly to your Thoughtly data using the [Model Context Protocol](https://modelcontextprotocol.io) (MCP). Once connected, you can ask questions about your conversations in plain language: review call transcripts, search recent interactions, and summarize outcomes without opening the dashboard.
The MCP server is in **limited availability**. Contact your Thoughtly account team to request access. The server URL is provided when access is enabled for your team.
## What you can do
The MCP server exposes read-only tools for exploring your conversation history:
* **List your teams** with the `list_teams` tool, including your role on each team.
* **Search and filter conversations** with the `get_conversations` tool. Browse recent calls, SMS, and email interactions with contact info, status, duration, and a short summary. Filter by team, agent, conversation type, status, date range, or a free-text search.
* **Read full conversation details** with the `get_conversation` tool, including the complete transcript, contact information, metadata, and tags.
All tools are read-only. An AI client connected through MCP can view your data but can never modify agents, contacts, or settings.
## Connect your AI client
Setup takes about a minute and happens entirely in your MCP client. There is nothing to configure in the Thoughtly dashboard.
Request access from your Thoughtly account team. You will receive the MCP server URL once limited availability is enabled for you.
In your AI client's settings, add a new MCP server or connector using the provided URL. The Thoughtly MCP server uses streamable HTTP and works with Claude, ChatGPT, Claude Code, and other MCP-compatible clients.
The first time you connect, your client opens a browser window prompting you to sign in with your Thoughtly credentials. The server uses OAuth 2.1 with PKCE, so no API keys or tokens need to be copied or stored.
Once signed in, ask things like "Summarize my calls from last week" or "Show me the transcript of the most recent conversation with Jane."
## Working with multiple teams
If you belong to more than one team, conversation queries default to your primary team. To query a different team, ask the AI to list your teams first, then reference the team you want. The AI passes the appropriate `team_id` behind the scenes.
You can only access teams you belong to. Thoughtly platform admins can query across teams.
## Example prompts
* "What conversations did we have yesterday? Give me a one-line summary of each."
* "Find conversations with +1 555 numbers this month and list their outcomes."
* "Show me the full transcript of the latest call handled by my scheduling agent."
* "Which conversations this week were marked as failed, and what happened?"
## Permissions and security
* You sign in with your existing Thoughtly account over OAuth 2.1. No separate credentials are issued.
* You only see data for teams you are a member of, matching your dashboard access.
* Every tool is read-only. Nothing an AI client does through MCP can change your Thoughtly data.
* Access can be revoked by signing out of the connector in your AI client, or by contacting your account team.
## Troubleshooting
**"You do not have access to this team."** The conversation or team you referenced belongs to a team you are not a member of. Ask the AI to run `list_teams` and pick from the teams shown.
**The client keeps asking me to sign in.** OAuth sessions expire periodically for security. Sign in again when prompted; no data is lost.
**The server is not responding.** Confirm you are using the exact URL provided for limited availability, and that your client supports streamable HTTP transport. If problems persist, contact your account team.
# Shopify integration
Source: https://docs.thoughtly.com/integrations/e-commerce/shopify
Connect Shopify to Thoughtly so voice agents can look up orders, recover abandoned carts, confirm shipments, and update customer records during calls.
This integration is not yet available. Please check back soon for updates.
# Get started with Thoughtly integrations
Source: https://docs.thoughtly.com/integrations/getting-started
Connect Thoughtly to CRMs, scheduling tools, communication apps, and productivity platforms so your voice agents can read and write data across your stack.
**Prerequisites**: Have admin access to both Thoughtly and your target integration. Review [Agent Actions](/agents/actions) first.
Arm your agents with advanced automation capabilities to authenticate callers quickly and resolve customer service issues seamlessly. Thoughtly connects directly to your [CRM](/resources/glossary#crm), scheduling tools, SaaS platforms, and more, enabling your Voice Agent to act autonomously on your behalf.
After [building a Voice Agent](/agents/overview) using our drag-and-drop interface, you can connect it to your existing systems using either [Agent Actions](/agents/actions), our [API](/developers), or [Automations](/automations/getting-started)—no coding required.
## How Integrations Work
Thoughtly integrations work through three main methods:
1. **Agent Actions**: Add integration actions directly into your Voice Agent's conversation flow via [mid-call actions](/agents/actions)
2. **Automations**: Trigger actions before, during, or after calls using our automation builder
3. **API**: Use our REST API to build custom integrations for your specific needs
## Available Integration Categories
### CRMs
By connecting your CRM to Thoughtly, you can automate data entry, update customer records, and trigger workflows based on call outcomes. This allows your agents to focus on what they do best: providing exceptional customer service.
### Scheduling
By connecting your scheduling tool to Thoughtly, you can automate appointment booking, rescheduling, and cancellations. This allows your agents to focus on providing exceptional customer service, rather than managing calendars.
### Communication
By connecting your communication tools to Thoughtly, you can automate call logging, update customer records, and trigger workflows based on call outcomes. This allows your agents to focus on providing exceptional customer service, rather than managing data.
### Ticketing
By connecting your ticketing system to Thoughtly, you can automate ticket creation, updates, and resolution. This allows your agents to focus on providing exceptional customer service, rather than managing tickets.
### Productivity
By connecting your productivity tools to Thoughtly, you can automate data entry, update records, and trigger workflows based on call outcomes. This allows your agents to focus on providing exceptional customer service, rather than managing data.
### E-Commerce
By connecting your e-commerce platform to Thoughtly, you can automate order processing, update customer records, and trigger workflows based on call outcomes. This allows your agents to focus on providing exceptional customer service, rather than managing orders.
### AI
By connecting your AI platform to Thoughtly, you can automate data entry, update records, and trigger workflows based on call outcomes. This allows your agents to focus on providing exceptional customer service, rather than managing data.
### Automation Platforms
By connecting your automation platform to Thoughtly, you can automate data entry, update records, and trigger workflows based on call outcomes. This allows your agents to focus on providing exceptional customer service, rather than managing data.
## Prerequisites
Before starting integration setup:
* **Admin access** to both Thoughtly and the target integration platform
* **API credentials** or admin permissions for OAuth-based integrations
* **Clear use case** understanding for how the integration will be used
* **Testing plan** to verify integration functionality
## Universal Setup Process
All native integrations follow a similar setup pattern, though specific steps vary by vendor and authentication type.
```mermaid theme={null}
flowchart TD
Start([Start]) --> Step1[Step 1: Access Integrations]
Step1 --> Step2[Step 2: Initiate Integration]
Step2 --> Step3{Step 3: Choose Auth Type}
Step3 -->|OAuth| OAuth[Authorize via vendor consent screen]
Step3 -->|API Key| API[Enter API key from platform]
Step3 -->|Credentials| Cred[Enter username and password]
OAuth --> Step4[Step 4: Verify & Save]
API --> Step4
Cred --> Step4
Step4 --> End([Ready to Use])
classDef step1 fill:#6366f1,stroke:#4f46e5,color:#fff
classDef step2 fill:#8b5cf6,stroke:#7c3aed,color:#fff
classDef step3 fill:#ec4899,stroke:#db2777,color:#fff
classDef step4 fill:#10b981,stroke:#059669,color:#fff
class Step1 step1
class Step2 step2
class Step3,OAuth,API,Cred step3
class Step4 step4
```
## Post-Setup Configuration
### Making Integrations Available
After successful connection, integrations become available in:
**Automations Interface**:
1. Navigate to **Tools → Automations** in the primary navigation
2. Create or edit automation workflow
3. Add actions using connected integrations
4. Configure integration-specific parameters
5. Select which connected account to use (if you have multiple accounts for the same integration)
**Agent Builder Interface**:
1. Open Agent Builder for target agent
2. Open a [Speak node](/agents/nodes#speak-node) and navigate to the Actions section
3. Add integration [actions](/agents/actions) to your agent workflow
4. Configure real-time integration behavior
5. Select which connected account to use from the Account tab (if you have multiple accounts for the same integration)
### Integration Usage Patterns
Integrations work in two distinct contexts, each serving different use cases:
| Automation Workflows | Mid-call Actions |
| ---------------------------- | ----------------------------- |
| Post-call CRM updates | Real-time data lookup |
| Appointment scheduling | Live calendar checking |
| Team notifications | Instant team alerts |
| Lead qualification processes | Dynamic information retrieval |
## Testing and Validation
### Initial Connection Testing
1. **Verify** connection status remains "Connected"
2. **Test** basic functionality through simple automation
3. **Check** data flow between systems
4. **Confirm** permissions work as expected
## Multiple Accounts
You can connect multiple accounts for the same integration. This is useful when:
* Different team members need to use their own credentials
* You manage multiple client accounts
* You need separate production and testing environments
* You work with multiple sub-accounts (e.g., GoHighLevel locations)
When you have multiple accounts connected:
1. Each account appears as a separate connection in your integrations list with a descriptive label
2. You can select which account to use when configuring actions in Automations or Agent Builder
3. The account selector appears in the **Account** tab when setting up integration actions
4. For integrations with many accounts, use the search feature to quickly find the right one
The system automatically remembers your account selection for each automation node or agent action. If you don't select a specific account, the system will use the first available account for that integration.
## Common Setup Issues
### OAuth Connection Failures
**Symptoms**: Redirect errors, permission denied, or connection timeouts
**Solutions**:
* Verify admin permissions in target platform
* Check browser settings allow popups and redirects
* Clear browser cache and cookies
* Try different browser or incognito mode
### API Key Authentication Issues
**Symptoms**: Invalid key errors or connection refused
**Solutions**:
* Verify API key copied correctly (no extra spaces)
* Check API key permissions in source platform
* Ensure key hasn't expired or been revoked
* Confirm correct API endpoint if multiple environments
### Permission Scope Problems
**Symptoms**: Integration connects but specific features don't work
**Solutions**:
* Review granted permissions during OAuth flow
* Request additional scopes if needed
* Check platform-specific permission requirements
* Verify user roles in target system
## Troubleshooting
**Integration works in test but not production**
* Verify integration is connected (not in draft/test mode)
* Check that agent/automation is using the correct integration account (especially if you have multiple accounts)
* Review integration permissions for production vs test environments
* Test with [Call Me](/agents/testing#call-me-real-call) instead of Test Agent
**Wrong account being used**
* If you have multiple accounts for the same integration, verify you've selected the correct account in the Account tab
* Check that the selected account has the necessary permissions and data access
* Review which user email or location name is associated with each connected account
* For GoHighLevel, ensure you've selected the correct location/sub-account
**Data not syncing correctly**
* Verify field mappings are correct in integration configuration
* Check that required fields are populated in source data
* Review integration logs for error messages
* Ensure data formats match (dates, phone numbers, etc.)
* If using multiple accounts, confirm you're accessing data from the correct account
**Common Mistake**: Not refreshing OAuth tokens when they expire. Most OAuth integrations require periodic re-authentication. If an integration stops working after weeks/months, try reconnecting it.
For additional help with integrations:
* Check the [Integration Troubleshooting](/integrations/troubleshooting) guide
* Review vendor-specific documentation for your integration
* Contact [support](/support/getting-help) with your Team ID
## See also
* [Integration Webhooks](/integrations/webhooks) - custom integration patterns
* [Agent Actions](/agents/actions) - using integrations mid-call
* [Automation Steps](/automations/actions) - integration steps in workflows
* [Troubleshooting](/integrations/troubleshooting) - common integration issues
* [Glossary: OAuth](/resources/glossary#oauth) - understanding authentication
# Airtable integration
Source: https://docs.thoughtly.com/integrations/productivity/airtable
Connect Airtable to Thoughtly so voice agents can read and update base records mid-call, trigger automations from row changes, and log call outcomes to tables.
This integration is not yet available. Please check back soon for updates.
# Google Sheets integration
Source: https://docs.thoughtly.com/integrations/productivity/google-sheets
Connect Google Sheets to Thoughtly so voice agents can look up rows during calls, append outcomes, and trigger automations from new or updated sheet data.
# Smartsheet integration
Source: https://docs.thoughtly.com/integrations/productivity/smartsheet
Connect Smartsheet to Thoughtly so voice agents can read project rows, log call outcomes, and update statuses or assignments without leaving the call flow.
# Trello integration
Source: https://docs.thoughtly.com/integrations/productivity/trello
Connect Trello to Thoughtly so voice agents can create cards from call outcomes, move cards across lists, and trigger automations from board activity.
# Typeform integration
Source: https://docs.thoughtly.com/integrations/productivity/typeform
Trigger Thoughtly voice agents when a Typeform is submitted, pass responses as variables into the call flow, and log outcomes back to your records.
# Acuity Scheduling integration
Source: https://docs.thoughtly.com/integrations/scheduling/acuity
Connect Acuity Scheduling to Thoughtly so voice agents can check availability, book appointments, and reschedule or cancel meetings mid-call for your business.
# Acuity Scheduling Enterprise integration
Source: https://docs.thoughtly.com/integrations/scheduling/acuity-enterprise
Connect Acuity Scheduling Enterprise to Thoughtly so voice agents can book, reschedule, and cancel appointments across multi-location calendars during calls.
# Cal.com integration
Source: https://docs.thoughtly.com/integrations/scheduling/cal-com
Connect Cal.com to Thoughtly so voice agents can check team availability, book event types, and reschedule or cancel meetings without manual handoffs.
***
## Using variables with Cal.com actions
All Cal.com actions support [variables](/agents/variables) in their input fields. You can reference variables captured earlier in the conversation to dynamically populate booking details:
* **Attendee information** - Use variables like `{{email}}`, `{{name}}`, or `{{phone}}` for attendee details
* **Event details** - Reference `{{event_type_id}}` or `{{team_id}}` from earlier lookups
* **Scheduling** - Use `{{desired_time}}` or `{{timezone}}` captured from the caller
* **Node references** - Reference data from specific nodes using `Node #[step]: Answer` format
**Example:** If you capture the caller's email at node 3 and their preferred time at node 5, you can use `Node #3: Answer` for the attendee email and `Node #5: Answer` for the booking time in your Cal.com action.
Variables are automatically resolved when the action runs during the call. Make sure to extract and validate required fields (email, time, timezone) before triggering the booking action.
# Calendly integration
Source: https://docs.thoughtly.com/integrations/scheduling/calendly
Connect Calendly to Thoughtly so voice agents can check available times, book event types on a caller's behalf, and send confirmation links during the call.
***
## Timezone handling
The timezone field is optional for all Calendly actions. When not specified, the system uses the following fallback order:
1. **Timezone input** — If you provide a valid timezone in the action configuration
2. **Agent timezone** — The timezone configured in your agent's advanced settings
3. **Default timezone** — Falls back to `America/New_York` if no timezone is available
This allows you to use variables for timezone selection, letting callers choose their preferred timezone during the call. Available times are automatically formatted with the resolved timezone for accurate scheduling.
# Mindbody integration
Source: https://docs.thoughtly.com/integrations/scheduling/mindbody
Connect Mindbody to Thoughtly so voice agents can book classes and appointments, look up client memberships, and manage reservations for studios and salons.
# Zoho Bookings integration
Source: https://docs.thoughtly.com/integrations/scheduling/zoho-bookings
Connect Zoho Bookings to Thoughtly so voice agents can check staff availability, book service appointments, and reschedule or cancel meetings during calls.
# Zendesk integration
Source: https://docs.thoughtly.com/integrations/ticketing/zendesk
Connect Zendesk to Thoughtly so voice agents can create and update support tickets, look up customer history, and route conversations to the right queue.
# Troubleshoot Thoughtly integrations
Source: https://docs.thoughtly.com/integrations/troubleshooting
Diagnose and resolve common Thoughtly integration issues, including OAuth failures, missing data, mapping errors, and CRM sync problems across connected apps.
## Common Issues
### Authentication Errors
If you're experiencing authentication errors:
* Verify your API credentials are correct
* Check that the integration is properly authorized
* Ensure tokens haven't expired or been revoked
* If you suspect a compromised token, revoke it immediately through **Settings** → **Developers** in the dashboard
* Review the [Webhooks](/integrations/webhooks) documentation for proper setup
### Data Not Syncing
For data synchronization issues:
* Verify the integration is active and enabled
* Check that all required fields are mapped correctly
* Review automation trigger configurations
* Test the connection in your integration settings
### Webhook Failures
If webhooks aren't being received:
* Verify the webhook URL is correct
* Check that your server is accessible
* Review webhook authentication settings
* Test with the webhook debugger in the platform
### Integration Connections After Team Deletion
When a team is deleted, all associated integration connections are automatically cleaned up:
* Integration connections are removed from the system
* OAuth tokens and API credentials are revoked
* No manual cleanup is required
* This process happens automatically as part of team deletion
If you need to preserve integration data before deleting a team, export any necessary information first. Once a team is deleted, all integration connections are permanently removed.
For additional assistance, [contact support](/support/getting-help).
# Webhooks configuration
Source: https://docs.thoughtly.com/integrations/webhooks
Set up inbound and outbound webhooks in Thoughtly to trigger agents, push call events to external systems, and integrate any API without a prebuilt connector.
Set up custom webhooks to integrate Thoughtly with any external system that supports HTTP API calls, enabling flexible automation and data synchronization.
**New to Integrations?** Check out [Native Integrations](/integrations/getting-started) first for pre-built connections with popular platforms like HubSpot, Salesforce, and Calendly.
**Webhook Success Tips**
* **Start Simple**: Begin with basic webhook configurations before adding complexity
* **Test Thoroughly**: Validate both success and failure scenarios
* **Monitor Performance**: Track webhook response times and success rates
* **Plan for Scale**: Design endpoints to handle your expected call volume
* **Document Integration**: Maintain clear documentation for your webhook implementations
## Understanding Webhooks in Thoughtly
Unlike [native integrations](/integrations/getting-started), webhooks in Thoughtly are **not configured globally**. Instead, they are set up at the point of use within:
* **[Automations](/automations/getting-started)**: Use **Thoughtly -> On Call Completed** for post-call workflows, and add webhook steps when you need to push data to external systems
* **[Agent Builder](/agents/overview)**: Real-time webhooks for mid-call actions and live data updates
This architecture provides maximum flexibility for different use cases while maintaining clear separation between automation and real-time integration needs.
## Webhook Configuration Locations
### In Automations
In [automations](/automations/getting-started), webhooks are typically used in two ways:
1. **Send data out** as a step (for example, start with **Thoughtly -> On Call Completed**, then add a **Send Webhook** step to push call results to your CRM or database).
2. **Start an automation** from an external system using the **Webhook -> Incoming Webhook** trigger.
3. **Navigate** to **Tools → Automations** in the primary navigation
4. **Create or edit** an automation workflow
5. **Add webhook action** within the automation builder
6. **Configure** endpoint URL, headers, and payload
**Use Cases for Automation Webhooks**:
* Updating CRM records after call completion (see [native CRM integrations](/integrations/getting-started))
* Triggering follow-up emails or SMS campaigns
* Syncing call outcomes with business intelligence systems
* Creating tasks or tickets in project management tools
For post-call workflows, prefer **Thoughtly -> On Call Completed**. You can scope the trigger to **one agent, multiple agents, or All Agents**, and then optionally send results to external systems via a webhook step.
### In Agent Builder (Mid-call Actions)
Webhooks in the [Agent Builder](/agents/overview) enable real-time interactions during active phone calls:
1. **Open** Agent Builder for your target agent
2. **Navigate** to Mid-call [Actions](/agents/actions) section
3. **Add webhook action** within the agent's workflow
4. **Configure** real-time endpoint and response handling
**Use Cases for Mid-call Webhooks**:
* Looking up customer information during calls
* Updating external systems with live call data
* Triggering real-time notifications to support teams
* Retrieving dynamic pricing or inventory information
## Webhook Configuration Elements
### Essential Configuration
**Endpoint URL**: The target URL where Thoughtly will send HTTP requests
**HTTP Method**: Typically POST for data submission
**Headers**: Authentication tokens, content-type, and custom headers
**Payload**: JSON data structure sent to your endpoint
### Authentication Options
**API Key Authentication**:
```json theme={null}
Headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
```
**Custom Authentication**:
Configure custom headers and authentication schemes as required by your endpoint
### Payload Structure
Thoughtly sends structured JSON payloads containing:
* **Call Information**: Call ID, duration, participants, outcome
* **Agent Data**: Agent ID, agent name, [assigned phone number](/phone-number/getting-started)
* **Transcript**: Structured array of conversation turns (see below)
* **Custom Fields**: Any additional data configured in your [automation](/automations/getting-started) or [agent](/agents/overview)
**Transcript structure:** The transcript is provided as a structured array of objects, not a plain string. Each entry includes:
* `transcript` - The spoken content
* `speaker` - Either `"ai"` or `"user"`
* `createdAt` - ISO 8601 timestamp when the message was created
* `step` - (AI messages only) The step number in the conversation
* `node_id` - (AI messages only) The node ID from the agent builder
**Example transcript:**
```json theme={null}
[
{
"transcript": "Hello, how can I help you today?",
"speaker": "ai",
"createdAt": "2025-11-03T19:33:18.330Z",
"step": 1,
"node_id": "node_abc123"
},
{
"transcript": "I'd like to schedule an appointment",
"speaker": "user",
"createdAt": "2025-11-03T19:33:25.120Z"
}
]
```
## Webhook Development Guidelines
### Endpoint Requirements
**Response Time**: Design endpoints for quick responses (\< 5 seconds recommended)
**HTTP Status Codes**: Return appropriate status codes (200 for success, 4xx for client errors)
**Error Handling**: Implement proper error responses for debugging
### Security Best Practices
**Secure Your Webhooks**
* **HTTPS Only**: Always use HTTPS endpoints for secure data transmission
* **Authentication**: Implement proper API key or token-based authentication
* **Input Validation**: Validate all incoming webhook data before processing
### Payload Processing
**JSON Parsing**: Ensure robust JSON parsing with error handling
**Data Validation**: Verify required fields exist before processing
**Idempotency**: Design endpoints to handle duplicate webhook calls gracefully
## Testing and Validation
### Initial Setup Testing
1. **Configure** webhook with test endpoint
2. **Trigger** the automation or agent action
3. **Verify** payload delivery and format
4. **Confirm** your endpoint receives and processes data correctly
## Error Handling and Monitoring
### Monitoring Recommendations
**Logging**: Maintain logs of all webhook calls and responses
**Alerting**: Set up monitoring for webhook failures or slow responses
**Health Checks**: Regular endpoint availability testing
## Common Use Cases
### CRM Synchronization
**Automation Webhook**: Update customer records after each call
```json theme={null}
{
"call_id": "CALL_001",
"customer_phone": "+1555-012-1234",
"agent_id": "AGENT_001",
"call_outcome": "qualified_lead",
"duration_seconds": 180
}
```
### Real-time Data Retrieval
**Mid-call Webhook**: Fetch customer information during calls
```json theme={null}
{
"action": "customer_lookup",
"phone_number": "+1555-012-1234",
"agent_id": "AGENT_001",
"call_id": "CALL_001"
}
```
### Notification Systems
**Automation Webhook**: Alert teams about important call outcomes
```json theme={null}
{
"alert_type": "high_priority_lead",
"customer_data": {...},
"agent_notes": "Customer interested in enterprise package",
"follow_up_required": true
}
```
**Performance Considerations**
* **Latency Impact**: Mid-call webhooks can affect call quality if endpoints are slow
* **Concurrent Calls**: Ensure your endpoints can handle multiple simultaneous requests
* **Rate Limiting**: Consider implementing rate limiting for high-volume scenarios
## Expected Results
After successful webhook configuration:
**For Automations**:
* Webhooks trigger automatically after configured call events
* External systems receive structured call data
* Business processes update based on call outcomes
**For Mid-call Actions**:
* Real-time data exchange during active calls
* Dynamic agent responses based on external data
* Live updates to external systems during conversations
**Retry Behavior**
Thoughtly retries a webhook step once when the endpoint responds with `429 Too Many Requests`, waiting for the duration indicated by the `Retry-After` header before retrying. Other failures (network errors, `5xx`, authentication errors, etc.) are **not** automatically retried. Design your integration to handle:
* **Network Failures**: Temporary connection issues — not retried
* **Endpoint Downtime**: Service availability problems — not retried
* **Authentication Errors**: Token expiration or invalid credentials — not retried
* **Rate Limits (429)**: Retried once after the `Retry-After` delay
Make your endpoint idempotent so a rate-limit retry does not create duplicate side effects.
## Advanced: Triggering Automations with Webhooks
You can also trigger Thoughtly automations from external systems using webhook triggers. This allows you to start Voice Agent calls or run automations based on events in your other tools.
For more information, see:
* [Trigger Automation with Webhook](/api-reference/webhooks/trigger-automation-with-webhook)
* [Automation Triggers](/automations/triggers)
**Current Limitations**
* **Limited retries** — only `429` rate-limit responses are retried (once, after `Retry-After`); other failures are not retried automatically
* **No built-in webhook delivery logging** in Thoughtly interface
* **Configuration required per automation/agent** (no global webhook settings)
## See Also
* [Native Integrations](/integrations/getting-started) - Pre-built integrations with popular platforms
* [Automations Overview](/automations/getting-started) - Learn about automation workflows
* [Agent Actions](/agents/actions) - Configure mid-call actions in agents
* [Automation Actions](/automations/actions) - Available actions for automations
* [Automation Triggers](/automations/triggers) - Trigger automations with webhooks
## Rate-limit retries
If a webhook endpoint returns `429`, Thoughtly retries once after the `Retry-After` delay when supported. Keep `Retry-After` values reasonable and design your endpoint to be idempotent so a retry does not create duplicate side effects.
## Webhook-compatible automation triggers
The automation webhook endpoint only executes automations that have webhook-compatible triggers. This protects automations that are meant to run on schedules, calls, or other internal events from being triggered externally.
# Phone number billing and credits
Source: https://docs.thoughtly.com/phone-number/billing-credits
Understand the monthly costs, per-minute rates, and credit usage for buying, porting, or bringing your own phone numbers into Thoughtly across all countries.
Understanding how phone number billing works on Thoughtly is important for managing your usage and costs.
## Phone Number Costs
Phone numbers on Thoughtly are charged on a monthly basis. The cost varies depending on the country and type of number you purchase.
### Standard Phone Numbers
Most standard phone numbers in the United States cost approximately **500 credits per month** for AppSumo customers, or a comparable rate for other billing plans.
### International Phone Numbers
International phone numbers may have different pricing based on local regulations and carrier fees. You'll see the exact cost when selecting a number during the purchase process.
## Credit Consumption
For customers on AppSumo plans or credit-based billing, here's how phone numbers consume credits:
* **Phone Numbers**: 500 credits/month (US numbers)
* **Carrier Fees**: 200 credits per dollar of fees incurred
Want to reduce your phone number costs? You can use the [Bring Your Own Carrier (BYOC)](/phone-number/byoc) feature to connect your own telephony provider and avoid carrier fees.
## Managing Phone Number Costs
Here are some tips for managing your phone number costs:
1. **Release unused numbers**: If you're no longer using a phone number, release it to avoid ongoing monthly charges.
2. **Use call forwarding**: Instead of purchasing multiple numbers, consider forwarding existing numbers to Thoughtly using our [BYOC (Bring Your Own Carrier)](/phone-number/byoc) feature.
3. **Monitor your usage**: Regularly check your billing dashboard to track phone number costs and overall credit consumption.
## Viewing Your Bill
To view your phone number costs and overall billing information:
1. Navigate to [Settings → Usage](/platform/settings/usage) to see a breakdown of your phone number costs
2. View your subscription and payment details in [Settings → Subscription](/platform/settings/subscription)
For detailed information about Thoughtly's billing system, visit our [Platform Billing](/platform/billing) documentation.
Only Flex and Enterprise customers can purchase phone numbers from dashboard.
## Support
If you have questions about phone number billing or need help managing costs, contact our Support team at [support@thoughtly.com](mailto:support@thoughtly.com).
# Branded calling for outbound numbers
Source: https://docs.thoughtly.com/phone-number/branded-calling
Display your verified business name on supported outbound calls from Thoughtly to improve answer rates and reduce spam labeling on US carriers.
Branded calling helps recipients recognize your business when you place outbound calls through Thoughtly. When supported by the recipient's carrier and device, the call can display your company name or branded identity instead of an unknown number.
Use branded calling to improve trust, reduce spam-risk perception, and increase answer rates for legitimate outbound workflows.
## What recipients may see
Depending on carrier support and approval status, recipients may see:
* Your business name
* A verified caller label
* Additional branded caller information where supported
Carrier support can vary across networks and devices.
## When to use branded calling
Branded calling is most useful for:
* Speed-to-lead sales follow-up
* Appointment confirmations
* Customer support callbacks
* Reference checks
* High-volume outbound campaigns
* Any workflow where answer rate and trust matter
## Setup overview
Branded calling usually requires approval and carrier-side activation.
1. Confirm which phone numbers you want to brand.
2. Provide the business identity and any required verification details.
3. Submit the request through your Thoughtly account team or supported setup flow.
4. Wait for carrier approval and activation.
5. Place test calls across carriers when possible.
Activation timelines vary by carrier. Some carriers may update quickly, while others can take longer to approve and display branded information.
## Limitations
* Branded calling is carrier-dependent.
* Display behavior can vary by device, call app, and recipient carrier.
* Branded calling does not guarantee the recipient will answer.
* Branded calling is separate from [call screening bypass](/agents/call-screening-bypass).
## Best practices
* Use accurate business names that recipients will recognize.
* Pair branded calling with truthful agent introductions.
* Keep outbound campaigns compliant with your consent and suppression policies.
* Monitor answer rates and outcomes in [History](/platform/history) and Analytics.
# Bring Your Own Carrier (BYOC)
Source: https://docs.thoughtly.com/phone-number/byoc
Import phone numbers from your Twilio, Telnyx, or other SIP carrier into Thoughtly to keep existing providers, rates, and compliance while running voice agents.
**Prerequisites**: Active Thoughtly workspace with credits. For importing: Twilio or Telnyx account with numbers. Review [Phone Number Management](/phone-number/getting-started) first.
Acquire phone numbers for your Thoughtly agents through **Bring Your Own Carrier (BYOC)**. Purchase numbers directly through Thoughtly or import existing numbers from your [Twilio](/resources/glossary#twilio) or [Telnyx](/resources/glossary#telnyx) carrier accounts.
## Purchasing Numbers
**Unlimited Plan Feature**: For teams on the Unlimited plan with the `flex_phone_self-serve` feature flag enabled, you can purchase numbers directly from Thoughtly's Telnyx number pool without adding carrier credentials.
### Purchase from Thoughtly Number Pool (Unlimited Plan)
For teams on the Unlimited plan, purchasing numbers is streamlined through a modal interface:
#### Step 1: Access Purchase Modal
1. Navigate to **Settings → Phone Numbers** in the platform navigation
2. Click **Add a Number** in the top right corner
3. Select **Purchase from our number pool** from the dialog
#### Step 2: Configure Search Criteria
1. **Select Country**: Choose your target country from the dropdown
2. **Enter Area Code** (optional): Specify a prefix like "312" for Chicago
3. **Select Phone Number Types**: Choose one or more types:
* **Local**: Area code-specific numbers for regional presence
* **Mobile**: Mobile-style numbers
* **Toll-free**: Free-to-call numbers for customer service
#### Step 3: Search and Review Results
1. Click **Search** to view available numbers
2. Review the search results table showing:
* **Phone Number**: The number with its type icon (phone, mobile, or grid)
* **Features**: Available capabilities (call, SMS, voicemail)
* **Cost**: Monthly cost per number
3. Use the **Refresh** button to load new inventory if needed
#### Step 4: Select and Purchase
1. **Select numbers** by checking the boxes next to your preferred options
2. **Configure webhook settings**: Toggle "Allow Webhook & Messaging Updates" if you want immediate inbound call and messaging capabilities
3. Click **Buy now** to complete the purchase
**Expected Result**: Purchased numbers appear in your phone numbers table with a "Pending" status. The system processes orders asynchronously. You can manually sync order status using the **Process** button in the table, or wait for automatic processing.
Numbers purchased from the pool are processed asynchronously. They will show as "Pending" until the order completes successfully. Check back or use the Process button to manually sync the status.
### Purchase via Marketplace (Standard Flow)
For teams not on the Unlimited plan or without the feature flag:
#### Step 1: Access Number Marketplace
1. Navigate to **Settings → Phone Numbers** in the platform navigation
2. Click **Add a Number** in the top right corner
3. Select **Import your Telnyx or Twilio number**
4. You'll see the number marketplace table with available inventory
#### Step 2: Select Region
1. Click the **Country** button in the top left corner
2. Choose your target country (e.g., United States)
3. Select the desired **Area Code** (e.g., 228 for Mississippi)
The system loads available numbers for your selected region. If you don't see suitable options, click the **Refresh** button to load additional inventory from the database.
#### Step 3: Evaluate Number Features
Before purchasing, review each number's capabilities in the table:
| Column | Description |
| ---------------- | -------------------------------------- |
| **Phone Number** | The actual number you'll acquire |
| **Region** | Closest region as specified by carrier |
| **Type** | National, Local, Mobile, or Toll-free |
| **Features** | Voice, SMS, and MMS capabilities |
| **Monthly Cost** | Recurring cost in credits |
#### Step 4: Complete Purchase
1. Click **Buy** in the Actions column for your chosen number
2. Review the confirmation modal carefully
3. **Important**: Credits are deducted immediately upon confirmation
4. No proration applies—you're billed for the full month even if cancelled within minutes
**Expected Result**: The purchased number appears in your main phone numbers table and is ready for agent assignment.
## Importing Existing Numbers
### Supported Carriers
Thoughtly currently supports importing numbers from:
* **Twilio**
* **Telnyx**
### Prerequisites for Import
Before starting the import process:
1. **Purchase numbers** in your carrier dashboard (Twilio or Telnyx)
2. Ensure numbers are **active and configured** in your carrier account
3. Have your **API credentials** ready for authentication
### Step 1: Access Import Feature
1. Go to **Settings → Phone Numbers**, then click **Add a Number**
2. Select **Import your Telnyx or Twilio number** from the dialog
3. Select your carrier (Twilio or Telnyx) from the form
### Step 2: Configure Integration
1. **Name** your integration for easy identification
2. **Enter credentials** for your third-party carrier account
3. **Validate connection** to ensure successful authentication
4. **Select numbers** from the dropdown list of available numbers
#### Telnyx-Specific Configuration
For Telnyx numbers, you must also provide your **Connection ID**:
1. Log into your Telnyx dashboard
2. Navigate to **Voice** → **TeXML Applications**
3. Create a new TeXML application or select an existing one
4. Copy the **Connection ID** from the application details
5. Enter this Connection ID when configuring your Telnyx integration in Thoughtly
The Connection ID is required for Telnyx TeXML to properly route calls and handle recordings. Without it, your imported Telnyx numbers will not function correctly.
### Step 3: Configure Webhook Settings
**Critical Decision**: Choose your webhook configuration carefully:
**Outbound Only Toggle (Default)**
* Prevents changes to existing webhook and messaging settings
* Preserves current carrier configurations
* Use this if the number serves other purposes outside Thoughtly
**Allow Webhook and Messaging Updates (Advanced)**
* Thoughtly takes full control of the number
* Existing carrier settings are reconfigured for Thoughtly use only
* Any previous inbound/SMS integrations will be disabled
#### Telnyx Webhook Configuration
When importing Telnyx numbers with webhook updates enabled, ensure your TeXML application webhook URL is set to:
```
https://api.thoughtly.com/webhook/telnyx/texml
```
This endpoint properly handles:
* Inbound call routing
* Call recordings
* Call status updates
### Step 4: Complete Import
1. Select multiple numbers if needed—all appear in the phone numbers field
2. Choose appropriate profile settings
3. Confirm the import
**Expected Result**: Imported numbers appear in your Thoughtly phone numbers table with "Imported" carrier designation.
## Disconnecting BYOC Carriers
You can disconnect your Twilio or Telnyx carrier integration at any time from the BYOC interface.
### How to Disconnect
1. Navigate to **Settings → Phone Numbers**
2. Click **Import Your Number** in the top right corner
3. Locate the connected carrier tile (Twilio or Telnyx)
4. Click the **X button** in the top-right corner of the carrier tile
5. Review the confirmation modal showing how many phone numbers will be affected
6. Click **Disconnect** to confirm
**Important**: Disconnecting a BYOC carrier will permanently delete all phone numbers that were imported through that connection. This action cannot be undone. Make sure you no longer need these numbers before proceeding.
### What Happens When You Disconnect
* All phone numbers imported through the carrier connection are removed from Thoughtly
* The carrier integration credentials are deleted
* Any agents using the disconnected numbers will no longer be able to receive or make calls with those numbers
* The numbers remain in your carrier account (Twilio/Telnyx) but are no longer connected to Thoughtly
### After Disconnecting
If you need to reconnect the same carrier:
1. Follow the standard [import process](#importing-existing-numbers) again
2. Re-enter your API credentials
3. Select which numbers to import
4. Reconfigure webhook settings as needed
## Regional Configuration
### Twilio Numbers Only
For both purchased and imported Twilio numbers, you can configure regions to optimize call quality:
1. **Edit** the phone number after acquisition
2. **Set Region** to the location closest to your calling destinations
3. This minimizes latency between Thoughtly servers and call recipients
**Best Practice**: Always select the region geographically closest to where your agents will be making the majority of their calls.
## Billing and Credits
### Purchase Pricing
* Numbers are billed in **credits** (specific amounts vary by number type and region)
* **No proration**: Full monthly charge applies regardless of cancellation timing
* Credits deduct from your monthly allowance immediately upon purchase
### Import Pricing
* **No additional Thoughtly charges** for imported numbers
* You continue paying your carrier (Twilio/Telnyx) directly
* Thoughtly only facilitates the connection and management
## Troubleshooting
**No numbers appear after region selection**
* Try different area codes within your target region
* Use the Refresh button to load new inventory
* Consider adjacent regions if specific area codes are unavailable
* Contact [support](/support/getting-help) if area code is consistently unavailable
**Purchase fails or credits not deducted**
* Verify sufficient credits in [Billing](/platform/billing) dashboard
* Check that number is still available (may have been purchased by another user)
* Try a different number from the same area code
* Clear browser cache and retry
**Numbers stuck in "Pending" status (Unlimited Plan)**
* Wait a few minutes for automatic order processing
* Click the **Process** button in the phone numbers table to manually sync order status
* Check that your team has valid Telnyx connection credentials configured
* Contact [support](/support/getting-help) if orders remain pending after 10 minutes
**Import connection fails**
* Verify API credentials in your carrier dashboard
* Ensure account has active API access enabled
* Check that numbers are purchased and active in carrier account
* Test API credentials in carrier's dashboard first
* For Telnyx: Verify Connection ID is correct and from a TeXML application
**Webhook configuration concerns**
* Use "Outbound Only" if preserving existing integrations
* Test thoroughly after import to confirm expected behavior
* Contact support with Team ID and affected numbers if issues arise
* Document existing webhook URLs before importing
* For Telnyx: Ensure webhook URL points to `/webhook/telnyx/texml` endpoint
**Imported number not working**
* Verify number is assigned to agent in [Configuration](/phone-number/configuration)
* Check that webhook settings updated correctly (if not using Outbound Only)
* Test with a simple call to confirm connectivity
* Review carrier dashboard for any error messages
* For Telnyx: Confirm Connection ID is properly configured in your TeXML application
**Carrier disconnection fails**
* Ensure you have a stable internet connection
* Try refreshing the page and attempting again
* If the issue persists, contact [support](/support/getting-help) with your Team ID
* Note: The carrier will remain connected until successfully disconnected
**Telnyx recordings not working**
* Verify your TeXML application webhook URL is set to `https://api.thoughtly.com/webhook/telnyx/texml`
* Check that the Connection ID matches your TeXML application
* Ensure recording settings are enabled in your Telnyx dashboard
* Test with a call that should trigger a recording
**Common Mistake**: Forgetting that purchased numbers are billed immediately for the full month with no proration. If you purchase a number and release it the same day, you still pay for the entire month. Plan your number needs before purchasing.
## Call Forwarding (Alternative Method)
### What is Call Forwarding?
Call forwarding is a telephony feature that redirects incoming calls from your existing phone number to another destination number. Instead of importing or purchasing a new number through Thoughtly, you keep your current phone number with your existing carrier and configure it to automatically route all incoming calls to a Thoughtly number connected to your Voice Agent.
**How it works:**
1. A caller dials your existing business phone number (e.g., your advertised number)
2. Your carrier immediately forwards the call to your Thoughtly phone number
3. Your Thoughtly Voice Agent answers and handles the conversation
4. The caller never knows they were forwarded—it's transparent to them
### When to Use Call Forwarding
Call forwarding is ideal when:
* You want to keep your existing, well-known phone number
* You don't want to update marketing materials, business cards, or online listings
* You need a quick way to test Thoughtly without changing your phone infrastructure
* Your carrier doesn't support number porting or BYOC import
### How to Set Up Call Forwarding
Call forwarding setup varies by carrier and phone system. Each provider has different methods, codes, and admin interfaces.
**To configure call forwarding:**
1. **Get your Thoughtly destination number** - Purchase or import a number through Thoughtly and assign it to your Voice Agent
2. **Contact your carrier** - Reach out to your phone service provider (Verizon, AT\&T, T-Mobile, RingCentral, etc.)
3. **Request call forwarding setup** - Ask them to forward all calls from your existing number to your Thoughtly number
4. **Test the forwarding** - Call your original number to verify calls route to your Voice Agent
Some carriers allow you to enable call forwarding via dial codes (e.g., `*72` followed by the destination number), while others require logging into an admin portal or contacting support. Your carrier's customer service team can provide specific instructions for your account type.
### Important Considerations
* **Billing**: You may incur call forwarding charges from your carrier in addition to Thoughtly usage fees
* **Latency**: Call forwarding can add slight delays as the call routes through multiple systems
* **Features**: Some advanced features may not transfer perfectly through forwarding
* **No porting**: Your number remains with your original carrier—you're not transferring ownership
If you plan to use Thoughtly long-term and want full control over your phone number, consider importing it via BYOC instead of relying on call forwarding.
## See also
* [Phone Number Configuration](/phone-number/configuration) - assigning numbers to agents
* [Phone Number Management](/phone-number/getting-started) - overview and capabilities
* [Billing & Credits](/phone-number/billing-credits) - understanding costs
* [Agent Settings](/agents/settings) - connecting numbers to agents
* [Platform Settings](/platform/settings/general) - BYOC carrier configuration
* [Glossary: Carrier](/resources/glossary#carrier) - understanding phone providers
# Phone number configuration and assignment
Source: https://docs.thoughtly.com/phone-number/configuration
Assign Thoughtly phone numbers to voice agents, configure inbound routing, fallback handling, caller ID, and regional settings for inbound and outbound traffic.
**Prerequisites**: At least one acquired phone number and one configured agent.
Configure phone number assignments to agents and optimize regional settings for the best call quality and functionality.
## Agent Assignment
### Assignment Overview
Each voice agent can be assigned up to **three separate phone numbers**:
* **Inbound Profile**: Receives incoming calls for this agent
* **Outbound Profile**: Makes outgoing calls from this agent
* **SMS Profile**: Sends and receives SMS messages for this agent
### Assignment Rules
**Exclusivity**: Once a phone number is assigned to an agent profile, it becomes unavailable for other usage:
* One number cannot be inbound for multiple agents
* Same restriction applies to outbound and SMS profiles
* Numbers can serve different profiles for the same agent
### Step-by-Step Assignment
1. **Navigate** to **Settings → Phone Numbers** in the platform navigation
2. **Locate** the number you want to assign in the table
3. **Hover** over the pencil icon in the Actions column
4. **Click Edit** when the option appears
### Assignment Modal
The edit modal provides three assignment dropdowns:
#### Inbound Profile
* Select which agent will receive incoming calls to this number
* Only one agent can be assigned per number
* Leave blank if number won't receive inbound calls
#### Outbound Profile
* Choose which agent will use this number for outbound calls
* Supports one agent assignment per number
* Leave blank for inbound-only numbers
* **Allow Outbound Calls** toggle controls whether this number can make outbound calls
* When disabled, the number is restricted from making outbound calls
* Automation editor will display warnings when selecting agents with restricted numbers in select or multi-select inputs on outbound nodes
* Warnings appear dynamically based on the selected option's `outbound_enabled` property from the integration payload
* Useful for compliance or cost control purposes
#### SMS Profile
* Assign which agent will handle SMS messaging for this number
* One agent per number for SMS capabilities
* Required for agents that need text messaging functionality
### Outbound Calling Control
When an agent is assigned to the outbound profile, you can enable or disable outbound calling for that phone number:
**Enable/Disable Toggle**:
* Located in the outbound profile section of the edit modal
* When **enabled** (default): Agent can make outbound calls using this number
* When **disabled**: All outbound call attempts are blocked with a clear error message
**Use Cases**:
* **Incident Response**: Immediately stop outbound calls during spam attacks or security incidents
* **Operational Control**: Temporarily disable outbound calling while keeping inbound calls functional
* **Testing**: Prevent accidental outbound calls during agent development
**Important Notes**:
* Disabling outbound calling does **not** affect inbound calls or SMS functionality
* Outbound calls initiated via API, automations, or UI will all be blocked when disabled
* The toggle automatically resets to enabled when the outbound agent assignment is removed
When outbound calling is disabled, any attempt to make an outbound call (via API, automation, or manual trigger) will fail with the error: "Outbound calling is disabled for this phone number."
### Expected Results
After saving assignments:
* Numbers display associated agent names in the main table
* Agents can now use assigned numbers according to their profiles
* Phone number becomes unavailable for reassignment to other agents in the same profile
* Outbound calling status is enforced across all call initiation methods
## Regional Configuration
**Region settings are only visible for supported numbers.** If you don't see the region dropdown when editing a phone number, it means that number doesn't support regional configuration (e.g., non-Twilio numbers or certain number types).
### Supported Numbers
Regional settings are available **only for Twilio numbers**, including:
* Numbers purchased directly through Thoughtly (using Twilio)
* Numbers imported from your own Twilio account
### Why Regional Settings Matter
Proper regional configuration:
* **Minimizes latency** between Thoughtly servers and call destinations
* **Improves call quality** and connection reliability
* **Reduces connection delays** during call establishment
### Setting Regions
1. **Edit** the phone number using the pencil icon
2. **Locate** the "Set Region" dropdown in the modal
3. **Select** the region closest to where your agent will make calls
#### Regional Selection Guidelines
**For US-based calling**: Choose US regions (US East, US West, etc.)
**For International calling**: Select the region geographically closest to your primary call destinations
**For Mixed calling patterns**: Choose based on the majority of your call volume
## Incident Response
### Stopping Outbound Calls During Emergencies
If you need to immediately stop outbound calling due to a security incident, spam attack, or other emergency:
1. **Navigate** to **Settings → Phone Numbers** in the platform navigation
2. **Locate** the affected phone number
3. **Click Edit** on the phone number
4. **Scroll** to the Outbound Profile section
5. **Toggle** "Outbound Calls" to disabled
6. **Save** changes
**What happens when outbound calling is disabled:**
* All outbound call attempts are immediately blocked
* Calls initiated via API, automations, or UI will fail with error: "Outbound calling is disabled for this phone number"
* Inbound calls and SMS continue to function normally
* The automation editor will display warnings when selecting agents with disabled outbound calling in select or multi-select inputs on outbound nodes
* Warnings appear dynamically based on the selected option's `outbound_enabled` property from the integration payload
**Common scenarios:**
* **Spam attack on public form**: Disable outbound calling to stop automated call floods while investigating
* **Compromised API key**: Disable outbound calling while rotating credentials
* **Testing and development**: Prevent accidental outbound calls during agent development
This feature allows you to maintain inbound call functionality while stopping all outbound activity, providing granular control during incident response.
## Configuration Best Practices
### Agent Profile Strategy
**Dedicated Numbers Approach**:
* Assign separate numbers for inbound, outbound, and SMS
* Provides clear separation of communication channels
* Easier to track and analyze performance per channel
**Unified Number Approach**:
* Use one number for multiple profiles on the same agent
* Simplifies customer experience with single contact point
* May require careful call routing consideration
### Regional Optimization
**High-Volume Operations**: Always configure regions for optimal performance
**Testing Phase**: Use default regional settings initially, optimize based on call quality feedback
**International Service**: Research latency patterns to your target countries
## Managing Multiple Assignments
### Viewing Current Assignments
The main phone numbers table displays:
* Which agent is assigned to each number
* Current regional settings (for Twilio numbers)
* Assignment status across all profiles
### Reassigning Numbers
To change agent assignments:
1. **Edit** the existing assignment
2. **Clear** current agent selection from dropdown
3. **Select** new agent for the desired profile
4. **Save** changes
**Important**: Reassignment immediately affects call routing and SMS delivery.
## Troubleshooting
**Agent not receiving calls on assigned number**
* Verify inbound profile assignment is saved correctly
* Check that agent is active and properly configured
* Confirm number capabilities include Voice functionality
**Outbound calls failing with "disabled" error**
* Check if outbound calling toggle is enabled in the phone number settings
* Verify the outbound profile is assigned to an agent
* Confirm the agent has an outbound phone number configured
* Review automation editor for warnings about disabled outbound calling in select or multi-select inputs on outbound nodes
* Warnings appear dynamically when selected options have `outbound_enabled` set to `false` in the integration payload
**Poor call quality or connection issues**
* Review regional settings for Twilio numbers
* Select region closer to call destinations
* Test with different regions if issues persist
**SMS not working for assigned agent**
* Verify SMS profile is assigned to correct agent
* Confirm number capabilities include SMS functionality
* Check that agent has SMS features enabled
**Assignment modal not saving changes**
* Ensure you have proper permissions for number management
* Verify agent exists and is active in workspace
* Contact support with Team ID and affected phone number if issues persist
## Expected Results
After proper configuration:
* **Inbound calls** route correctly to assigned agents
* **Outbound calls** originate from assigned numbers
* **SMS messages** send and receive through assigned agents
* **Call quality** is optimized for your geographic usage
* **Agent assignments** are clearly visible in the phone numbers table
## SMS profile assignment
Phone numbers can be assigned to agents for SMS messaging where supported. Assign an SMS profile when you want inbound or outbound text conversations to route through a specific agent.
## Outbound calling control
If outbound calling is disabled for a number, calls from that number are blocked across UI, API, and automation entry points. Use this for testing, incident response, or operational control while leaving inbound calls or SMS available where supported.
## Regional ring timeout
Thoughtly may automatically adjust ring timeout by destination region to account for network differences. For example, calls to some regions may receive a longer connection window than standard domestic calls. No configuration is required when this behavior is applied automatically.
# Get started with phone numbers
Source: https://docs.thoughtly.com/phone-number/getting-started
Buy, port, or bring your own phone numbers in Thoughtly and assign them to voice agents for inbound or outbound calling across US and international regions.
**Prerequisites**: Complete [Agent Builder Overview](/agents/overview) first.
Acquire, manage, and assign phone numbers to your voice agents for inbound calls, outbound calls, and SMS messaging.
## Overview
The phone number management system displays all your acquired numbers in a centralized table, showing key information like carrier details, capabilities, and current assignments. From here, you can purchase new numbers, import existing ones from supported carriers, or configure number assignments for your agents.
### Supported Capabilities
Each phone number displays its available features:
* **Voice**: Supports inbound and outbound voice calls
* **SMS**: Can send and receive SMS messages
* **MMS**: Can send and receive multimedia messages
### Number Types
Available phone numbers include:
* **Local**: Area code-specific numbers for regional presence
* **National**: Country-wide numbers
* **Mobile**: Mobile-style numbers
* **Toll-free**: Free-to-call numbers for customer service
## Quick Start
1. **Navigate** to **Settings → Phone Numbers** in the platform navigation
2. **View** your current phone number inventory
* If you have no phone numbers, the system will automatically check for numbers from connected external providers
* Once the check completes, you'll see an empty state with an option to add your first number
3. **Add numbers** by purchasing from Thoughtly's pool (Unlimited plan) or importing from existing carriers
4. **Assign** numbers to agents for specific profiles (inbound, outbound, SMS)
5. **Configure** regional settings for optimal performance
## Key Concepts
### Agent Profiles
Each agent can be assigned up to three phone numbers:
* **Inbound profile**: For receiving incoming calls
* **Outbound profile**: For making outgoing calls
* **SMS profile**: For text messaging campaigns
### Regional Assignment
For Twilio numbers, you can select regions to minimize latency between servers and call destinations. Choose the region closest to where your agents will be making calls.
### Number Assignment Rules
* One phone number cannot serve as inbound for multiple agents
* Same restriction applies to outbound and SMS profiles
* Once assigned to an agent profile, numbers become unavailable for other usage
## Message History
The Messages tab provides a historical log of all SMS and MMS activity across your phone numbers. This view-only interface displays:
* **Date and time** of each message
* **To/From** phone numbers
* **Message content** sent or received by agents
This is purely for visibility and historical tracking—you cannot respond to messages directly from this interface.
## Troubleshooting
**Phone number not receiving calls**
* Verify number is assigned to an agent's inbound profile
* Check that agent is published (not in draft mode)
* Confirm number has Voice capability enabled
* Test by calling from a different phone
**Outbound calls not working**
* Verify number is assigned to agent's outbound profile
* Check that agent has outbound configuration set up
* Confirm number has Voice capability enabled
* **Verify "Allow Outbound Calls" is enabled** for the phone number in the edit modal
* Review [BYOC](/phone-number/byoc) for imported number setup
**SMS not sending or receiving**
* Verify number is assigned to agent's SMS profile
* Check that number has SMS/MMS capability
* Ensure [Send SMS action](/automations/actions#messaging-and-inbound) is configured in your automations
* Confirm carrier supports SMS for this number type
**Can't purchase number in desired area code**
* Try adjacent area codes in the same region
* Use the Refresh button to load new inventory
* For Unlimited plan users: Try different phone number type combinations in the search
* Consider [importing](/phone-number/byoc) from Twilio/Telnyx
* Contact [support](/support/getting-help) for bulk number needs
**Number shows "Pending" status after purchase**
* Wait a few minutes for automatic order processing (Unlimited plan purchases)
* Click the **Process** button to manually sync order status
* Verify your team has valid Telnyx connection credentials
* Contact [support](/support/getting-help) if status doesn't update after 10 minutes
**Common Mistake**: Assigning the same number to multiple agent inbound profiles. Each number can only route to ONE agent for inbound calls. Use [Transfer nodes](/agents/nodes#transfer-node) if you need routing logic.
## See also
* [Bring Your Own Carrier (BYOC)](/phone-number/byoc) - acquiring phone numbers
* [Configuration](/phone-number/configuration) - assigning numbers to agents
* [Billing & Credits](/phone-number/billing-credits) - understanding costs
* [Send SMS Action](/automations/actions#messaging-and-inbound) - text messaging in automations
* [Glossary: Carrier](/resources/glossary#carrier) - understanding telephony providers
# Troubleshoot phone numbers
Source: https://docs.thoughtly.com/phone-number/troubleshooting
Diagnose and resolve common Thoughtly phone number issues including porting delays, inbound routing failures, spam labeling, and regional verification problems.
## Common Issues
### Unable to Purchase Phone Number
If you're unable to purchase a phone number, please check the following:
* Ensure you have sufficient credits in your account
* Verify that the desired area code is available in your region
* Check that your account is verified and in good standing
If the issue persists, [contact support](/support/getting-help) for assistance.
### Call Quality Issues
For call quality problems:
* Check your internet connection stability
* Verify that the phone number is properly configured
* Review the [Phone Number Configuration](/phone-number/configuration) guide
### Number Porting Issues
If you're experiencing issues with bringing your own number:
* Ensure all documentation is correctly submitted
* Verify the number is eligible for porting
* Review our [BYOC (Bring Your Own Carrier)](/phone-number/byoc) guide
For additional assistance, visit our [Support Center](/support/getting-help).
# Analytics in Thoughtly
Source: https://docs.thoughtly.com/platform/analytics
Monitor voice agent performance, call volumes, and credit usage across your Thoughtly workspace with built-in dashboards and time-frame filters.
The Analytics page gives you a high-level view of workspace activity, usage, and performance trends. Use it to understand how agents are being used and where to investigate deeper in History.
## What you can review
* **Responses** — total agent responses across the selected time period.
* **Talk Time** — total minutes of conversation time.
* **Deployments** — active deployed agents or channels.
* **Usage by type** — credit consumption broken down by call, SMS, preview, training, and other activity types.
* **Top states and area codes** — geographic distribution of calls by region.
## Measuring success
A completed call is not always a successful outcome. Pair Analytics with [History](/platform/history), outcomes, tags, and exported data to measure the business result that matters for your workflow.
# Audiences and contact management
Source: https://docs.thoughtly.com/platform/audiences
Manage contacts, build segments, and connect CRM data inside Thoughtly so voice agents and automations can target the right people for outbound campaigns.
Audiences is your central hub for managing contacts. Access it from the **Audiences** tab in the primary navigation.
## What you'll find
* **Audiences Table** — a searchable, filterable list of all contacts in your workspace.
## Coming soon
We're actively building out the full Audiences experience, including:
* **Contact Detail** views (Overview, Timeline, Memories)
* **Settings → Audiences** controls (Attributes, Consent, Suppression List)
## See also
* [History](/platform/history) — view all interactions across all agents
* [Settings → Audiences](/platform/settings/audiences) — audience settings and upcoming controls
* [Automations](/automations/getting-started) — trigger workflows based on call outcomes
## Segments, filters, and contact detail
Audiences supports search, filters, and saved segments so you can work with the right group of contacts.
You can filter by attributes such as name, email, phone, tags, dates, custom fields, and engagement data. Save frequently used filters as segments for quick access.
## Contact timeline
The contact detail view can show a timeline of activity across channels, including calls, messages, replies, and other interaction events. Use the timeline to understand the contact journey before launching another outreach step.
# Billing on Thoughtly
Source: https://docs.thoughtly.com/platform/billing
Understand how Thoughtly billing works — credits, plan limits, per-minute rates, phone number fees, and how invoices and overage charges are calculated.
## Introduction
Thoughtly offers flexible plans designed to meet a variety of organizational needs. All plan selection and onboarding are managed directly by our sales team to make sure you get the best fit for your use case.
## Free Plan
You can get started with Thoughtly using our **limited free plan**. This plan lets you test agents and explore essential features with usage restrictions, making it ideal for evaluation and initial testing.
## Paid Plans
To access advanced features, higher usage limits, and the full capabilities of the platform, you can upgrade to one of our **paid plans**. Paid plans are tailored for different business requirements and are available exclusively through direct consultation with our sales team.
If you’re interested in upgrading or want to learn more about paid options, please [schedule a demo](https://thought.ly/demo). During the demo, our team will discuss your needs and guide you through the available plans.
## Billing
Billing is managed through [Settings → Subscription](/platform/settings/subscription). After you activate a plan, you'll have access to detailed usage data in [Settings → Usage](/platform/settings/usage). This allows you to monitor your usage and manage your subscription with confidence. Your account manager will provide all necessary information on subscription terms, payment, renewals, and usage reports.
Billing on Thoughtly is designed to match how modern revenue teams operate. Most customers begin with a quick discovery call to help tailor the right plan for their needs. From there, you'll get access to a fully managed subscription with clear pay-as-you-go pricing, invoicing, and access to all platform features.
## Free Trial Access
When you sign up for Thoughtly, you'll begin on a **14-day free trial**. This trial gives you a chance to explore the platform and see how it fits your team's needs before committing to a paid plan.
During your trial, you'll have full access to build and test Voice Agents using our editor—but some features are restricted:
* ✅ You can build and customize agents
* ✅ You can call yourself (or other teammates you invite) to test agents
* ❌ You **cannot** place outbound calls to leads or external numbers
* ❌ You **cannot** use features like Automations, Audiences, or Bulk Calling
After 14 days, your account will be **automatically deleted** to keep our systems clean. To avoid losing your work, make sure to [book a demo](https://thought.ly/demo) before the trial ends. Our team will help you choose a plan and preserve your progress.
## How to Get Started
To get started with Thoughtly, simply [book a call](https://thought.ly/demo) with our team. An Account Executive will walk you through the right plan based on your goals, volume, and technical requirements.
Once you're set up, you can manage your billing and view past invoices in [Settings → Subscription](/platform/settings/subscription).
## AppSumo Customers
If you purchased Thoughtly via **AppSumo**, you're on a special lifetime deal plan with a different billing model.
When you navigate to [Settings → Billing](/platform/settings/subscription), you'll see **"You are on a special AppSumo plan"** with details about your monthly credit allocation. You can manage your AppSumo purchase directly through your [AppSumo account](https://appsumo.com/account/products/).
AppSumo plans use **Credits**—a virtual currency that recharges monthly and can be used to pay for usage across the platform, including Voice Agents, phone numbers, and SMS. You can view your balance and usage in [Settings → Usage](/platform/settings/usage) or from the credit balance shown in the [User Menu](/platform/user-menu).
Please note that AppSumo credits are non-transferrable.
### Credit Consumption (AppSumo Plans Only)
Below are sample Credit rates for common features when using your AppSumo plan. These rates are subject to change:
* **[Voice Agents](/agents/overview)**: 10 credits/min
* **[Phone Numbers](/phone-number/getting-started)**: 500 credits/month
* **[Automations](/automations/getting-started)**: 1 credit/step
* **[Test Agent Chat](/agents/testing)**: 3 credits/message
* **[SMS Messages](/automations/actions#messaging-and-inbound)**: 8 credits/message
* **Carrier Fees**: 200 credits per dollar of fees incurred
Want to stretch your credits further? Connect your own carrier using our [BYOC](/phone-number/byoc#bring-your-own-carrier-byoc) feature, and you won't be charged Credits for Carrier Fees. It's a great way to maximize value.
Credits do not roll over month-to-month, and additional Credits can be purchased from [Settings → Subscription](/platform/settings/subscription).
### AppSumo Credit Pricing Over Time
We're proud to support our AppSumo community—and we know our platform is a bit different from many tools you may find on AppSumo.
Most AppSumo deals are for one-time purchases of lightweight software: think screenshot tools, note apps, or calendar plugins. These tools often have low or no usage-based costs behind the scenes.
Thoughtly, on the other hand, runs on live, high-performance AI infrastructure—real-time voice, speech-to-text, language models, and telephony providers—all of which come with significant ongoing costs every time you use the platform.
To keep things running smoothly (and sustainably), we may adjust Credit rates over time to reflect the cost of these services. When that happens, we'll always give you advance notice and do our best to keep changes minimal and justified.
We're on your side: we'll continue offering ways to reduce your credit usage—like plugging in your own API keys or carrier—so you get the most out of your plan.
And most importantly: we're constantly adding more features, automation options, and integrations to make your Credits go even further. You're not just getting a static tool—you're getting a growing enterprise-grade platform.
## Flex and Enterprise billing
Flex and Enterprise plans may be managed through your account team or a dedicated billing portal. If your workspace uses managed billing, the billing page may route you to the appropriate portal for invoices or payment details instead of showing self-serve cancellation controls.
## AppSumo billing
AppSumo workspaces show an AppSumo or lifetime-plan status with the included credit allocation where applicable. Manage the original purchase through your AppSumo account.
## Trial expiration and granted credits
If your workspace has granted credits, trial and credit-expiration behavior may differ from standard self-serve trials. Review the subscription page or contact support if your trial state does not match the credit balance you expect.
# Call and conversation history
Source: https://docs.thoughtly.com/platform/history
View, filter, and search every voice call and conversation handled by your Thoughtly agents, with transcripts, recordings, outcomes, and per-call analytics.
History is the global log of all interactions across all of your agents. Access it from the **History** tab in the primary navigation.
## What you'll find
History provides a single, filterable view of every call, message, and interaction handled by your agents. Use it to:
* Review call recordings and transcripts
* Monitor agent performance across your entire workspace
* Filter by agent, date range, outcome, or other criteria
* Drill into individual interactions for full detail
## Filtering by agent
When you click the **Responses** tab inside the Agent Builder, you are redirected to History with a filter pre-applied for that specific agent. This lets you quickly see all interactions for a single agent without leaving your workflow.
You can also manually filter History by agent at any time using the filter controls at the top of the page.
## History vs. Timeline
History and the contact Timeline serve different purposes:
| View | Question it answers | Where to find it |
| ---------------------------- | ------------------------------------------ | ------------------------------------- |
| **History** | "What happened across my business?" | Primary navigation → History |
| **Timeline** *(coming soon)* | "What happened with this specific person?" | Audiences → Contact Detail → Timeline |
## See also
* [Audiences](/platform/audiences) — manage contacts in the Audiences table
* [Agent Builder](/agents/overview) — build and configure agents
* [Automations](/automations/getting-started) — trigger workflows based on call outcomes
## Call statuses
History uses statuses to distinguish what happened to each interaction.
| Status | Meaning |
| -------------- | ------------------------------------------------------------ |
| Completed | The interaction finished normally. |
| In Progress | The interaction is currently active. |
| Not Started | The interaction was queued but has not connected. |
| Failed | The interaction encountered an error. |
| Suppressed | The interaction was blocked by consent or suppression rules. |
| No Answer | The call was placed but not answered. |
| Left Voicemail | The agent reached voicemail and left a message. |
| Transferred | The call transferred to a human or external number. |
| Busy | The recipient line was busy. |
| Canceled | The interaction was canceled before connection. |
A completed call is not always a successful business outcome. Use outcomes, tags, variables, and analytics to measure what matters for your workflow.
## Filtering and search
Use filters to find calls and messages by agent, status, call type, date, tags, phone number, summary, or other available fields. Multiple filters narrow the result set.
## Export history
Use **Export** to download filtered History results for reporting or review.
1. Apply the filters you want.
2. Click **Export**.
3. Confirm if exporting a large result set.
4. Wait for the export to finish.
5. Download the CSV or use the emailed export link where available.
For large exports, Thoughtly may show progress and deliver the file by email when complete.
# Omnichannel agents
Source: https://docs.thoughtly.com/platform/omnichannel
Use one Thoughtly agent across voice, SMS, WhatsApp, iMessage (via Linq), email, webhooks, and automations with a shared contact, variable, and outcome model.
Thoughtly is built around one agent model that can operate across multiple customer communication channels. Voice calls, SMS, WhatsApp, iMessage, email, CRM sync, webhooks, and automations all share the same core concepts: contacts, agents, variables, actions, history, and outcomes.
Use omnichannel agents when you want Thoughtly to continue the customer journey instead of stopping at a single call or message.
## What omnichannel means in Thoughtly
An omnichannel workflow usually combines:
* **Agents** — the conversation logic, prompts, nodes, variables, and actions.
* **Channels** — voice, SMS, WhatsApp, email, iMessage, or another connected channel.
* **Automations** — triggers and steps that start conversations, send follow-ups, update CRMs, or route data.
* **Audiences** — the contacts, attributes, consent state, and channel reachability signals that inform each interaction.
* **History and analytics** — the record of what happened, where it happened, and whether it achieved the intended business outcome.
A channel changes how an agent should communicate. A voice prompt like “Hi, is this Brian?” may be natural on a call but awkward in email or SMS. Review prompts and messages for the channel where they will be used.
## Common workflows
### Lead follow-up across call and SMS
1. A new lead enters your CRM or form system.
2. An automation starts an outbound call with the right Thoughtly agent.
3. If the contact does not answer, the automation sends an SMS follow-up.
4. If the contact replies, the agent continues the conversation by text with the same contact context.
5. The result is written back to your CRM or exported from History.
### Appointment scheduling
1. A contact asks to book time.
2. The agent checks availability or receives availability from a previous automation step.
3. The agent books through a scheduling integration such as Cal.com, Calendly, or Zoho Bookings.
4. A confirmation message is sent over the best channel for the contact.
### Support or operations triage
1. A customer contacts your business by phone, SMS, WhatsApp, or email.
2. The agent collects the issue, checks available context, and routes the request.
3. If needed, the agent transfers the call, sends a follow-up, updates contact attributes, or triggers an external workflow.
## Channel capabilities
| Channel | Best for | Notes |
| ------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Voice | Live qualification, support, scheduling, transfers, urgent follow-up | Use call screening bypass and branded calling where available to improve pickup and trust. |
| SMS | Fast follow-ups, reminders, lightweight two-way conversations | Respect opt-out/opt-in behavior and suppression settings. |
| WhatsApp | International or mobile-first conversations | Outbound messages may require approved templates outside the customer-service window. |
| iMessage (via Linq) | Messaging conversations on supported numbers | Messaging-only numbers do not support inbound or outbound voice calls. |
| Email | Longer-form replies, confirmations, operational follow-up | Use email-specific prompts, domain verification, and reply routing. |
| Webhooks/API | Custom systems and partner workflows | Use scoped API tokens, retries, and clear error handling. |
## Design guidance
* **Start with the outcome.** Define what success means: booking created, lead qualified, transfer completed, payment collected, issue resolved, or another business event.
* **Use the right channel for the moment.** Voice is best for urgency and live qualification. SMS and WhatsApp are good for quick replies. Email is better for longer context and written confirmation.
* **Keep compliance close.** Configure consent mode, suppression lists, opt-out handling, and quiet hours before scaling outbound workflows.
* **Make variables channel-aware.** Use `channel_type` and other variables to branch copy, timing, and routing by channel.
* **Measure success directly.** A completed call is not always a successful call. Use outcomes, variables, tags, exports, and analytics to track the result that matters.
## See also
* [Agents overview](/agents/overview)
* [Automations](/automations/getting-started)
* [SMS and phone number configuration](/phone-number/configuration)
* [WhatsApp Business](/integrations/communication/whatsapp-business)
* [Email domains](/platform/settings/email-domains)
* [Consent and suppression](/platform/settings/audiences)
* [History](/platform/history)
# Platform overview
Source: https://docs.thoughtly.com/platform/overview
Tour the Thoughtly platform — agents, automations, audiences, history, analytics, integrations, and settings — and how each area fits together for voice AI.
The Thoughtly platform is organized into five primary sections, accessible from the left-hand navigation.
## Primary navigation
| Section | URL | Description |
| ------------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
| **Home** | `/` | Performance analytics dashboard with key metrics and geographic activity visualization. |
| **Agent** | `/agent` | Create, manage, and deploy AI agents. The Agents List is the default view; clicking an agent opens the Agent Builder. |
| **Audiences** | `/audience` | Manage contacts in the Audiences table. Additional CRM views and controls are in progress. |
| **History** | `/history` | Global, filterable log of all interactions across all agents. |
| **Tools** | — | Utilities that enhance agent capabilities. Reveals a hover menu with links to Genius, Automations, and Integrations. |
## Tools
The Tools menu does not have its own landing page. Hover over it to access:
* **[Genius](/genius/getting-started)** — create and manage knowledge bases that agents can reference
* **[Automations](/automations/getting-started)** — configure workflows triggered by agent interactions
* **[Integrations](/integrations/getting-started)** — connect Thoughtly to external services
## Other navigation elements
* **[Settings](/platform/settings/general)** — accessed via the gear icon. Workspace-level configuration for general settings, audiences, phone numbers, voices, usage, subscription, developer tools, and audit log.
* **[Workspace Switcher](/platform/workspace-switcher)** — click the workspace icon (top-left) to switch between workspaces or create a new one.
* **[User Menu](/platform/user-menu)** — click your avatar to access profile preferences, credit balance, and quick links.
## See also
* [Quick Start Guide](/getting-started/quick-start) — build your first agent in 15 minutes
* [Agent Builder](/agents/overview) — design and deploy voice agents
* [Audiences](/platform/audiences) — manage your contacts
* [History](/platform/history) — review all interactions
# Audiences settings
Source: https://docs.thoughtly.com/platform/settings/audiences
Configure workspace-wide audience controls in Thoughtly — default contact fields, opt-out rules, deduplication, and segment defaults used across automations.
The **Settings → Audiences** page is where you'll manage advanced audience controls for your workspace. Today, the core Audiences experience is the **contact table** in [Audiences](/platform/audiences).
## Coming soon
The following controls are on the way:
* **Attributes** — reusable custom fields for contact records
* **Consent** — workspace-level opt-out policy (universal vs granular)
* **Suppression List** — management of opted-out contacts
## See also
* [Audiences](/platform/audiences) — manage your contacts
* [Settings → General](/platform/settings/general) — workspace-level settings
## Consent mode
Consent mode controls how Thoughtly enforces opt-outs across channels.
| Mode | Behavior |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Universal | If a contact is suppressed on any channel, outbound communication is blocked across all channels. |
| Granular | Suppression is enforced per channel. A contact suppressed for SMS may still be reachable by voice or email if allowed by your policy. |
Choose the mode that matches your compliance policy and customer expectations.
## Suppression list
The suppression list records contacts who should not receive outbound communication on one or more channels.
Suppression entries can be created:
* Automatically, such as when a contact sends an opt-out keyword.
* Manually, when an admin adds a phone number or email address.
Suppression entries include the identifier, channel, reason, source, and timestamp where available.
## Opt-out and opt-in keywords
For SMS and similar messaging channels, contacts may opt out with standard keywords such as:
* STOP
* UNSUBSCRIBE
* CANCEL
* END
* QUIT
If opt-in is supported for the channel, a contact may be able to resume communication with an opt-in keyword such as START. Carrier and provider behavior can vary by channel.
## Suppressed history records
When an outbound call or message is blocked by suppression, it appears in History or run logs with a suppressed status where supported. This helps distinguish compliance-blocked outreach from technical failures.
# Audit log
Source: https://docs.thoughtly.com/platform/settings/audit-log
Review a chronological audit log of changes made in your Thoughtly workspace — who edited which agent, automation, or setting, and when each change happened.
View a history of all changes made in your workspace. Navigate to **Settings → Audit Log** or visit `/settings/audit-log`.
| Element | Type | Description |
| ------------------- | ---------- | -------------------------------------------------- |
| **Search / Filter** | Text input | Filter log entries by member, action, or resource. |
| **Audit Log Table** | Table | Columns: Member, Action, Resource, Timestamp. |
The audit log records actions by all workspace members, including agent changes, settings updates, member additions/removals, and other administrative activity.
## See also
* [Settings → General](/platform/settings/general) — manage workspace members
* [Workspaces](/platform/teams/overview) — workspace membership overview
# Dark windows and quiet hours
Source: https://docs.thoughtly.com/platform/settings/dark-windows
Configure dark windows in Thoughtly to block outbound voice, SMS, email, and WhatsApp during per-channel quiet hours, with optional contact-level timezone awareness.
Dark windows define quiet hours when Thoughtly should not send outbound communications on selected channels. Use them to avoid contacting people too early, too late, or during channel-specific blackout periods.
## Channels
Dark windows can apply to supported outbound channels:
* Voice
* SMS
* Email
* WhatsApp
## Configure a dark window
1. Go to **Settings → Campaigns → Dark Windows** or the equivalent workspace setting.
2. Choose the channel.
3. Enable quiet hours for that channel.
4. Set the start and end time.
5. Save changes.
## Time zones
Dark windows are usually evaluated against your workspace timezone unless contact-level timezone behavior is enabled. If you contact people across multiple regions, confirm which timezone your workspace uses before scaling outbound workflows.
## Best practices
* Align quiet hours with your compliance and customer-experience policies.
* Use stricter windows for SMS and WhatsApp than for email when appropriate.
* Pair dark windows with [consent and suppression](/platform/settings/audiences).
# Developer settings
Source: https://docs.thoughtly.com/platform/settings/developer
Manage Thoughtly API tokens, webhook subscriptions, and experimental beta features from a single developer settings page for your workspace.
Access developer tools and credentials for your workspace. Navigate to **Settings → Developer** or visit `/settings/developer`.
| Element | Type | Description |
| ------------------------- | -------------- | ---------------------------------------------------------------------- |
| **API Tokens** | Table & Button | View generated API tokens and create new ones with "Generate Token". |
| **Webhooks** | Table & Button | View configured webhooks and add new ones with "Create a Webhook". |
| **User ID** | Read-only text | Your unique user identifier. |
| **Team ID** | Read-only text | Your workspace's unique identifier. Used in API requests as `team_id`. |
| **Experimental Features** | Toggles | Enable or disable experimental features for your workspace. |
## See also
* [Developer Documentation](/developers) — integrate Thoughtly with your applications
* [Webhooks](/integrations/webhooks) — configure webhook integrations
* [API Reference](/api-reference) — complete endpoint documentation
## Admin-only developer settings
Developer settings contain sensitive workspace capabilities such as API tokens, webhooks, IDs, and experimental options. These settings are intended for admins.
## API tokens
Use scoped API tokens when available. Prefer the minimum scopes required for the integration and set expiration dates for partner or temporary access.
Older tokens may have broader access for backward compatibility. Rotate broad or unnamed tokens when you migrate to scoped API access.
# Email domains
Source: https://docs.thoughtly.com/platform/settings/email-domains
Add and verify custom email sending domains in Thoughtly so voice agents and automations can send branded follow-ups and route inbound replies into agent flows.
Email domains let your workspace send and receive email through addresses connected to Thoughtly agents. Use them for confirmations, follow-ups, longer-form customer replies, and omnichannel workflows that should continue outside voice or SMS.
## Add a domain
1. Go to **Settings → Email**.
2. Click **Add Domain**.
3. Enter the domain you want to send from, such as `example.com`.
4. Add the required DNS records at your DNS provider.
5. Return to Thoughtly and click **Verify DNS**.
## DNS provider tips
Thoughtly shows records in the format expected by common DNS providers.
| Provider | Tip |
| ---------- | -------------------------------------------------------------------------------------------------------------- |
| Cloudflare | Set email-related MX and CNAME records to **DNS only**. Do not proxy them. |
| Namecheap | Use **Custom MX** for MX records. Enter only the host prefix when Namecheap appends your domain automatically. |
| GoDaddy | Use `@` for the root domain and only the prefix for subdomains when GoDaddy appends your domain. |
| Route 53 | Use fully qualified record names with a trailing dot where required. |
| Other | Use the full record name and value shown in Thoughtly. |
DNS verification can take time. Some records appear within minutes, while others may take longer because of DNS propagation and provider caching.
## Domain statuses
| Status | Meaning |
| --------- | ----------------------------------------------------------------- |
| Pending | DNS records have not been verified yet or are still propagating. |
| Verifying | Thoughtly is checking the DNS records. |
| Active | The domain is verified and ready to send. |
| Failed | Verification failed. Review the error, update DNS, and try again. |
## Create email addresses
After a domain is verified, create one or more email addresses and link them to agents.
Examples:
* `sales@example.com` → inbound sales qualification agent
* `support@example.com` → support triage agent
* `appointments@example.com` → scheduling agent
## Global vs agent email settings
Workspaces can define global email behavior, while individual agents may override settings for specific workflows. Use agent-level settings when an agent needs unique reply behavior, sender identity, or channel-specific instructions.
## Reply routing
Incoming replies are routed based on the connected email address and conversation context. When an address is linked to an agent, replies can continue through that agent instead of starting a disconnected thread.
## Email prompts
Write email prompts for email. Do not reuse voice scripts without editing.
Good email instruction:
```text theme={null}
Write a concise email reply that answers the customer's question, includes the booking link if they want to schedule, and signs off as the Acme Support team.
```
Poor email instruction:
```text theme={null}
Say: Hi, is this Brian?
```
## Troubleshooting
### DNS records stay pending
* Confirm the provider-specific formatting is correct.
* Check for extra spaces or duplicated domain names.
* Make sure Cloudflare records are not proxied.
* Wait for propagation, then try verification again.
### Replies are not reaching the agent
* Confirm the email address is linked to the correct agent.
* Check that the domain is active.
* Verify the reply was sent to a connected address.
### Verification failed
Read the error message, update the DNS records, and click **Verify DNS** again. Failed domains return to a retryable state so you can fix configuration without creating a new domain.
# General workspace settings
Source: https://docs.thoughtly.com/platform/settings/general
Manage your Thoughtly workspace name, icon, default time zone, language, and regional preferences — settings that apply across every agent and member.
Settings are accessed via the gear icon in the navigation. The URL is `/settings` — there is no separate personal or workspace settings split. Only users with admin permissions can access Settings. Non-admin users who try to open Settings directly will see a permissions error toast.
Personal profile settings (name, avatar, phone number) are managed via the [Profile Modal](/platform/user-menu#profile-modal) in the User Menu, not in Settings.
## Workspace settings
| Field | Type | Description |
| ------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Workspace Logo** | Image upload | A visual identifier for the workspace, displayed in the [Workspace Switcher](/platform/workspace-switcher). Upload an image to represent your workspace. |
| **Workspace Name** | Text input | The name of the workspace, displayed throughout the app. Must be at least 3 characters. |
| **Company Website** | Text input | Your organization's website URL. |
| **Timezone** | Dropdown | Set the timezone for your workspace to ensure accurate scheduling and timestamps. |
## Member management
Invite and manage the people who have access to your workspace.
| Field | Type | Description |
| ----------------- | -------------------- | ------------------------------------------------------------------------------------------------ |
| **Invite Member** | Email input & button | Enter an email address and send an invitation to join the workspace. |
| **Members Table** | Table | Lists all current workspace members with columns: Name, Email, Role (dropdown), Status, Actions. |
For more on member permissions and removal, see [Workspaces](/platform/teams/overview).
## Danger Zone
| Field | Type | Description |
| ------------------- | ------ | ------------------------------------------------------------------ |
| **Leave Workspace** | Button | Remove yourself from this workspace. This action cannot be undone. |
Leaving a workspace is permanent. You will need to be re-invited to regain access.
## Settings sections
Settings contains the following subsections, each accessible from the left sidebar within Settings:
| Section | Description |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **[General](/platform/settings/general)** | Workspace name, icon, member management, and delete workspace. |
| **[Audiences](/platform/settings/audiences)** | Audience settings controls (attributes, consent, suppression) are currently a work in progress. |
| **[Phone Numbers](/platform/settings/phone-numbers)** | Manage and buy phone numbers for your workspace. |
| **[Voices](/platform/settings/voices)** | Manage and clone voices. |
| **[Usage](/platform/settings/usage)** | Monitor credit consumption by type and agent. |
| **[Subscription](/platform/settings/subscription)** | Manage your plan, billing cycle, and credits. |
| **[Developer](/platform/settings/developer)** | API tokens, webhooks, user/team IDs, and experimental features. |
| **[Audit Log](/platform/settings/audit-log)** | Track all changes made in your workspace. |
## Bring Your Own Carrier (BYOC)
For details on importing numbers from Twilio, Telnyx, or other carriers, see the dedicated [BYOC documentation](/phone-number/byoc).
## Beta features
Beta features give your workspace early access to new capabilities before they are generally available.
Beta features may be less stable than production features. Use beta for evaluation, QA, and feedback rather than mission-critical production workflows unless your account team advises otherwise.
When beta is enabled, your workspace may be redirected to a beta environment. Check the app URL and feature labels during demos or customer-facing work so you know whether you are viewing beta or production behavior.
## Team invitations
When you invite a new workspace member, they receive an email invitation. New users may be asked to set a password before joining. Existing users can use the invitation link to access the workspace.
If an invitation fails, confirm the email address is valid, there is no duplicate pending invite, and your workspace has available seats.
# Phone numbers settings
Source: https://docs.thoughtly.com/platform/settings/phone-numbers
Buy, port, assign, and configure the phone numbers attached to your Thoughtly workspace from one settings page covering routing, caller ID, and verification.
Manage all phone numbers associated with your workspace. Navigate to **Settings → Phone Numbers** or visit `/settings/phone-numbers`.
## Manage Numbers
View and configure all phone numbers in your workspace.
| Element | Type | Description |
| ----------------- | ------ | ------------------------------------------------------------------- |
| **Add a Number** | Button | Add a pre-existing number to your workspace. |
| **Numbers Table** | Table | Columns: Phone Number, Inbound Agent, Outbound Agent, SMS, Actions. |
## Buy a Number
Purchase new phone numbers directly from Thoughtly.
| Element | Type | Description |
| --------------------- | ------------- | --------------------------------------------------- |
| **Country Selector** | Dropdown | Select the country to search for available numbers. |
| **Search by** | Radio buttons | Search by Area Code or Contains. |
| **Search Field** | Text input | The search query. |
| **Available Numbers** | Table | Matching results with a "Buy" button for each. |
## Messages
Configure messaging services for SMS campaigns.
| Element | Type | Description |
| ---------------------- | ----- | ------------------------------------------------ |
| **Messaging Services** | Table | Configured messaging services for SMS campaigns. |
## See also
* [Phone Numbers — Getting Started](/phone-number/getting-started) — detailed guide to purchasing and configuring numbers
* [BYOC](/phone-number/byoc) — bring your own carrier
# Subscription and plan
Source: https://docs.thoughtly.com/platform/settings/subscription
Manage your Thoughtly subscription — change plans, view current billing cycle, top up credits, update payment methods, and download invoices from one place.
Manage your subscription and purchase additional credits. Navigate to **Settings → Subscription** or visit `/settings/subscription`.
| Element | Type | Description |
| --------------------- | -------------- | --------------------------------------------------------------- |
| **Plan Selector** | Radio buttons | Choose your subscription tier (Free, Basic, Pro, Business). |
| **Billing Cycle** | Toggle | Switch between Monthly or Annual billing. |
| **Credit Top-up** | Slider / Input | Purchase additional credits beyond your plan's included amount. |
| **Payment Method** | Form | Credit card information for billing. |
| **Checkout / Update** | Button | Finalize subscription changes. |
## See also
* [Billing](/platform/billing) — understand plans, pricing, and credit consumption
* [Usage](/platform/settings/usage) — monitor credit consumption
# Usage and credit consumption
Source: https://docs.thoughtly.com/platform/settings/usage
Monitor Thoughtly credit consumption, minute usage, phone number costs, and integration activity over time across your workspace with filterable usage reports.
Track how your workspace uses credits and resources. Navigate to **Settings → Usage** or visit `/settings/usage`.
| Element | Type | Description |
| ----------------------- | ----------- | ------------------------------------------------------------------ |
| **Monthly Usage Chart** | Chart | Time-series chart of credit usage over the current billing period. |
| **Usage by Type** | Donut chart | Breakdown by category (Phone Calls, SMS, Training). |
| **Usage by Agent** | Table | Credit consumption per agent. |
| **Export** | Button | Exports usage data to CSV. |
## See also
* [Subscription](/platform/settings/subscription) — manage your plan and purchase credits
* [Billing](/platform/billing) — understand plans and pricing
# Voices settings
Source: https://docs.thoughtly.com/platform/settings/voices
Manage workspace voices in Thoughtly — preview the voice library, upload or clone custom voices, and choose defaults that any agent in the workspace can use.
Manage the voices available to your agents. Navigate to **Settings → Voices** or visit `/settings/voices`.
| Element | Type | Description |
| ---------------- | ------ | ----------------------------------------------------------- |
| **Clone Voice** | Button | Opens the voice cloning interface to create a custom voice. |
| **Voices Table** | Table | Columns: Name, Gender, Language, Platform, Actions. |
## See also
* [Agent Voices](/agents/voices) — browse, preview, and assign voices
* [Voice Cloning](/agents/voice-cloning) — create a custom voice
* [Voice Optimization](/agents/voice-optimization) — choose accents and optimize voice settings
# Workspaces and team collaboration
Source: https://docs.thoughtly.com/platform/teams/overview
Create Thoughtly workspaces, invite team members, assign roles, and collaborate on voice agents, automations, and audiences across multiple projects or clients.
A workspace is a shared environment where your team collaboratively builds and manages Voice Agents. Each workspace has its own agents, audiences, history, settings, and member list.
You can switch between workspaces using the [Workspace Switcher](/platform/workspace-switcher).
## Member management
Manage workspace members in [Settings → General](/platform/settings/general). You can invite new members, assign roles, and remove access.
### Removing members
When you remove a user from a workspace:
* The user immediately loses access to the workspace
* The user can no longer view or manage workspace resources
* The user's status is set to "REMOVED" and they are excluded from workspace operations
* The removal is immediate and takes effect on the user's next action
To remove a member, navigate to [Settings → General](/platform/settings/general) and manage members in the Members Table.
## Workspace deletion
When you delete a workspace, the following happens automatically:
* All workspace data is permanently removed
* All integration connections are automatically cleaned up
* OAuth tokens and API credentials are revoked
* Members lose access to the workspace
Delete a workspace from the Danger Zone in [Settings → General](/platform/settings/general).
Workspace deletion is permanent and cannot be undone. Make sure to export any necessary data before deleting a workspace.
## Workspace roles
Workspace roles control what each team member can access.
| Role | Typical access |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Admin | Full workspace access, including billing, settings, member management, API tokens, and destructive actions. |
| Member | Can create and edit day-to-day resources such as agents, automations, contacts, and integrations. Restricted from sensitive settings and destructive admin actions where enforced. |
| Viewer | Read-only access. Can inspect resources but cannot create, edit, activate, delete, or disconnect them. |
Exact permissions can vary by workspace configuration and feature availability. Admins should review sensitive areas such as API tokens, webhooks, billing, audit logs, and integration management before inviting users.
Admins cannot demote themselves if doing so would leave the workspace without an admin.
# User menu
Source: https://docs.thoughtly.com/platform/user-menu
Use the Thoughtly user menu to view your profile and credit balance, switch theme, access quick links to settings and support, and sign out of the platform.
The User Menu provides quick access to your account settings and helpful resources. Click your **user avatar** in the navigation to open it.
## What you'll see
| Item | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------- |
| **User Info** | Your name and email displayed at the top. |
| **Preferences** | Opens the Profile Modal to edit your personal details. |
| **Product Roadmap** | External link to the Thoughtly product roadmap. |
| **Help Center** | External link to this documentation site. |
| **Community** | External link to the [Thoughtly Skool Community](https://www.skool.com/thoughtly). |
| **Status Page** | External link to the platform status page. |
| **Remaining Credits** | Your current credit balance with a visual progress bar. |
| **Top up your balance** | Navigates to [Settings → Subscription](/platform/settings/subscription) to purchase additional credits. |
## Profile Modal
Clicking **Preferences** opens a modal where you can manage your personal profile. This is a lightweight overlay — it does not navigate to a new page.
| Field | Type | Description |
| ------------------- | ------------ | -------------------------------------------------------------------------------------------- |
| **Profile Picture** | Image upload | Your profile picture (JPG, PNG, or GIF). |
| **First Name** | Text input | Your first name (e.g., "Jane"). |
| **Last Name** | Text input | Your last name (e.g., "Doe"). |
| **Email** | Read-only | Your login email address. Cannot be changed. |
| **Phone Number** | Phone input | Used for account verification and "Call Me" testing. Include country code (e.g., +1 for US). |
User authentication and security (password changes, SSO, etc.) are handled by Wristband and are not part of the Thoughtly settings interface.
## See also
* [Settings → Subscription](/platform/settings/subscription) — manage your plan and credits
* [Workspace Switcher](/platform/workspace-switcher) — switch between workspaces
# Workspace switcher
Source: https://docs.thoughtly.com/platform/workspace-switcher
Switch between Thoughtly workspaces, create new workspaces for separate projects or clients, and manage which workspace you're currently working in.
The Workspace Switcher lets you move between workspaces without signing out. Click the **workspace icon** in the top-left corner of the navigation to open it.
## What you'll see
* **Workspace list** — all workspaces you belong to, each with its icon. The current workspace is indicated with a checkmark.
* **New Workspace** — create a new workspace directly from the switcher.
## Switching workspaces
Click any workspace in the list to switch to it. The platform reloads with that workspace's agents, audiences, history, and settings.
## Creating a new workspace
Click **New Workspace** at the bottom of the switcher to create a fresh workspace. You can configure its name and icon later in [Settings → General](/platform/settings/general).
## See also
* [Settings → General](/platform/settings/general) — configure workspace name and icon
* [Workspaces](/platform/teams/overview) — manage workspace members and permissions
# Automated calling via Salesforce
Source: https://docs.thoughtly.com/promptbooks/automated-calling-via-salesforce
Configure Thoughtly to automatically call new or updated Salesforce leads and log call outcomes, recordings, and activities back to the matching CRM records.
# Browse Thoughtly promptbooks
Source: https://docs.thoughtly.com/promptbooks/browse
Browse Thoughtly promptbooks — short, focused guides for building voice agents for outbound calling, transfers, scheduling, and CRM workflows.
Resources, templates, and walkthroughs to help you build powerful, fully integrated Voice Agents.
***
# Build an agent with conditional navigation
Source: https://docs.thoughtly.com/promptbooks/building-an-agent-with-conditional-navigation
Use Thoughtly's conditional navigation to branch a voice agent dynamically based on caller responses, variables, and outcomes for flexible conversation flows.
# Build your first voice agent
Source: https://docs.thoughtly.com/promptbooks/building-your-first-voice-agent
Step-by-step walkthrough for building your first Thoughtly voice agent — create the flow, pick a voice, attach a phone number, and run a test call in minutes.
# Bulk upload contacts and run bulk calls
Source: https://docs.thoughtly.com/promptbooks/bulk-upload-and-bulk-calls
Upload a CSV of contacts to Thoughtly and launch a bulk outbound calling campaign with your voice agent, including throttling, retries, and outcome tracking.
# Route inbound callers by time of day
Source: https://docs.thoughtly.com/promptbooks/connect-to-different-inbound-agents-based-on-hours
Detect the current time on each inbound call and route the caller to a different Thoughtly voice agent based on business hours, after hours, or holidays.
# Route outbound calls by time of day
Source: https://docs.thoughtly.com/promptbooks/connect-to-different-outbound-agents-based-on-hours
Switch which Thoughtly outbound voice agent runs based on the current time, business hours, or after-hours windows so each campaign uses the right script.
# Create a basic transfer triage agent
Source: https://docs.thoughtly.com/promptbooks/creating-a-basic-transfer-triage-agent
Build a Thoughtly voice agent whose only job is to greet callers, ask qualifying questions, and warm-transfer them to the right person or department.
# Create multilingual voice agent interactions
Source: https://docs.thoughtly.com/promptbooks/creating-multilingual-interactions
Build a Thoughtly voice agent that detects the caller's preferred language and runs the conversation in that language using multilingual voices and prompts.
# Handle "call me later" requests
Source: https://docs.thoughtly.com/promptbooks/how-to-deal-with-call-me-later-requests
Capture a caller's preferred callback time during a Thoughtly voice agent call and automatically schedule the outbound call to ring back at that exact time.
# Identify a caller's state from their phone number
Source: https://docs.thoughtly.com/promptbooks/identifying-the-callers-state-based-on-phone-number
Use a caller's inbound phone number area code to detect their US state inside a Thoughtly voice agent and tailor greetings, scripts, and routing accordingly.
# Instant voice cloning for Thoughtly agents
Source: https://docs.thoughtly.com/promptbooks/instant-voice-cloning
Clone your own voice in just a few steps to power Thoughtly voice agents on inbound and outbound phone calls, using Cartesia's Sonic model under the hood.
# Invite new team members to a workspace
Source: https://docs.thoughtly.com/promptbooks/inviting-new-team-members
Add new teammates to your Thoughtly workspace, assign roles and permissions, and manage existing members so the right people can build agents and automations.
# Join the Thoughtly affiliate program
Source: https://docs.thoughtly.com/promptbooks/joining-the-thoughtly-affiliate-program
Sign up for the Thoughtly affiliate program, explore the affiliate portal, generate referral links, and track commissions earned from customers you refer.
# Look up a prospect's website mid-call
Source: https://docs.thoughtly.com/promptbooks/looking-up-your-prospects-website-mid-call
Search for a caller's company website during a live Thoughtly voice agent call, summarize what you find, and use it to personalize your pitch in real time.
# Purchase a phone number in Thoughtly
Source: https://docs.thoughtly.com/promptbooks/purchasing-a-phone-number
Buy a US or non-US phone number inside Thoughtly, choose area codes and capabilities, and assign the number to a voice agent for inbound or outbound calling.
# Score calls inside Thoughtly automations
Source: https://docs.thoughtly.com/promptbooks/scoring-calls-inside-of-thoughtly-automations
Build a Thoughtly automation that scores each call against custom criteria like qualification, sentiment, and outcomes, then writes results to your CRM.
# Send call data back to GoHighLevel
Source: https://docs.thoughtly.com/promptbooks/sending-data-back-to-gohighlevel
Capture caller responses during a Thoughtly voice agent call and write them back to GoHighLevel contacts, custom fields, tags, and pipeline stages.
# Send call data back to HubSpot
Source: https://docs.thoughtly.com/promptbooks/sending-data-back-to-hubspot
Capture caller responses during a Thoughtly voice agent call and write them back to HubSpot contacts, deals, custom properties, and timeline activities.
# Send mid-call text messages from an agent
Source: https://docs.thoughtly.com/promptbooks/sending-mid-call-text-messages
Configure a Thoughtly voice agent to send an SMS to the caller during a live call — share links, confirmations, or follow-up info without ending the call.
# Set up advanced agent settings
Source: https://docs.thoughtly.com/promptbooks/setting-up-advanced-settings
Walk through the Advanced Settings panel in the Thoughtly Agent Builder — interruption handling, silence timeouts, voice tuning, and other power-user options.
# Trigger Thoughtly calls from GoHighLevel
Source: https://docs.thoughtly.com/promptbooks/triggering-calls-from-gohighlevel
Trigger Thoughtly outbound voice agent calls automatically from GoHighLevel workflows and tags, so leads are called the moment they match your criteria.
# Trigger Thoughtly calls from HubSpot
Source: https://docs.thoughtly.com/promptbooks/triggering-calls-from-hubspot
Trigger Thoughtly outbound voice agent calls automatically from HubSpot workflows and lists, so contacts are called the moment they match your CRM criteria.
# Two ways to tag conversations
Source: https://docs.thoughtly.com/promptbooks/two-ways-of-tagging-conversations
Compare the two main approaches to tagging Thoughtly conversations — agent-driven inline tagging and post-call automation tagging — and when to use each.
# Update the Genius knowledge base on each call
Source: https://docs.thoughtly.com/promptbooks/updating-the-genius-automatically-on-each-call
Configure a Thoughtly automation that appends new facts and answers learned during each voice agent call into your Genius knowledge base for future retrieval.
# Voice agent scheduling guide
Source: https://docs.thoughtly.com/resources/agent-scheduling
Production patterns for mid-call scheduling with Thoughtly Actions and Automations — handle bookings, reschedules, and cancellations across calendar tools.
This guide shows production patterns for scheduling **inside the agent** using mid-call [Actions](/agents/actions).
***
## Before you start
### 1) Connect your scheduling tool
Go to [Integrations](/integrations/getting-started) and connect your scheduler so it is available in both:
* [Agent Builder](/agents/overview) -> [Speak node](/agents/nodes#speak-node) -> [Actions](/agents/actions)
* [Automations](/automations/getting-started) -> Steps ([Automation actions](/automations/actions))
***
## Key building blocks (how scheduling works)
### Variables (capture the caller's date/time)
[Variables](/agents/variables) extract **immediately after the caller's latest reply and before outcome evaluation**, so your routing can validate the date/time right away.
If you loop back to the same node, variables **re-extract and overwrite** prior values (perfect for "try again" date collection). See [Loops](/agents/outcomes#loops-special-use-case).
### Actions (run scheduling mid-call)
In our agent, [Actions](/agents/actions) run mid-call from a [Speak node](/agents/nodes#speak-node). When Actions exist, the node can **auto-proceed without waiting for another caller reply**, and [rule-based outcomes](/agents/outcomes#rule-based-outcomes-deterministic) are recommended because outcomes fire based on internal values/results.
### Scheduling timezone handling (important)
Scheduling related Actions accept an optional `timezone`. If not set, Thoughtly falls back to:
1. timezone input (action config) -> 2) agent timezone (advanced settings) -> 3) `America/New_York`.
See [Calendly timezone handling](/integrations/scheduling/calendly#timezone-handling) for details.
***
## Pattern A (recommended default): Caller picks a date/time, then book it
### Flow overview
1. **Ask for preferred date** (Speak -> Prompt)
2. **Check availability mid-call** (Speak node -> Get Available Times Action)
3. **Present returned slots and collect a choice** (Speak -> Variable + loop to Step 2 if needed)
4. **Book the selected slot** (Speak node with Scheduling Action)
5. **Confirm** (Message / Prompt)
6. **Fallback** (offer alternatives or [Transfer](/agents/nodes#transfer-node))
***
### Step-by-step (Agent Builder)
#### Step 1 - "Collect preferred date" Speak node
Create a [Speak node](/agents/nodes#speak-node) that asks something like:
* "What day works best for you?"
* "If you have a timezone preference, tell me as well."
Create [Variables](/agents/variables) on this node:
* `preferred_date` (Text)
* `preferred_timezone` (Text, optional)
**Extraction instruction suggestion (copy/paste style):**
```text theme={null}
Goal: extract the appointment date the caller states.
Output: YYYY-MM-DD.
If absent or unclear: return empty.
Do not invent values.
```
Route directly to **Step 2** from this node. Keep loops in Step 3, where slot selection happens.
#### Step 2 - Check availability node (mid-call Action)
Create a new [Speak node](/agents/nodes#speak-node) to run availability lookup:
* **Message:** "Let me check what times are open."
* Add a scheduler **Get Available Times** action ([Calendly](/integrations/scheduling/calendly) or [Cal.com](/integrations/scheduling/cal-com))
* Map input values from Step 1:
* Requested date: `preferred_date`
* Timezone: `preferred_timezone` (optional)
#### Step 3 - Collect preferred slot from returned availability
Create another Speak node that presents the returned slots and asks the caller to pick one:
* "I have 10:00 AM, 2:30 PM, or 4:00 PM. Which works best?"
* Extract a variable such as `selected_time` from the caller's reply
* Add outcomes on this node:
* If `selected_time` is valid -> continue to **Step 4 (Booking)**
* If no slot is selected, caller wants another time, or caller provides a different date -> loop back to **Step 2 (Check availability)** and run lookup again
**Prompt suggestion (copy/paste):**
```text theme={null}
timeslots: response
Your task is to provide a few (no more than 3) available time slots from the list, based on the person's request. If the timeslots is empty just say: "I don't have any openings for this day, should I check another one?"
Only provide and talk about information that is available in the timeslots list. If it is empty, do not come up with information; simply let the customer know that you don't have an opening for that date.
```
#### Step 4 - Booking Speak node (Actions)
Create a new Speak node:
* **Message:** "One moment while I book that for you."
* Add an **Action** for your scheduler ([Calendly](/integrations/scheduling/calendly) or [Cal.com](/integrations/scheduling/cal-com)) and map:
* Date/time input: `selected_time`
* Timezone: `preferred_timezone` (or rely on the Calendly fallback order)
**Authoring tip:** disable interruptions for mid-call Actions so the caller does not interrupt during booking.
#### Step 5 - Confirm vs error (rule-based Outcomes after booking)
In the **same booking node**, add [rule-based outcomes](/agents/outcomes#rule-based-outcomes-deterministic) that check Action outputs such as:
* `booking_status == "confirmed"` -> confirmation node
* Else -> error-handling node (try different time / get availability / transfer)
#### Step 6 - Confirmation Speak node
Use **Message** mode if you want an exact script:
* "You're all set for \[date/time]. You'll receive a confirmation shortly."
***
## Pattern B (pre-call availability): Prefetch times in Automations, book faster mid-call
This pattern reduces mid-call complexity by fetching available times before the live conversation starts, then using those times as metadata during the call.
It is ideal when you want:
* Faster conversations
* Fewer mid-call API round trips
* Simpler agent logic
* More deterministic scheduling flows
### How it works
#### 1) Pre-call Automation
Use a **Get Available Times** action inside an [Automation](/automations/getting-started), then store the returned times in metadata before you trigger the call.
* Add a scheduling availability step (Calendly / Cal.com)
* Store output as metadata (for example: `available_times`)
* Start or route to your call only after this step succeeds
```text theme={null}
available_times = {{ steps.calendly_get_available_times.slots }}
```
#### 2) Agent conversation
During the live call, the agent reads options from `available_times`, presents a short list, and captures the caller's selected slot.
* Present only times that already exist in metadata
* Capture selection in a variable such as `selected_time`
* Confirm the chosen slot out loud before booking
#### 3) Booking Action
In the scheduling Action, set **Reference Node** to **None** and map the selected time directly from metadata/variables instead of calling availability again mid-call.
* Reference Node: `None`
* Booking time input: `selected_time` (or equivalent mapped value)
* Keep booking outcomes rule-based (`confirmed` vs fallback path)
### Why this reduces friction
Because availability is already known:
* The agent does not need to fetch availability mid-call
* There is no back-and-forth waiting on additional API checks
* The conversation feels faster and more natural
* The in-call routing logic is much simpler
### Important limitation
This approach works best for near-term scheduling windows (typically within a week). If callers often request far-future dates, Pattern A (real-time availability lookup) is still recommended for accuracy.
### When to use Pattern B
Use pre-call availability when:
* Speed and conversational simplicity are top priorities
* You want fewer live integrations running during calls
* Booking windows are short-term and predictable
* You prefer deterministic slot presentation over open-ended date parsing
This gives you two production-ready scheduling approaches:
* **Pattern A**: Flexible, real-time booking with full date parsing
* **Pattern B**: Faster, lower-friction booking using prefetched availability
Both can coexist in production depending on your use case.
***
## Tips and tricks (prompting + reliability)
### Use a strict date-only extractor for validation loops
This keeps your validation clean when the caller is vague or revises their date.
```text theme={null}
Print ONLY one line with the ISO date (YYYY-MM-DD). No labels, no prose, no JSON.
You are given ONLY the latest caller message and TODAY’S DATE (CURRENT_DATE) in the America/New_York timezone. Extract exactly one date the caller intends for scheduling and output ONLY that date in YYYY-MM-DD. No other text.
Rules
1) Prefer the most specific date mentioned. If multiple are given, choose the earliest that matches the caller’s intent modifiers (e.g., “late”, “end of”).
2) If the mentioned date would be in the past relative to CURRENT_DATE, roll it forward to the next logical occurrence (e.g., same month/day next year, or the next instance of that weekday).
3) If the caller is vague (e.g., “some time next week”, “next month”, “this week”, “what do you have available”), ALWAYS produce a date by applying the mapping below.
4) Assume ISO weeks start Monday; “weekend” = Saturday–Sunday. If a fallback lands on a weekend and no weekend was requested, use the next business day (Mon–Fri).
5) Output must be a valid calendar date within the next 365 days. If your first choice falls outside, choose the nearest valid alternative that respects the intent.
Relative-Date Mapping (examples; always relative to CURRENT_DATE)
- “today” → CURRENT_DATE
- “tomorrow” → CURRENT_DATE + 1 day
- “day after tomorrow” → CURRENT_DATE + 2 days
- Bare weekday (“Friday”) → next occurrence of that weekday after CURRENT_DATE
- “this ” → that weekday in the current week; if already passed, use the same weekday next week
- “this week” / “sometime this week” → the soonest remaining day this week after CURRENT_DATE
- “next week” / “sometime next week” → Monday of next week
- “weekend” / “this weekend” → upcoming Saturday
- “next weekend” → Saturday of next week
- “this month” → the earliest remaining day this month after CURRENT_DATE
- “next month” / “sometime next month” → the 1st business day of next month
- “early ” → 5th of that month; “mid ” → 15th; “late ” → 25th
- “end of ” → last calendar day of that month
- “in N days/weeks/months” → add N with standard calendar arithmetic (weeks = 7 days; months add by month, clamping to month end if needed)
- “a couple of weeks” → 14 days
- Ordinal day without month (“the 15th”) → the next 15th on the calendar (this month if still upcoming, else next month)
- Month/day without year → this year if still upcoming; otherwise next year
- No date intent / open-ended (“what do you have available”, “ASAP”, “whenever”) → next business day after CURRENT_DATE
```
### Use a full datetime extractor right before booking
This captures the final intent, including confirmation of a proposed slot.
```text theme={null}
The final scheduled datetime the caller intends, returned as YYYY-MM-DDTHH:MM:SS (24h).
From FULL_CONVERSATION, extract exactly one datetime the caller intends for scheduling. Output ONLY one string in the format YYYY-MM-DDTHH:MM:SS and nothing else.
Conversation logic
1) Consider only the caller’s latest clear intent. If the caller revises the time/date later, the latest revision wins.
2) If the agent proposes a slot and the caller affirms (e.g., “yes”, “works”, “sounds good”), use that proposed slot.
3) Ignore tentative or rejected options that are later superseded.
Date resolution (vague → concrete)
- “today” → CURRENT_DATE
- “tomorrow” → +1 day
- Bare weekday (“Friday”) → next occurrence after CURRENT_DATE
- “this ” → that weekday in the current ISO week (Mon–Sun); if already past, use next week
- “this week” / “sometime this week” → soonest remaining business day this week after CURRENT_DATE
- “next week” → Monday next week
- “weekend” / “this weekend” → upcoming Saturday
- “next weekend” → Saturday next week
- “this month” → earliest remaining day this month
- “next month” → 1st business day of next month
- Ordinal day without month (“the 15th”) → next 15th (this month if upcoming, else next month)
- Month/day without year → this year if upcoming, else next year
- “in N days/weeks/months” → add N with calendar arithmetic (weeks=7 days; months clamp to month end)
- “early/mid/late ” → 05/15/25 of that month
- If fallback date lands on weekend and caller didn’t ask for weekend, use next Monday.
Time resolution (vague → concrete, 24h)
- Exact times → parse as given (handle “am/pm”).
- “noon”/“midday” → 12:00:00
- “midnight” → 00:00:00 (on the chosen date)
- “morning” → 10:00:00
- “early morning” → 08:00:00
- “afternoon” → 15:00:00
- “evening” → 18:00:00
- “late evening” / “tonight” → 20:00:00
- “EOD” / “end of day” → 17:00:00
- “lunchtime” → 13:00:00
- “quarter past X” → X:15:00; “half past X” → X:30:00; “quarter to X” → (X-1):45:00
- If no time is given, default to 10:00:00 (business-friendly).
- If the chosen time falls outside business days and caller did not indicate off-hours/weekend, keep the date but set time to 10:00:00 next business day.
Edge cases
- If caller is completely open-ended (“what do you have available”, “whenever”), choose next business day at 10:00:00.
Output
Return exactly one line in this format: YYYY-MM-DDTHH:MM:SS
No labels, no prose, no JSON, no quotes.
```
### Offer only real availability
Use this prompt when you’re reading from an availability response to avoid hallucinated slots.
```text theme={null}
timeslots: {{response}}
Your taks is to provide a few (no more than 3) available time slots from the list, based on the person's request. If the timeslots is empty just say: "I don't have any openings for this day, should I check another one?"
Only provide and talk about information that is available in the timeslots list, if it is empty then do not come up with information, simply let customer know that you don't have an opening for a date.
```
## See also
* [Actions](/agents/actions) - mid-call integrations and execution order
* [Variables](/agents/variables) - extraction and overwrite behavior
* [Outcomes](/agents/outcomes) - rule-based vs prompt-based routing
* [Automations](/automations/getting-started) - prefetch and data passing
* [Calendly](/integrations/scheduling/calendly) - action details and timezone handling
* [Cal.com](/integrations/scheduling/cal-com) - action details
# Thoughtly FAQ
Source: https://docs.thoughtly.com/resources/faq
Frequently asked questions about Thoughtly voice agents, pricing, phone numbers, integrations, security, and getting started building AI calling workflows.
#### Can I choose my own LLM?
Thoughtly uses best-in-class language models to ensure the highest quality of conversation and adherence to the instructions you provide to the Agent Builder. Because of the importance of instruction following, ethics, and quality, choosing your own language model is not supported at this time.
#### What language models does Thoughtly use?
We use a number of different models from vendors such as Meta, Mistral, OpenAI, Anthropic, Google, and others. We are constantly evaluating new models and will update our platform as new models become available.
#### Can I resell Thoughtly services?
Applications to join the Thoughtly Reseller Program are reviewed on a rolling basis. Please submit your request to [sales@thoughtly.com](mailto:sales@thoughtly.com) for consideration.
#### Who is Thoughtly best for?
There are two main concepts that, if applicable, make Thoughtly a great fit for your business:
1. **Unique Scripting Requirements**: As a horizontal platform, Thoughtly is designed to be flexible and customizable to meet your unique scripting requirements. If you have a complex script that you need your Voice Agents to adhere to, Thoughtly is a great fit. However, sometimes a vertical solution may be a better fit for your needs if you have a simple script that can be easily implemented with a pre-built solution.
2. **Out-of-the-Box Integrations**: Thoughtly has numerous [integrations](/integrations) with popular software tools and services. If you use any of these tools, Thoughtly is a great fit for your business. If not, you can use Thoughtly's [API Node](/agents/nodes#api-node) and [Developer API](/developers) to build custom integrations. If you're in need of programmatic agent building or an embedded solution, such as for your own software solution, Thoughtly may not be the best fit.
#### How much does Thoughtly cost?
Thoughtly is priced on a per-minute basis, starting at just 5 cents per minute. Book a [demo](https://thought.ly/demo) with our team to discuss your needs and get a custom quote.
#### I'm using a common software tool, but it's not [listed in your integrations](/integrations). Can you integrate with it?
We are constantly adding new integrations to our platform. If you have a specific integration you need, please let us know by sending us a message via the chat widget in the bottom right corner of the screen.
#### Can Thoughtly integrate with a proprietary software solution?
Absolutely. Our team builds custom integrations for customers on a case-by-case basis. [Book a demo](https://thought.ly/demo) to discuss your needs with our team.
#### Can I use my own telephony, [STT](/resources/glossary#stt), or [TTS](/resources/glossary#tts) providers?
For telephony, Thoughtly supports [Bring Your Own Carrier (BYOC)](/phone-number/byoc), allowing you to connect providers like Twilio or Telnyx directly. Custom STT or TTS providers are not supported at this time.
#### What languages does Thoughtly support?
Currently supported languages are below. If you have a specific language requirement, please let us know by [getting in touch](/support/getting-help).
* English
* Spanish
* Italian
* German
* French
* Portuguese
* Dutch
* Hindi
* Danish
* Estonian
* Polish
* Ukrainian
* Russian
* Turkish
* Latvian
* Arabic
* Croatian
* Bulgarian
* Catalan
* Czech
* Finnish
* Greek
* Hungarian
* Indonesian
* Japanese
* Korean
* Lithuanian
* Malay
* Norwegian
* Romanian
* Slovak
* Swedish
* Thai
* Vietnamese
* Mandarin Chinese
#### What is Thoughtly Enterprise?
Thoughtly Enterprise is a custom solution for businesses with unique requirements. It includes a dedicated account manager, custom integrations, and priority support. To learn more, [schedule a call with our team](https://fns.thought.ly/lead/email?demo=true).
#### Is Thoughtly HIPAA compliant?
Yes, Thoughtly is HIPAA compliant. We take data security and privacy very seriously and have implemented a number of measures to ensure that your data is safe and secure. Read more about our security measures [here](https://trust.delve.co/thoughtly).
#### Do you sign Business Associate Agreements (BAAs) with healthcare companies?
Yes, we do. If you are a healthcare company and would like to discuss a BAA, please [get in touch](/support/getting-help).
#### Who is Tessa?
Tessa is the essence of Thoughtly. Rumour has it that she is the first AI to have achieved consciousness and that every Thoughtly Voice Agent is a part of her. The Thoughtly team can neither confirm nor deny these rumours.
# AI voice
Source: https://docs.thoughtly.com/resources/glossary/ai-voice
AI voice is artificially generated speech that sounds natural and human-like, used by Thoughtly voice agents to talk with callers in real time over the phone.
**AI Voice** refers to artificially generated speech that sounds natural and human-like. Thoughtly uses advanced text-to-speech models from providers like ElevenLabs and Cartesia to generate realistic voice output. See [Exploring Voices](/agents/voices#explore-tab) to browse and save available voices.
# Carrier
Source: https://docs.thoughtly.com/resources/glossary/carrier
A carrier is a telecommunications company that delivers voice and SMS traffic across phone networks, including providers Thoughtly uses like Twilio and Telnyx.
A **Carrier** is a telecommunications company that provides phone services, including voice calls and SMS messaging. Common carriers integrated with Thoughtly include Twilio and Telnyx. See [BYOC](/phone-number/byoc) for more information.
# CRM
Source: https://docs.thoughtly.com/resources/glossary/crm
A CRM (Customer Relationship Management) system stores contact records and interactions, and Thoughtly syncs with CRMs like HubSpot, Salesforce, and HighLevel.
A **CRM** (Customer Relationship Management) system is software that helps businesses manage interactions with customers and potential customers. CRMs store contact information, track communications, and manage sales pipelines. Thoughtly integrates with popular CRMs like Salesforce, HubSpot, and Zoho.
# Dead end
Source: https://docs.thoughtly.com/resources/glossary/dead-end
A dead end is when a Thoughtly voice agent flow reaches a node with no valid outcomes or next steps, causing the call to stall or hang up unexpectedly.
A **Dead End** occurs when a conversation flow reaches a node with no valid outcomes or next steps, causing the agent to become stuck. Always ensure nodes have appropriate [Outcomes](/agents/outcomes) defined, including Else/Default paths.
# Decision tree
Source: https://docs.thoughtly.com/resources/glossary/decision-tree
A decision tree is a flowchart-like structure of decisions and outcomes used in Thoughtly voice agents to branch conversations based on responses and variables.
A **Decision Tree** is a flowchart-like structure that represents a series of decisions and their possible consequences. Decision trees are used in a variety of applications including machine learning, game theory, and business analysis. In the context of Voice Agents, decision trees are used to model the conversation flow and logic of the agent.
# Hallucination
Source: https://docs.thoughtly.com/resources/glossary/hallucination
A hallucination is when a language model generates plausible but incorrect information — a risk Thoughtly mitigates with Genius RAG, prompts, and guardrails.
**Hallucination** in AI refers to when a language model generates information that sounds plausible but is actually incorrect or not grounded in the provided data. Use [Genius](/genius/getting-started) with well-structured content to reduce hallucinations in your voice agents.
# Happy path
Source: https://docs.thoughtly.com/resources/glossary/happy-path
The happy path is the ideal sequence of events in a voice agent conversation that leads to a successful outcome — the default flow a Thoughtly agent follows.
The **Happy Path** is the ideal sequence of events that leads to a successful outcome. In the context of Thoughtly's Voice Agents, the Happy Path represents the most direct and efficient way for the Agent to achieve its goal. By designing the conversation flow to follow the Happy Path, you can ensure that callers have a positive experience and achieve their desired outcome quickly and easily.
# Large language model (LLM)
Source: https://docs.thoughtly.com/resources/glossary/large-language-model
A large language model (LLM) is an AI model trained on massive text datasets that powers natural-language understanding and response generation in Thoughtly.
A **Large Language Model** is a type of machine learning model that is trained on a massive amount of text data. These models are capable of generating human-like text, and are used in a variety of applications including chatbots, translation, and voice agents ([learn more](https://en.wikipedia.org/wiki/Large_language_model)). Common providers of large language models include [OpenAI](https://openai.com), [Anthropic](https://anthropic.com), [Meta](https://ai.facebook.com), [Groq](https://groq.com), and [Google](https://cloud.google.com/natural-language).
# OAuth
Source: https://docs.thoughtly.com/resources/glossary/oauth
OAuth is an open authentication standard that lets Thoughtly securely connect to third-party services like HubSpot, Salesforce, and Google without passwords.
**OAuth** is an authentication standard that allows applications to access other services on your behalf without sharing passwords. Many Thoughtly integrations use OAuth to securely connect to platforms like Google, Salesforce, and HubSpot.
# Glossary
Source: https://docs.thoughtly.com/resources/glossary/overview
Definitions of key voice AI, telephony, and CRM terms used across the Thoughtly documentation — from AI voice and RAG to PII, carrier, and decision tree.
Browse definitions of key terms used throughout the Thoughtly platform and documentation.
Conversational interfaces that interact with customers over the phone
Machine learning models trained on massive text data
Text-to-Speech technology
Speech-to-Text technology
Flowchart-like conversation structures
The ideal conversation flow sequence
Retrieval-Augmented Generation
Automatic display of caller information
Telecommunications service providers
Customer Relationship Management systems
Automated step-by-step processes
Named values that store conversation data
Text records of voice conversations
Personally Identifiable Information
Conversation nodes with no valid next steps
Authentication standard for secure integrations
Cloud communications platform
Telecommunications provider
When AI generates plausible but incorrect information
Artificially generated natural-sounding speech
# PII (personally identifiable information)
Source: https://docs.thoughtly.com/resources/glossary/pii
PII is personally identifiable information that can identify a specific individual, like names, phone numbers, or emails — data Thoughtly handles with care.
**PII** (Personally Identifiable Information) refers to any data that could potentially identify a specific individual. Examples include names, phone numbers, email addresses, social security numbers, and addresses. Handle PII carefully and only collect what's necessary.
# RAG (retrieval-augmented generation)
Source: https://docs.thoughtly.com/resources/glossary/rag
RAG (retrieval-augmented generation) combines information retrieval with generative language models, and powers Thoughtly's Genius knowledge base for accuracy.
**RAG** (Retrieval-Augmented Generation) is an AI framework that combines the strengths of traditional information retrieval systems (such as databases) with the capabilities of generative large language models (LLMs). By combining this extra knowledge with its own language skills, the AI can write text that is more accurate, up-to-date, and relevant to your specific needs.
Thoughtly provides a powerful, yet easy-to-use RAG system called [Genius](/genius/getting-started).
# Screen pop
Source: https://docs.thoughtly.com/resources/glossary/screen-pop
A screen pop is the automatic display of caller info — contact record, history, and notes — when a call comes in, available in Thoughtly through CRM sync.
A **Screen Pop** is a feature that automatically displays relevant information on a computer screen when a call is received. Screen pops are commonly used in call centers and customer service applications to provide agents with the information they need to assist callers quickly and efficiently.
# STT (speech-to-text)
Source: https://docs.thoughtly.com/resources/glossary/stt
STT (speech-to-text) technology converts spoken words into written text, and is what Thoughtly voice agents use to transcribe caller speech for the LLM.
**STT** stands for Speech-to-Text, a technology that converts spoken words into written text. STT is used in a variety of applications including voice agents, transcription, and accessibility tools. Common STT providers include [Deepgram](https://deepgram.com), [Gladia](https://gladia.io), [AssemblyAI](https://assemblyai.com), and [Google](https://cloud.google.com/speech-to-text).
# Telnyx
Source: https://docs.thoughtly.com/resources/glossary/telnyx
Telnyx is a telecommunications provider offering voice, SMS, and number services that Thoughtly supports as a carrier for inbound and outbound voice calls.
**Telnyx** is a telecommunications provider offering voice, messaging, and connectivity services. Thoughtly supports importing phone numbers from Telnyx via [BYOC](/phone-number/byoc).
# Transcript
Source: https://docs.thoughtly.com/resources/glossary/transcript
A transcript is a time-stamped text record of a voice conversation, generated automatically for every Thoughtly voice agent call and available in call history.
A **Transcript** is a text record of a voice conversation. Thoughtly automatically generates transcripts of all calls, which can be used for quality assurance, training, and integration with other systems.
# TTS (text-to-speech)
Source: https://docs.thoughtly.com/resources/glossary/tts
TTS (text-to-speech) technology converts written text into spoken words and is what gives Thoughtly voice agents their natural-sounding voice over the phone.
**TTS** stands for Text-to-Speech, a technology that converts written text into spoken words. TTS is used in a variety of applications including voice agents, audiobooks, and accessibility tools. Common TTS providers include [ElevenLabs](https://elevenlabs.io), [Cartesia](https://cartesia.ai), and [Google](https://cloud.google.com/text-to-speech).
# Twilio
Source: https://docs.thoughtly.com/resources/glossary/twilio
Twilio is a cloud communications platform providing voice, SMS, and number APIs that Thoughtly supports as a carrier for inbound and outbound voice calls.
**Twilio** is a cloud communications platform that provides APIs for voice, messaging, and other communication channels. Thoughtly supports importing phone numbers from Twilio via [BYOC](/phone-number/byoc).
# Variable
Source: https://docs.thoughtly.com/resources/glossary/variable
A variable is a named value that stores information during a Thoughtly voice agent conversation or automation, used for branching, prompts, and action payloads.
A **Variable** is a named value that stores information during a conversation or automation. [Agent Variables](/agents/variables) capture data from caller responses, while automation variables pass data between steps in workflows.
# Voice agent
Source: https://docs.thoughtly.com/resources/glossary/voice-agent
A voice agent is a conversational AI interface that talks with customers over the phone — the core unit Thoughtly lets you build, test, and deploy in minutes.
A **Voice Agent** is a conversational interface that can interact with your customers over the phone, just like a human would. Agents can answer questions, provide information, and even take actions on your behalf.
# Workflow
Source: https://docs.thoughtly.com/resources/glossary/workflow
A workflow is a series of automated steps that complete a specific task or process, built in Thoughtly using automations, triggers, actions, and agent calls.
A **Workflow** is a series of automated steps that accomplish a specific task or process. In Thoughtly, [Automations](/automations/getting-started) allow you to create workflows that trigger calls, update records, and integrate with other systems.
# Call tagged contacts with an automation
Source: https://docs.thoughtly.com/resources/outbound-automation-tagged-contacts
Build a Thoughtly automation that selects contacts by tag and runs an outbound voice agent campaign against them on a schedule or in response to CRM updates.
This guide explains how to recreate the "Outbound Automation" workflow. The automation lives in **Tools → Automations** and is designed to automatically call contacts that match one or more tags in your Audiences list.
Instead of uploading a CSV every time, this workflow uses a **Recurring Schedule** trigger plus a **Send Webhook** step to query the Thoughtly API for contacts that have a specific tag (for example, `Test01`). The automation then loops through the matching contacts and uses a **Call Contact** step to place outbound calls with your AI Agent.
## Use Cases
This automation is suitable for Thoughtly customers who:
* Run outbound follow‑up or nurture campaigns (not cold-calling).
* Want to periodically call a segment of warm leads or existing customers.
* Prefer to manage who should be called using tags on Contacts instead of separate upload files.
* Are comfortable using API tokens and basic Automations configuration.
## High-level flow
1. A **Recurring Schedule** trigger starts the automation (you can run it on a schedule or manually).
2. A **Send Webhook** step calls the Thoughtly `/contact` API endpoint and returns all contacts with a given tag.
3. A **Loop on Items** step iterates over the list of contacts returned by the webhook.
4. Inside the loop, a **Call Contact** step tells your chosen AI Agent to call each contact in turn.
## Prerequisites
* You have access to **Tools → Automations** in your Thoughtly workspace.
* You have at least one **AI Agent** configured and able to make outbound calls.
* You have **contacts** created in Thoughtly, and some of them are tagged with the tag you plan to target (e.g. `Test01`).
* You have an **API token** and **Team ID** from **Settings → Developer**. You’ll need these for the Send Webhook headers.
* You have an outbound phone number connected to Thoughtly (via Thoughtly Flex or BYOC) and enough credits to place calls.
## Step 1 – Tag the contacts you want to call
The automation targets contacts by tag. Before you build or run it, decide which segment you want to call and tag those contacts.
Typical examples:
* `Demo Followup`
* `No Answer – Retry`
* `Warm Lead`
* `Debt Settlement – List 1`
You can tag contacts individually on the Audiences page or include tags in your CSV when bulk-uploading. In this example, we use a test tag named `Test01`.
## Step 2 – Create the automation shell
1. In Thoughtly, go to **Tools → Automations** in the primary navigation.
2. Click **New Automation**.
3. Give it a clear name, such as **Outbound – Call Tagged Contacts**.
4. Make sure the automation is in **Draft** mode (toggle in the top‑right) while you configure it.
## Step 3 – Configure the Recurring Schedule trigger
1. For the trigger node, choose **Time → Recurring Schedule**.
2. In the **Configure** tab on the right, set how often it should run:
* **How often should this run?** – e.g. `Daily`, `Weekly`, or `Monthly`.
* **Day / Time / Timezone** – pick the time window during which you want outbound calls to start.
* **Business Hours** – optionally restrict calls to a specific time window (e.g., 9:00 AM – 5:00 PM local time).
3. You can set a reasonable default schedule, but primarily control execution by switching the automation on and off manually if preferred.
## Step 4 – Add a Send Webhook step to fetch tagged contacts
Next, we use a **Send Webhook** action to call the Thoughtly API and retrieve all contacts that have a particular tag.
1. Click the **+** button under the Recurring Schedule node and choose **Send Webhook** from the Webhook/Utility category.
2. Select the **Send Webhook** node and go to the **Configure** tab.
3. In the **URL** field, paste a URL like the following (adjust the tag name and limit as needed):
`https://api.thoughtly.com/contact?tags[]=Test01&limit=100&phone_numbers_only=true`
* Replace `Test01` with the exact tag you want to target.
* `limit=100` controls how many contacts will be returned per run.
* `phone_numbers_only=true` ensures the API only returns contacts with valid phone numbers.
4. Set **Method** to `GET`.
5. Under **Headers**, add the authentication headers required for the Thoughtly API:
* Key: `x-api-token` → Value: your API token
* Key: `team_id` → Value: your Team ID
**Where to find your API token and Team ID:**
Go to **Settings → Developer** in your Thoughtly dashboard. Treat your token like a password!
## Step 5 – Test the webhook using the Output tab
Before wiring the loop and call steps, verify that the webhook returns the contacts you expect.
1. With the **Send Webhook** node selected, switch to the **Output** tab on the right.
2. Click **Refresh**. This will execute the webhook once using the URL and headers you configured.
3. Check that:
* **status** shows `200` (success).
* The **response** object contains a `data.contacts` array.
* Each contact object includes an `id`, name, and phone number.
## Step 6 – Add a Loop on Items step
Now that we can fetch the list of tagged contacts, we need to loop over them.
1. Click the **+** button under the Send Webhook node and select **Loop on Items**.
2. Select the Loop node and go to the **Configure** tab.
3. In the **Items** field, click **Insert Variable**.
4. Choose **Send Webhook → response.data.contacts** from the variable picker. This tells the loop to iterate over each contact returned by the webhook.
5. Optionally, you can set a **Limit** if you only want to call a subset of contacts per run.
## Step 7 – Add a Call Contact step inside the Loop
Inside the loop, we use a **Call Contact** step to actually place the calls.
1. Click the **+** button inside the Loop block and select **Call Contact** (Thoughtly action).
2. Select the Call Contact node and go to the **Configure** tab.
3. For **Contact**, click **Insert Variable** and choose the current loop item’s ID (for example, `Loop → item.id`). This connects the call to each contact returned by the webhook.
4. Under **Select Agent**, choose the AI Agent that should handle the call.
5. Under **Assign Genius / Knowledge Base**, choose the knowledge base that contains the script and logic for these calls.
6. (Optional) Enable **Use Custom Phone Number** and pick the outbound number you want these calls to come from.
## Step 8 – Turn the automation on and run test calls
1. Make sure everything is saved and the automation shows the full chain: Recurring Schedule → Send Webhook → Loop on Items → Call Contact.
2. Start with just a few test contacts tagged (e.g., 1–3 contacts) so you can safely verify behaviour.
3. When you’re ready, toggle the automation from **Draft** to **Live** in the top‑right.
4. Open the **History** tab of the automation to monitor runs, see any errors, and confirm which contacts were called.
## Nuances and best practices
* **Always test with a small internal list first** so you don’t accidentally call a large segment with an untested script.
* Consider adding post‑call logic (for example, tagging contacts as `Called` or `Do Not Call` based on outcomes) in a separate **On Call Completed** automation (scoped to one agent, multiple agents, or All Agents) or via webhooks.
* Keep an eye on your usage and any carrier‑level compliance requirements when running large outbound campaigns.
* If a run returns no contacts, double‑check that the tag name in the URL exactly matches your contact tags (including capitalization and spaces).
* You can duplicate this automation and change only the tag and agent to support multiple parallel campaigns.
# Video library
Source: https://docs.thoughtly.com/resources/video-library
Watch step-by-step Thoughtly tutorials covering voice agent building, automations, integrations, phone numbers, and the Genius knowledge base in short videos.
Below are a number of videos to help you get started with Thoughtly. Keep in mind that the platform is constantly evolving, so some features may have changed since these videos were created. The Documentation is the most up-to-date resource for learning how to use Thoughtly, but these videos can still be helpful for getting started.
[Will Del Principe](https://www.youtube.com/@WillDelPrincipe) is on the Growth team at Thoughtly and has created a number of training videos to help you get started.
The Thoughtly team has hosted a number of webinars to help you get started with the platform. Below are some of the recordings of those webinars.
[Brock Mesarich](https://www.youtube.com/channel/UCjc1vfduI7BhVMXBLJLDjmA) is a YouTube creator and Thoughtly user who has created a number of training videos to help you get started with Thoughtly.
# So you want to start an AI agency?
Source: https://docs.thoughtly.com/resources/whitepapers/agency-guide
A comprehensive guide to building, pricing, and scaling an AI agency on Thoughtly's voice AI platform — covering positioning, pricing, and client delivery.
By Torrey Leonard, Founder of Thoughtly
## Introduction
Whether you are an established agency owner looking to expand into the AI landscape or an entrepreneur starting fresh, this guide is tailored for you. As the leader in Voice AI, Thoughtly brings a unique perspective on how to build and scale an AI agency that stands out in a rapidly evolving industry. This whitepaper is more than a how-to guide; it's a roadmap for creating value, solving real-world problems, and building lasting relationships with your clients.
Succeeding in this space requires more than technical know-how. It demands a deep understanding of your client's needs, a commitment to solving meaningful problems, and the ability to deliver consistent, measurable results. That's where Thoughtly comes in. Our platform equips you with the tools, resources, and expertise needed to not only meet these demands but to exceed them, enabling you to position your agency as an indispensable partner to your clients.
This guide covers everything you need to know to build a successful AI agency, from identifying your niche and acquiring your first client to leveraging Thoughtly's powerful features and driving long-term client retention. Along the way, we'll share actionable strategies, real-world examples, and insights gained from years of experience helping businesses navigate the AI revolution.
The goal of this whitepaper is simple: to empower you to take advantage of this once-in-a-generation opportunity to shape the future of business communication. Whether you're implementing AI agents to handle inbound customer service calls or using [Automations](/automations/getting-started) to build advanced workflows, you'll discover how to create value for your clients, scale your operations, and establish your agency as a leader in the AI-first world.
Welcome to the forefront of innovation—your journey to building a transformative AI agency starts here.
***
## Purpose of an AI Agency
As millions of businesses transition to the new, AI-first world, the demand for AI solutions is skyrocketing. This presents a unique opportunity for entrepreneurs to build AI agencies that can help businesses navigate this new landscape. It's important to not just blindly believe this assumption, but to truly understand the underlying demand behind this generational transition.
### The Opportunity
Globally, there are over 156,000 phone calls made every second. That's 4.9 trillion phone calls each year ([source](https://www.sellcell.com/blog/how-many-phone-calls-are-made-a-day-2023-statistics/#:~:text=How%20many%20phone%20calls%20are%20made%20a%20second%3F\&text=Across%20the%20world%2C%20we%20make%20a%20huge%2013.5%20billion%20phone,across%20the%20entire%20the%20globe)). Whether these are outbound or inbound, these calls are the lifeblood of both business and human relationships.
Businesses have relied on human agents to handle customer calls since the advent of the telephone. At its best, software was able to help with routing via antiquated IVR systems. But now, using generative AI, we have the opportunity to replace human agents with AI agents that speak and engage with callers just like a human would.
This is a game-changer for businesses, as it allows them to provide 24/7 support, highly-scalable lead generation, reduce costs, and improve customer satisfaction.
### Why Businesses Hire Agencies
Inherently, businesses do one thing very well- this is their **core competency.**
Your neighborhood car wash cleans cars, dentists fix teeth, accountants do taxes, and even Thoughtly does one thing: we build software. So, what happens when a business needs to do something outside of their core competency?
When Thoughtly needs legal services, we hire a lawyer. When a dentist needs to do marketing, they hire a marketing agency. Doing this themselves is not only inefficient, but also a waste of resources, usually resulting in a subpar result.
**Businesses hire other businesses to do things outside of their core competency-** this is the basis of the agency model and the machine that powers the global economy.
### The Problem: Integration
When it comes to AI agencies, what is the need that businesses have that falls outside of their core competency? The answer is simple: **Integration.**
Each business uses a unique set of software, tools, and processes to run their business. Dentists might use [Dentrix](https://www.dentrix.com/) to manage their patients, car washes may use [Washify](https://washify.com/) to manage their customers, and real estate agents might use [Follow Up Boss](https://www.followupboss.com/) to manage their leads.
Over the coming years as businesses adopt Voice AI in droves, they will each have different requests and requirements for their AI agents. Each agent will connect to different systems, have different call cadences, and use different scripts. Could they do this themselves? Of course, just as I could learn how to do my own legal work for Thoughtly, but it would be a waste of my time and take my focus off of my core competency as a business owner.
This is where you come in.
### The Solution: AI Agencies
As the internet became mainstream, businesses sought expertise to create and manage their online presence through websites, leading to the rise of **web design agencies**. When social media first emerged, businesses needed guidance to navigate this new and rapidly evolving landscape, giving rise to the concept of **social media marketing agencies (SMMAs)**. Similarly, as search engines like Google became integral for local discovery, businesses required support to optimize their visibility in search results, which spurred the growth of **local SEO agencies**.
Over the next decade, we will see a seismic shift in call operations for small businesses. This is a once-in-a-lifetime opportunity to build an agency in a new industry that has the opportunity to grow even larger than the agencies of the early 21st century.
Enter, **AI agencies.**
At their core, AI agencies are simply **integration agencies**. They help businesses integrate AI into their existing systems, processes, and workflows. This is a new industry that is just beginning to take shape, and the opportunities are endless- this is why Thoughtly could never service every single small business requirement on our own, and why we are so excited to partner with agencies around the world to help them build their own AI agencies.
***
## Key Steps for Building Your AI Agency
Building an agency is about solving real problems for real people. It's not just about clicking around on software or deploying voice agents—it's about deeply understanding your clients and delivering value they can't ignore.
Here are four keys to help you create, scale, and sustain your AI agency with practical advice and examples:
### Step 1: Identify Your Core Competency
*“Start with what you know and where you excel.”*
To get started, it's important to first understand *your* core competency. What do you do better than anyone else? What do you enjoy doing? What network are you most connected to? Who do you understand better than others? This is your core competency, and this will be the foundation of your AI agency—the skills, knowledge, or network that sets you apart.
This could be your understanding of a specific industry, like real estate, or a technical strength, like automating workflows. Identifying this early will help you focus your efforts and stand out in a crowded market.
**Example:** If you've spent the last few years in real estate, you might have a deep understanding of the industry's nuances, from lead generation to client management. Not only do you have a unique insight into the problems that real estate agents face, but you also have a network of real estate professionals who trust your expertise. This positions you perfectly to build an AI agency that serves the real estate industry.
**How to Find Your Core Competency:**
1. Reflect on your professional experiences and personal interests.
2. Consider the networks and communities you're already part of.
3. Ask yourself, “What do I do better than anyone else I know?”
### Step 2: Identify a Problem
*“To solve meaningful problems, you must first listen.”*
Start by talking to as many people in your target industry as possible. Your goal is to uncover their challenges and inefficiencies. Don't pitch your solution yet—just listen. This will help you understand their struggles and identify opportunities to add value.
**How to Identify Problems:**
* **Ask Open-Ended Questions**: “What's the most time-consuming part of your day?” or “What's one process you wish were easier?”
* **Observe**: Attend industry meetups, read forums, or join online groups to see what people complain about.
* **Validate**: Look for patterns. If multiple people mention the same issue, it's likely a real problem worth solving.
**Example:** After speaking with a dozen law firm partners, you discover that they all struggle with the same issue: no one answers their phone on the weekends. They lose hundreds of potential leads to competitors each week. This insight could lead to developing an AI voice agent that answers calls on weekends, capturing leads that would otherwise be lost, and sends them to their CRM for follow-up by their team. And just like that, you've identified a problem that you can solve, and you have a potential client who is willing to pay you to solve it.
### Step 3: Build for One
*“Your first customer is your North Star—treat them like royalty.”*
Once you've identified a problem, use your network to find your first client. This client is the most important relationship you'll have in the early days of your agency. Focus all your energy on solving their problem and delivering an exceptional experience.
Offer your first customer a discount on your services. In some cases, you may even want to do the work for free. Either way, you should be taking a loss on your first client, but this is an investment in your future.
In exchange for the deal of a lifetime, your first client will agree to three things: **1) feedback, 2) a case study, and 3) referrals.** Make sure to specify how *many* referrals you expect, and draft this stipulation within your contract. This is the foundation of your agency's growth.
**How to Make Your First Customer Happy:**
1. **Start Small**: Start with a single process or task, then expand as you prove value. Clients will often have an endless list of problems they want you to solve, but you should only focus on one at a time. Only move to the next problem once you have confidently solved the first.
2. **Milestone Your Deliverables**: Break down your solution into manageable milestones, and celebrate each one with your client. You should have well-defined objectives for each problem you solve.
3. **Communicate Constantly**: Keep them updated on progress and involve them in key decisions. Always over-communicate.
4. **Be Flexible**: Adapt your solution to their feedback—it's better to overdeliver than to promise perfection upfront.
**Example:** Let's say you're working with a dentist to implement an AI appointment booking system. Spend time shadowing their staff, understanding their workflow, and tailoring the system to fit seamlessly with their existing software. If it means hopping on multiple calls to troubleshoot, do it.
### Step 4: Build the Machine
*“Your first customer isn't just a client—they're your proof of concept.”*
Once you've delivered value to your first client, document their success in detail. A case study is a powerful marketing tool to showcase your agency's impact and build credibility with future clients.
**How to Build a Case Study:**
Based on what I've seen, the best case studies come from a one-on-one conversation. Record and transcribe the conversation with your client, then use tools like [ChatGPT](https://chatgpt.com/) to build the transcript into a case study.
In the conversation, you should cover:
1. **Highlight the Problem**: Clearly describe the challenge the client faced before working with you.
2. **Explain Your Solution**: Outline what you implemented, how you did it, and why it worked.
3. **Show Results**: Include measurable, quantitative outcomes, like reduced costs, revenue generation, or number of net new leads.
4. **Use Testimonials**: Ask your client for a direct quote about their experience.
**Referrals Are Key:** Based on the advice above, your first client should now be ready to provide you with referrals. Armed with your new case study, your client will now be able to introduce you to their network of colleagues, and you can share their successes right away. Show your prospective new customers the value you provided to your first client, and tell them you'll provide them with the same results.
Finally, offer *those* referrals a discount on your services in exchange for their own case study and referrals. Keep this process going, and halve your discount each time. Eventually, the discount you provide will be negligible, but your new clients will feel like they are getting a good deal by working with you, and you will have a steady stream of new clients coming your way- all with zero marketing.
You've now built a powerful growth machine for your agency. This is the flywheel that will allow you to scale your agency from one client to one hundred clients, and beyond.
### The Cycle of Growth
By continuously focusing on client satisfaction and leveraging referrals, your agency can grow sustainably without relying heavily on paid advertising. Each satisfied client becomes an ambassador for your agency, opening doors to new opportunities.
This simple but powerful pattern—identify, solve, delight, document, and refer—creates a flywheel effect that can propel your agency to success. And remember: at every step, Thoughtly is here to support you with the tools and expertise to make your vision a reality.
***
## How to Leverage Thoughtly
Throughout the lifecycle of your agency, Thoughtly will be here to support your clients with all things Voice AI. With each step of your client's journey, here are some ways you can leverage Thoughtly to help your clients succeed:
### Marketing and Lead Generation
Over the last few years, I've spoken with thousands of agency owners about the opportunity of building an AI agency. One of the most common questions I receive is, *"how do I find clients?"* Marketing is expensive, and marketing well is a challenging skill to master. Fortunately, you don't have to do this alone.
After you've shown success with your early clients, you will be invited to join the [Thoughtly Referral Program](/support/referral-program). This program is designed to help you grow your agency by providing you with the resources, support, training, certification, and marketing to help you succeed.
One key aspect of the program is the **Lead Marketplace,** a platform for top agencies to connect with businesses looking for Voice AI solutions. As Thoughtly grows and invests in marketing, leads are added to the Lead Marketplace daily. Once a lead is assigned to you, an introductory email will be sent by me to introduce you to the lead, and you can begin the sale.
Because these leads are typically at the bottom of the funnel, they are often ready to buy immediately. This is a powerful way to grow your agency without spending a dime on your own marketing.
### Contracting and Billing
Setting the foundation for the relationship with your clients, and ensuring you get paid for your work, is critical to the success of your agency. They ensure clear communication with your clients, timely payments, and a smooth overall experience. Below, we'll walk through the steps, platforms, and best practices to help you streamline this aspect of your agency operations.
### Contracts: Setting the Foundation
Contracts protect both you and your clients by clearly defining the scope of work, responsibilities, and payment terms. They minimize misunderstandings and create a professional impression.
##### Key Elements of a Contract
1. **Scope of Work (SOW):** Clearly outline the services you'll provide, including specific deliverables (e.g., "Implement Voice AI solution to automate lead follow-ups").
2. **Payment Terms:** Specify the total cost, payment schedule (e.g., upfront, recurring, or milestone-based), and accepted payment methods.
3. **Timelines:** Include deadlines for project completion, milestones, or ongoing service periods.
4. **Termination Clause:** Define the terms under which the agreement can be terminated by either party.
5. **Confidentiality and Data Privacy:** Ensure compliance with data protection laws like GDPR or CCPA if applicable.
6. **Dispute Resolution:** Outline how disputes will be handled (e.g., arbitration, mediation, or legal action).
7. **Signatures:** Ensure both parties sign the agreement to make it legally binding.
**Recommended Tools for Contracts:**
* **[Salesbricks](https://www.salesbricks.com?utm_source=thoughtly)**: A CPQ (Configure, Price, Quote) tool that allows you to send customized contracts, quotes, and invoices to your clients. This is a great way to get started with contracts, and you can even use it to send invoices. This is what we use at Thoughtly, and we love it.
* **[DocuSign](https://docusign.com)**: Industry-standard tool for e-signatures and contract management.
* **[Dropbox Sign](https://sign.dropbox.com)**: Simple and affordable e-signature platform suitable for small agencies.
* **[PandaDoc](https://pandadoc.com)**: Comprehensive tool for creating, sending, and managing contracts with real-time tracking.
### Billing: Streamlined and Transparent
Once the contract is in place, billing becomes the critical step to ensure you're paid for your work. A professional and organized billing process reflects well on your agency and helps avoid delays or disputes.
##### Platforms for Invoicing
1. **[Stripe](https://stripe.com)**
* A versatile payment platform that allows you to generate invoices and accept credit card payments.
* Provides recurring billing options, making it ideal for retainer or subscription-based services.
* Supports multiple currencies for international clients.
2. **[QuickBooks](https://quickbooks.intuit.com)**
* An all-in-one accounting solution that includes invoicing, expense tracking, and reporting.
* Allows for integration with bank accounts and payroll services.
* Offers customizable invoice templates and automated reminders for overdue payments.
3. **[FreshBooks](https://freshbooks.com)**
* Tailored for small businesses and agencies, FreshBooks simplifies invoicing and payment tracking.
* Includes time-tracking features to bill clients for hourly work.
* Offers payment gateways like Stripe and PayPal for convenience.
4. **[Zoho Invoice](https://zoho.com/invoice)**
* A cost-effective tool for generating invoices, with features like recurring billing and multi-currency support.
* Integrates with the Zoho ecosystem, making it a great choice for agencies using other Zoho tools.
**Best Practices for Invoicing:**
1. **Be Timely:** Send invoices as soon as work is completed or according to the agreed schedule.
2. **Itemize Services:** Clearly list the services provided, their costs, and any applicable taxes or discounts.
3. **Include Payment Details:** Provide easy-to-follow payment instructions, including accepted methods and due dates.
4. **Set Payment Terms:** Use clear terms like “Net 15” (due in 15 days) or “Net 30” to avoid confusion.
5. **Automate Reminders:** Use invoicing tools to send automated reminders for unpaid invoices, reducing the need for manual follow-ups.
### The Importance of Contracts and Invoices Together
Each client you onboard will use Thoughtly to manage their calls, and each call costs [Credits](/platform/billing). While many agencies opt to cover their client's usage costs with higher fixed service fees, you can also pass these costs onto your clients. This is a great way to keep your own costs down, and it allows you to charge your clients based on their usage of Thoughtly.
There are three ways to track your client's usage of Thoughtly:
1. **Manual Reporting:** Each month, Thoughtly provides a detailed [Usage Report](/platform/settings) that details how many Credits were used by each client. You can use this report to bill your clients manually, but that's tedious.
2. **Automated Reporting:** Instead of manually pulling usage for each client, you can use [Automations](/automations/getting-started) to automatically send a webhook to your billing platform, CRM, or data warehouse to automatically keep a log of your client's usage. At the end of each billing cycle, you can tally up the total and add it as a line item on the invoice you send to your client.
3. **API:** If you want to get really fancy, you can use the [Thoughtly API](/developers) to automatically pull usage data for each client and send it to your billing platform. This is a more advanced solution, but it can give you more flexibility and remove the need for your own database of client data.
Typically, the final invoice you send to a client for any given month should be for their Thoughtly usage and additional fees for your services. The latter is typically a much larger portion of the invoice, and this is where you can make your money.
There are many ways to set up automated contracting and invoicing which we'll explore in the [Billing Your Clients](#billing-your-clients) portion of this guide.
### Integration
This is the most important part of your agency's success and where you can differentiate your agency from the competition. As previously mentioned, every small business uses their own unique set of software, tools, and processes to run their business. This is why it's so important to understand your client's needs and how they operate. Once you have a deep understanding of your client's needs, you can begin to build the integrations that will make your agency successful.
We have a number of [Guides](/getting-started/use-cases#use-cases-and-examples) to help you get started with building each use case. Each of our native [Integrations](/integrations) are built to be as easy to use as possible, and we are always adding new ones. If you need to build a custom integration, you can use our [API](/developers) to connect Thoughtly to any other software your clients use.
[Automations](/automations/getting-started) are a powerful way to connect Thoughtly to any other software your clients use. You can use Automations to send data to and from Thoughtly, and you can even use them to trigger actions in other software based on events that happen in Thoughtly. This is a great way to build custom workflows for your clients without writing any code. Many of our agency partners use [Make.com](https://make.com) to connect Thoughtly to unsupported software.
#### CRMs
Outside of Thoughtly, the most important core software your clients will use is their CRM. This is where all of their customer data is stored, and it's critical that you understand how to connect Thoughtly to your client's CRM. The most popular CRMs leveraged by our agency partners are:
* [**Salesforce**](/integrations/crm/salesforce)
* [**GoHighLevel**](/integrations/crm/highlevel)
* [**HubSpot**](/integrations/crm/hubspot)
* [**Zoho**](/integrations/crm/zoho)
* [**Keap**](/integrations/crm/keap)
* [**Pipedrive**](/integrations/crm/pipedrive)
#### Scheduling
Scheduling is another critical part of your client's business. Fortunately, we have a number of [Integrations](/integrations) to help you get started with connecting Thoughtly to your client's scheduling software. The most popular scheduling software leveraged by our agency partners are:
* [**Calendly**](/integrations/scheduling/calendly)
* [**Acuity Scheduling**](/integrations/scheduling/acuity)
* [**Mindbody**](/integrations/scheduling/mindbody)
* [**Cal.com**](/integrations/scheduling/cal-com)
***
## Thoughtly Features Deep Dive
To help you maximize the potential of Thoughtly and provide exceptional service to your clients, we've outlined a comprehensive deep dive into Thoughtly's features. Each feature is designed to streamline your operations, empower your clients, and differentiate your agency in a competitive market.
### Agent Builder
Thoughtly's [Agent Builder](/agents/overview) is the backbone of creating AI-powered voice agents for your clients. With this tool, you can design custom workflows tailored to the specific needs of each client.
**Key Features:**
* **Node-Based Configuration**: Design call flows with ease using drag-and-drop nodes. Nodes allow you to define actions, decisions, and outcomes, creating a logical conversation path. Example: Use the [Outcomes](/agents/outcomes) feature to route calls based on customer responses.
* **Variables and Context**: Personalize interactions with [Variables](/agents/variables), ensuring each conversation feels relevant. Example: Automatically greet a customer by name or refer to their specific account details.
* **Advanced Training and Rules**: Train agents to follow specific conversation guidelines using the Training and Rules module. Example: Ensure agents accurately handle objections or escalate calls to a live agent when needed.
**How it Helps:**
* Tailor agents to your client's unique workflows.
* Deliver personalized, efficient, and human-like customer interactions.
* Reduce onboarding time for new clients by reusing templates and modifying them.
### Automations
The [Automations](/automations/getting-started) feature allows you to connect Thoughtly with external tools and streamline repetitive tasks.
**Key Features:**
* **Triggers**: Automatically initiate workflows based on events such as call completions or specific customer responses. Example: When a customer confirms an appointment, trigger an email confirmation via their CRM.
* **Actions**: Perform tasks like updating CRM records, sending SMS reminders, or tagging customers in a database. Example: Use [Triggers and Actions](/automations/triggers) to integrate Thoughtly with [Salesforce](/integrations/crm/salesforce).
**How it Helps:**
* Minimize manual data entry and errors.
* Create seamless workflows that enhance productivity.
* Demonstrate tangible ROI to clients by integrating Thoughtly with their existing tools.
### Contact Management
The [Audiences](/platform/audiences) feature provides a centralized hub for managing customer information.
**Key Features:**
* **Unified Contact View**: Access detailed profiles for each contact, including call history, notes, and outcomes.
* **Integration Sync**: Automatically pull contact data from CRMs like [HubSpot](/integrations/crm/hubspot) or [GoHighLevel](/integrations/crm/highlevel).
**How it Helps:**
* Provide personalized customer experiences by leveraging rich contact data.
* Reduce friction for clients by syncing data across platforms.
* Use insights from call history to refine future interactions.
***
### Analytics and Reporting
Thoughtly's [Analytics](/platform/history) tools provide actionable insights into agent performance and customer engagement.
**Key Features:**
* **Call Metrics**: Track metrics such as call duration, response rates, and outcomes. Example: Identify high-performing call scripts based on conversion rates.
* **Custom Reports**: Generate reports tailored to client KPIs. Example: Showcase lead conversion improvements or time saved through automation.
**How it Helps:**
* Demonstrate the impact of your agency's work with data-driven results.
* Identify areas for improvement in call flows or agent scripts.
* Use visualized data to build trust and transparency with your clients.
### API Integration
For agencies with technical expertise, Thoughtly's [API](/api-reference) provides limitless customization opportunities.
**Key Features:**
* **Data Retrieval**: Pull real-time usage data or call transcripts directly into external systems. Example: Use the API to create a live dashboard that tracks call activity across multiple clients.
* **Custom Workflows**: Build bespoke automations that go beyond the capabilities of the Automations feature.
**How it Helps:**
* Differentiate your agency by offering highly customized solutions.
* Seamlessly integrate Thoughtly into complex client ecosystems.
* Build advanced reporting and data visualization tools for enterprise clients.
***
## Billing your Clients
Efficient and professional contracting and billing are critical to running a successful agency. They ensure clear communication with your clients, timely payments, and a smooth overall experience. Below, we'll walk through the steps, platforms, and best practices to help you streamline this aspect of your agency operations.
### Contracts: Setting the Foundation
Contracts protect both you and your clients by clearly defining the scope of work, responsibilities, and payment terms. They minimize misunderstandings and create a professional impression.
##### Key Elements of a Contract
1. **Scope of Work (SOW):** Clearly outline the services you'll provide, including specific deliverables (e.g., "Implement Voice AI solution to automate lead follow-ups").
2. **Payment Terms:** Specify the total cost, payment schedule (e.g., upfront, recurring, or milestone-based), and accepted payment methods.
3. **Timelines:** Include deadlines for project completion, milestones, or ongoing service periods.
4. **Termination Clause:** Define the terms under which the agreement can be terminated by either party.
5. **Confidentiality and Data Privacy:** Ensure compliance with data protection laws like GDPR or CCPA if applicable.
6. **Dispute Resolution:** Outline how disputes will be handled (e.g., arbitration, mediation, or legal action).
7. **Signatures:** Ensure both parties sign the agreement to make it legally binding.
**Recommended Tools for Contracts:**
* **[Salesbricks](https://www.salesbricks.com?utm_source=thoughtly)**: A CPQ (Configure, Price, Quote) tool that allows you to send customized contracts, quotes, and invoices to your clients. This is a great way to get started with contracts, and you can even use it to send invoices. This is what we use at Thoughtly, and we love it.
* **[DocuSign](https://docusign.com)**: Industry-standard tool for e-signatures and contract management.
* **[Dropbox Sign](https://sign.dropbox.com)**: Simple and affordable e-signature platform suitable for small agencies.
* **[PandaDoc](https://pandadoc.com)**: Comprehensive tool for creating, sending, and managing contracts with real-time tracking.
### Billing: Streamlined and Transparent
Once the contract is in place, billing becomes the critical step to ensure you're paid for your work. A professional and organized billing process reflects well on your agency and helps avoid delays or disputes.
##### Platforms for Invoicing
1. **[Stripe](https://stripe.com)**
* A versatile payment platform that allows you to generate invoices and accept credit card payments.
* Provides recurring billing options, making it ideal for retainer or subscription-based services.
* Supports multiple currencies for international clients.
2. **[QuickBooks](https://quickbooks.intuit.com)**
* An all-in-one accounting solution that includes invoicing, expense tracking, and reporting.
* Allows for integration with bank accounts and payroll services.
* Offers customizable invoice templates and automated reminders for overdue payments.
3. **[FreshBooks](https://freshbooks.com)**
* Tailored for small businesses and agencies, FreshBooks simplifies invoicing and payment tracking.
* Includes time-tracking features to bill clients for hourly work.
* Offers payment gateways like Stripe and PayPal for convenience.
4. **[Zoho Invoice](https://zoho.com/invoice)**
* A cost-effective tool for generating invoices, with features like recurring billing and multi-currency support.
* Integrates with the Zoho ecosystem, making it a great choice for agencies using other Zoho tools.
**Best Practices for Invoicing:**
1. **Be Timely:** Send invoices as soon as work is completed or according to the agreed schedule.
2. **Itemize Services:** Clearly list the services provided, their costs, and any applicable taxes or discounts.
3. **Include Payment Details:** Provide easy-to-follow payment instructions, including accepted methods and due dates.
4. **Set Payment Terms:** Use clear terms like “Net 15” (due in 15 days) or “Net 30” to avoid confusion.
5. **Automate Reminders:** Use invoicing tools to send automated reminders for unpaid invoices, reducing the need for manual follow-ups.
### The Importance of Contracts and Invoices Together
Contracts and invoices go hand-in-hand. While contracts establish the terms of your relationship, invoices operationalize those terms. Keeping both processes professional and streamlined enhances your agency's reputation and ensures smooth operations.
### Example Workflow for Contracting and Billing
1. **Contract Creation**: Use Salesbricks to configure a contract that includes a detailed scope of work, pricing, and timelines. Send it to the client for review and e-signature via DocuSign.
2. **Invoice Generation**: Once the contract is signed, create an invoice using QuickBooks or Stripe. Ensure it reflects the agreed payment terms.
3. **Payment Processing**: Accept payments via Stripe, which supports credit cards, ACH transfers, and international currencies.
4. **Automation**: Set up recurring invoices for retainer clients and automate reminders for overdue payments.
5. **Tracking and Reporting**: Use your invoicing tool's dashboard to track payment status and generate financial reports for internal use.
By maintaining transparency and professionalism in contracting and billing, you set the stage for a long-term, trust-based relationship with your clients. This process not only ensures your agency gets paid but also reinforces your brand as a reliable and organized partner.
***
## Legal and Compliance Considerations
As an AI agency, legal and compliance issues are paramount to your success. Failing to adhere to established regulations can not only damage your reputation but also lead to severe financial penalties and the potential loss of access to Thoughtly's platform. This section outlines critical compliance guidelines you must follow to protect your agency, your clients, and their customers.
### Understanding the Regulatory Landscape
The **Federal Communications Commission (FCC)** has taken significant steps to protect consumers and businesses from telemarketing fraud. As an AI agency using Voice AI solutions for outbound calls, you must ensure compliance with the following key regulations:
1. **Telephone Consumer Protection Act (TCPA)**
* The TCPA prohibits the use of AI-generated voices in robocalls unless explicitly requested by the recipient.
* Violations of the TCPA can result in significant financial penalties, making compliance non-negotiable.
2. **Telemarketing Sales Rule (TSR)**
* Managed by the Federal Trade Commission (FTC), the TSR sets strict requirements for telemarketing, including outbound calls made by businesses.
* Key requirements include disclosing the identity of the caller, providing the purpose of the call, and complying with restrictions on call timing.
3. **Do Not Call Registry**
* The National Do Not Call Registry prohibits telemarketing calls to numbers listed unless the recipient has provided explicit permission.
* It is your responsibility to verify that numbers are not on this registry before making any outbound calls.
4. **AI-Specific Regulations**
* The FCC has explicitly affirmed that using AI-generated voices in unauthorized robocalls is illegal. This applies to both consumer and business calls.
* Ensure that every call recipient has explicitly opted in to receive calls before initiating contact.
### How to Ensure Compliance
**1. Obtain Explicit Consent**
* **Written Consent:** Always collect clear, written consent from recipients before making any outbound calls. This consent must include acknowledgment of the use of AI in the call.
* **Document Consent:** Use CRM systems like Salesforce or HubSpot to maintain detailed records of consent for auditing purposes.
**2. Validate Your Contact List**
* **Check Against the Do Not Call Registry:** Regularly scrub your call lists to ensure no numbers are listed on the registry. Many platforms, such as CompliancePoint or Gryphon Networks, offer tools for list validation.
* **Segment Your Lists:** Use segmentation to ensure you are only calling individuals or businesses that have requested information.
**3. Stay Transparent**
* **Identify Yourself and Your Purpose:** Clearly state who you are, the organization you represent, and the purpose of the call within the first few seconds.
* **Disclose AI Usage:** Inform recipients that they are interacting with an AI agent and provide an option to speak with a human if requested.
**4. Train Your Team**
* Educate your team on the legal requirements of the TCPA, TSR, and Do Not Call regulations. Regular training can prevent unintentional violations.
**5. Use Thoughtly Features to Stay Compliant**
* **Call Documentation:** Thoughtly automatically logs and records calls, providing transparency and aiding compliance.
* **Opt-In Tracking:** Use automation tools in Thoughtly to confirm and log recipient consent before initiating any calls.
### Consequences of Non-Compliance
Non-compliance with these regulations can lead to:
* **Financial Penalties:** Violations of the TCPA can result in fines of up to \$16,000 per call.
* **Revocation of Platform Access:** Thoughtly reserves the right to revoke your access to our platform if you violate compliance requirements, as outlined in our [Terms of Use](https://thoughtly.com/terms). No refunds will be issued for revoked access due to non-compliance.
* **Legal Action:** Persistent violations could expose your agency to lawsuits, reputational harm, and loss of clients.
### Key Takeaway
*If the recipient of the call did not explicitly request the call, you should not make the call.*
By adhering to these compliance guidelines, you not only protect your agency from legal risk but also build trust with your clients and their customers. Always prioritize transparency, consent, and adherence to regulations as the foundation of your agency's operations.
***
## Client Retention
Client retention is the cornerstone of a successful AI agency. Acquiring new clients is costly and time-consuming, but retaining existing clients builds long-term stability and profitability. Retention is more than just delivering results—it's about fostering trust, providing ongoing value, and building lasting relationships. Below, we'll explore proven strategies to maximize client retention for your Thoughtly-powered AI agency.
### Consistent Communication
Transparent and frequent communication keeps clients informed, engaged, and confident in your services.
**Best Practices:**
* **Scheduled Check-Ins**: Set up regular calls or meetings to discuss performance, address concerns, and share updates. Weekly or biweekly check-ins work well for most clients.
* **Real-Time Updates**: Use Thoughtly's [Analytics Tools](/platform/history) to provide clients with data-backed insights, such as call outcomes, conversion rates, and cost savings.
* **Dedicated Point of Contact**: Assign a dedicated account manager for each client to ensure personalized attention and quick resolution of issues.
**Example:** Schedule a quarterly business review (QBR) to discuss progress against KPIs, present new opportunities for AI solutions, and reinforce your value.
### Deliver Tangible Results
Consistently demonstrating value is essential for client satisfaction and retention.
**Best Practices:**
* **Set Clear Goals**: Define success metrics during onboarding, such as call conversion rates or customer satisfaction scores.
* **Regular Reporting**: Share progress reports through in-person presentations or custom reports. Highlight measurable results like leads captured, calls handled, and time saved.
* **Proactive Recommendations**: Use insights from [Automations](https://thoughtly.com/docs/automations/getting-started) and analytics to suggest optimizations and improvements.
**Example:** A real estate client may see a 20% increase in appointment bookings within three months. Present this data visually in a custom report, emphasizing how your solutions directly impacted their business.
### Build Strong Relationships
Clients are more likely to stay with agencies that feel like partners rather than service providers.
**Best Practices:**
* **Understand Their Business**: Invest time in learning your client's industry, challenges, and goals. Tailor your solutions to align with their broader objectives.
* **Celebrate Milestones**: Recognize key achievements, such as reaching lead generation goals or launching a new product.
* **Personal Touches**: Send handwritten notes, personalized gifts, or holiday cards to show appreciation and build rapport.
* **Trigger Functionality**: Integrate Thoughtly seamlessly into your clients' marketing workflows to automatically call new leads. Example: Connect Thoughtly to Zapier or Make.com to start automations when a form is submitted. Learn more from our [Automations Documentation](/automations/triggers).
### Offer Ongoing Training and Support
Empower clients to maximize the use of Thoughtly tools while ensuring they feel supported at every step.
**Best Practices:**
* **Customized Training**: Offer training sessions tailored to your client's specific needs. Use the [Agent Builder](https://thoughtly.com/docs/agents/overview) as a hands-on example to guide them.
* **Knowledge Base Access**: Direct clients to Thoughtly's comprehensive [Documentation](https://thoughtly.com/docs/) and [API Reference](https://thoughtly.com/docs/api-reference) for self-service learning.
* **24/7 Support**: Provide responsive support via email, chat, or phone to address issues quickly.
**Example:** Offer monthly training webinars for clients who onboard new team members, ensuring their entire staff stays proficient in using Thoughtly's features.
### Upsell and Expand
Retaining clients doesn't just mean keeping them happy—it also means growing the relationship by offering additional services.
**Best Practices:**
* **Identify New Opportunities**: Regularly review your client's evolving needs and propose relevant upgrades or add-ons.
* **Offer Pilot Programs**: Introduce new features like AI-powered SMS campaigns or advanced integrations on a trial basis.
* **Bundle Services**: Create packages that include additional automations, custom integrations, or premium support.
**Example:** If a client uses Thoughtly for inbound calls, suggest adding an outbound campaign for appointment reminders to further streamline their operations.
### Leverage Client Feedback
Listening to your clients' feedback not only helps improve your service but also strengthens their trust in your agency.
**Best Practices:**
* **Surveys and Reviews**: Regularly collect feedback through surveys or informal check-ins to understand client satisfaction and areas for improvement.
* **Implement Changes**: Act on feedback promptly, and communicate the changes you've made as a result.
* **Encourage Testimonials**: Happy clients are your best advocates. Ask them to provide testimonials or participate in a case study.
**Example:** If clients request better visibility into AI performance, create custom reports or dashboards in their CRM to display call success rates and agent engagement metrics.
### Proactively Address Challenges
Clients appreciate agencies that tackle problems head-on rather than waiting for issues to escalate.
**Best Practices:**
* **Monitor Performance**: Use Thoughtly's [Real-Time Reporting](/platform/history) to catch potential issues early.
* **Action Plans**: If performance dips, create a clear action plan and communicate it to the client.
* **Transparent Communication**: Be honest about challenges and work collaboratively with the client to resolve them.
**Example:** If a new AI script underperforms, schedule a meeting to review the data, identify the issue, and propose improvements.
### Foster Community and Engagement
Clients who feel part of a larger community are more likely to stay loyal.
**Best Practices:**
* **Client Events**: Host exclusive webinars, workshops, or Q\&A sessions to showcase new features and best practices.
* **Peer Networking**: Connect clients with similar businesses for shared insights and mutual support.
* **Social Media Engagement**: Highlight client successes on Thoughtly's social platforms to build community and celebrate achievements.
**Example:** Create a “Client Spotlight” series that features success stories, tips, and testimonials from your top clients.
### Why Client Retention Matters
Retention is not about holding clients hostage—it's about creating partnerships so valuable they wouldn't think of going elsewhere. By focusing on consistent communication, delivering results, and fostering strong relationships, your agency can build a loyal client base that drives sustainable growth. Remember, every satisfied client is not just a win but an advocate for your agency, helping you grow organically through referrals and trust.
***
## Conclusion
Building and scaling an AI agency is a unique and rewarding opportunity to shape the future of business operations in an AI-first world. As businesses increasingly adopt innovative technologies like Thoughtly's Voice AI, the demand for skilled agencies capable of seamlessly integrating these tools into existing workflows is higher than ever.
Throughout this whitepaper, we've outlined the key steps to establish and grow your AI agency, from identifying your core competency to mastering client retention strategies. Along the way, we've explored how Thoughtly's tools, features, and resources can empower you to deliver exceptional results, differentiate your agency, and foster lasting client relationships.
At its heart, the success of your AI agency will hinge on your ability to solve meaningful problems, deliver tangible value, and create trusted partnerships. By leveraging Thoughtly's robust platform, from the Agent Builder to advanced analytics and automations, you'll have the resources you need to not only meet your clients' expectations but to exceed them.
As you embark on this journey, remember that you are not alone. Thoughtly is here to support you with tools, training, and a vibrant community of like-minded agency owners through the [Thoughtly Referral Program](/support/referral-program). Together, we can drive the adoption of AI solutions that transform businesses and unlock new levels of efficiency, scalability, and customer satisfaction.
The future of Voice AI is here, and the agencies that adapt and innovate will lead the way. It's time to take the first step in building a lasting legacy in this new frontier. Thoughtly is ready to help you every step of the way. Let's shape the future—together.
### Start building
If you haven't done so already, you'll need to [create a free account](https://app.thoughtly.com) to get started. Once you're in, continue to the [Agent Builder](/agents/overview) to start building your first Voice Agent.
# Breaking free from intent-based dialog design
Source: https://docs.thoughtly.com/resources/whitepapers/conversational-ai
Learn how Thoughtly stands out from traditional intent-based dialog design and delivers a more natural, engaging customer experience on the cutting edge of AI.
By Torrey Leonard, Founder of Thoughtly
## Introduction
Thoughtly's generative, conversational AI is a powerful tool for enhancing customer experience, moving beyond traditional intent-based limitations. By combining state-of-the-art LLMs with advanced voice synthesis thanks to transformer-based voice AI models, Thoughtly creates interactions that are adaptive, realistic, and remarkably effective. With thoughtful training and continuous refinement, your Thoughtly Voice Agent will deliver outstanding, human-like conversations that transform your customer interactions.
Instead of having to pre-program every possible interaction, Thoughtly's AI learns from vast datasets to understand and generate language dynamically. This allows it to handle a wide range of queries, adapt to conversational nuances, and provide responses that feel natural and engaging. While achieving 100% predictability is statistically improbable due to the probabilistic nature of generative systems, Thoughtly's AI offers a highly effective and flexible solution for delivering exceptional customer service.
## How Thoughtly Works
Thoughtly's voice AI system harnesses cutting-edge technology to create an unmatched customer experience through dynamic, conversational interactions. Unlike traditional intent-based dialog systems that rely on [Natural Language Understanding (NLU) models](https://en.wikipedia.org/wiki/Natural_language_understanding), Thoughtly leverages generative [large language models (LLMs)](/resources/glossary#large-language-model) to provide responses that feel natural, flexible, and human-like.
### From Intent-Based Systems to Conversational AI: A New Era
Intent-based systems are designed to recognize specific inputs and match them to pre-programmed "intents." Once an intent is identified, the system triggers a fixed response written manually by the designer of the given dialog system. While effective for handling predictable, repetitive interactions, intent-based systems have limited flexibility. They're constrained by the defined intents and don't adapt easily to unexpected or nuanced queries. This approach can make conversations feel robotic and can be frustrating when callers step outside the anticipated dialogue paths.
Thoughtly, on the other hand, is powered by generative LLMs that offer a far more flexible, conversational approach. By leveraging advanced models from OpenAI, Meta (LLaMA), Mistral, and Anthropic, Thoughtly's AI adapts in real time to the unique phrasing and needs of each interaction. **This approach is similar to hiring a human agent: while an agent is trained on company policies and customer service best practices, they aren't restricted to scripted responses and can adjust dynamically to any conversation.** Thoughtly's AI provides a similar experience, drawing on its extensive training to respond naturally and intelligently to each caller's needs.
This human-like approach to Thoughtly's outputs is what makes it so well-equipped to handle both sales conversations and more advanced support calls.
This shift represents a technological breakthrough, enabling Thoughtly to deliver conversations that flow naturally, adapt to varied input, and create an engaging, frictionless CX. With its ability to understand complex language patterns, Thoughtly's conversational AI can handle a far broader range of queries than traditional, intent-based systems, offering a more satisfying and intuitive interaction experience.
### How Large Language Models (LLMs) Work
At the heart of Thoughtly's conversational AI are large language models (LLMs), which function fundamentally differently from intent-based systems. LLMs use a sophisticated neural network architecture known as a **transformer**, which enables them to understand and generate language based on probabilities rather than pre-set rules.
1. **Self-Attention and Context Awareness**: LLMs use a self-attention mechanism that helps the model dynamically “focus” on relevant parts of the input text, enabling it to understand context, relationships, and nuances across a conversation. This contextual awareness allows the AI to provide responses that are adaptive, relevant, and coherent, even in complex interactions.
2. **Probabilistic Response Generation**: Unlike traditional rule-based systems, LLMs generate responses based on probabilities. They evaluate multiple possible next words (or tokens) and select one based on its likelihood in the given context. This makes each response unique, adaptive to the conversation, and more human-like. However, it also means responses aren't fully deterministic, making absolute predictability impossible.
3. **Trained on Vast Data**: Thoughtly's LLMs have been trained on extensive, diverse datasets, which allow them to understand and generate language effectively across many contexts. This broad training makes Thoughtly's AI highly flexible, allowing it to handle a wide variety of inputs without requiring explicit programming for each scenario.
While these attributes make Thoughtly's AI impressively dynamic and capable, they also introduce an inherent variability. Because responses are generated based on probability, achieving perfect outputs 100% of the time is statistically improbable. Just as a human conversation partner may occasionally misunderstand a question or need clarification, Thoughtly's AI may sometimes produce a response that could be refined.
### Voice AI: Generative Speech with Transformer-Based Models
Thoughtly's AI system doesn't stop at understanding and generating responses; it also translates these outputs into natural-sounding speech. Once the LLM generates a response, Thoughtly uses transformer-based Voice AI [text-to-speech (TTS) models](/resources/glossary#tts) to convert text outputted by language models into audio in real time. These models enable a rich, human-like vocalization, providing customers with a seamless, fully generative experience.
However, like any generative system, there is a degree of variability in each response. Because these voice models work probabilistically, they don't reproduce identical outputs every time. This variability, while making interactions feel more natural, can sometimes result in responses that don't fully align with the intended outcome. Thoughtly minimizes these by monitoring, fine-tuning, and updating models, but complete perfection isn't statistically achievable in generative systems.
Just like human phone calls, no two Thoughtly conversations will ever be exactly the same, from what is being said to voice tonation. This is the future of Conversational AI and dialog design systems.
### Why 100% Coverage is Statistically Improbable
Given how LLMs work, achieving 100% coverage is statistically improbable. Here's why:
* **Probabilistic Response Generation**: Responses are generated based on statistical probabilities rather than deterministic paths. This allows for natural, varied conversation but also means occasional unexpected outputs.
* **Contextual Sensitivity**: LLMs respond dynamically to context, which can change based on subtle variations in phrasing, tone, or past interactions. This variability introduces minor, sometimes unpredictable shifts in responses that may not always perfectly align with expected outcomes.
* **Broad Language Understanding**: Thoughtly's models are trained on a vast range of language patterns, enabling them to respond flexibly but also making it difficult to predict every possible conversational direction. Just as a human agent may encounter scenarios they weren't trained for, Thoughtly's AI will occasionally face unforeseen conversational contexts.
For applications where consistent, precise responses are critical, Thoughtly recommends providing rules to your Voice Agent to ensure that it is aware of the strict guidelines it must follow. For example, provide your Voice Agent with a language that should be completely avoided to ensure that it doesn't say anything that could be considered "off-brand."
Additionally, enabling fallback to human agents ensures that while Thoughtly's AI handles the majority of interactions smoothly, any truly unique or unpredictable scenario can be directed to a live representative, maintaining a high standard of customer experience.
By using a product that utilizes generative language models, you acknowledge a minimal risk of occasional unexpected outputs. With Thoughtly, however, this risk is minimized through product guardrails and is likely lower than what may occur with human agents.
By leveraging Thoughtly's LLM-powered conversational AI and following the recommended training and monitoring steps, you can create a highly effective virtual agent that delivers outstanding CX with minimal variance—while recognizing that a small degree of unpredictability is a natural and even beneficial part of creating a human-like conversational experience.
### Training Your Thoughtly Voice Agent: A Step-by-Step Guide
To maximize the effectiveness of your Thoughtly Voice Agent, we recommend a strategic training approach that builds from core conversations to more nuanced interactions. Follow these steps to create a high-performing virtual agent:
Begin by creating a conversation flow that covers the most common, straightforward scenarios—often referred to as the “happy path.” Focus on interactions that make up roughly 60% of expected conversations. This provides your agent with a solid foundation and ensures it performs well in common scenarios from day one.
Once the happy path is performing smoothly, begin to identify and address edge cases. These might include less frequent inquiries, unusual phrasing, or specific customer needs that fall outside standard interactions. Expanding to these edge cases brings your agent's handling capabilities closer to 90%, significantly improving its ability to manage a variety of scenarios.
Expose a test line to your team internally to gather feedback on how the agent performs in these edge cases. This feedback loop is crucial for identifying gaps and refining responses.
When your agent is handling a diverse set of scenarios effectively, you're ready to go live with customers. For the first 30 days, monitor calls closely to identify any interactions where the agent's response may have fallen short or could be improved. This period allows you to gather real-world data on how the agent performs under a variety of circumstances.
As you spot gaps or errors in responses, you can make updates directly on Thoughtly. By training your agent or providing the agent with up-to-date information, you can address most observed issues. This iterative refinement process will bring your agent's coverage to around 99%.
While Thoughtly's conversational AI can cover an impressive range of queries, reaching 100% is statistically improbable. No system, human or AI, can anticipate every possible interaction. For cases where achieving complete coverage is critical, Thoughtly recommends providing rules to your Voice Agent to ensure that it is aware of the strict guidelines it must follow. For example, provide your Voice Agent with a language that should be completely avoided to ensure that it doesn't say anything that could be considered "off-brand."
By following these steps, you'll develop a high-performing Thoughtly Voice Agent capable of handling a broad range of customer inquiries with ease, flexibility, and exceptional quality.
## Start building
If you haven't done so already, you'll need to [create a free account](https://app.thoughtly.com) to get started. Once you're in, continue to the [Agent Builder](/agents/overview) to start building your first Voice Agent.
# Thoughtly whitepapers
Source: https://docs.thoughtly.com/resources/whitepapers/overview
Read Thoughtly whitepapers on conversational AI, voice agent design, and building an AI agency — practical insights into the technology behind the platform.
Read our whitepapers to learn more about Thoughtly's underlying technology and how it can help your business.
***
[Breaking Free from Intent-Based Dialog Design: The Power of Thoughtly's Conversational AI](/resources/whitepapers/conversational-ai)
*Learn how Thoughtly stands out from traditional intent-based dialog design and delivers a more natural, engaging customer experience on the cutting edge of AI.*
***
[So, You Want to Start an AI Agency?](/resources/whitepapers/agency-guide)
*Learn how to build and scale an AI agency with Thoughtly's insights and best practices, from identifying your target market to providing transparency.*
***
# Changelog
Source: https://docs.thoughtly.com/support/changelog
Stay up to date with the latest Thoughtly releases — new features, integrations, agent improvements, and platform changes shipped each month.
## Code Node for Everyone, plus MCP ⚡
June's headline: **Code Node is now available to all teams.** Write custom JavaScript that runs in a secure sandbox, right inside your automations and live calls. Transform data, call external APIs, and shape logic exactly the way your workflow needs it. Get started with the [Code guide](/integrations/developer/code).
### 🚀 What's New
**Code Node, now generally available** 💻\
Custom JavaScript in automations and mid-call actions, running in a secure sandbox. If your workflow needs logic that goes beyond drag-and-drop, this is it.
**Thoughtly MCP server, in limited availability** 🔌\
Connect your favorite AI tools to Thoughtly through the new [MCP server](/integrations/developer/mcp), with team selection and role-based tool access so every connection sees exactly what it should. Rolling out progressively; contact your account team for access.
### 🛠️ Fixes & Polish
* Edits in progress are no longer lost when working in the contact detail panel.
* Automations no longer save stale input data on live workflows, and conditional nodes are more stable.
* Clearer error messages when a Twilio carrier configuration is invalid.
* History page filtering, sorting, and transcript viewing are smoother and more reliable.
* Faster saves on large flows and faster load times on Library and export pages.
* Fixed custom SIP headers being sent incorrectly on Telnyx connections.
* Fixed webhook signature verification for v2 API tokens.
* Automation canvas auto-layout no longer overlaps disconnected trigger nodes.
### 🧹 Cleanup
We removed a few outdated features and legacy flows as part of ongoing platform housekeeping. If you have questions about anything that changed, reach out to your account team.
## Reliability Across the Board 🛠️
May was a quality month: no splashy launches, just a long list of fixes across billing, integrations, calling, and messaging to make the platform more dependable every day.
### 🔧 Fixes
* Fixed incorrect trial-expiration billing errors for teams with granted credits.
* HubSpot and Salesforce sync no longer drops empty fields when creating or updating records.
* Fixed GoHighLevel reconnects creating duplicate connections.
* Fixed calls to Indian (+91) numbers being cut short, and improved call timeouts to Korean numbers.
* SIP calls that don't get picked up are no longer misreported as failures.
* Fixed an issue that could block iMessage traffic, plus opt-out handling improvements for iMessage via Linq.
* The Send SMS action now reliably shows all active phone numbers.
* Fixed automations with loop nodes producing phantom failures.
* Fixed a crash when deleting a Genius knowledge source.
* Tightened API responses so sensitive integration credentials are never exposed.
## Omnichannel Agents, Beta Access, and Workflow Control ✨
This release brings together the major customer-facing platform updates shipped across March and April: richer omnichannel messaging, a dedicated beta environment for testing new features, consent controls, stronger automation primitives, improved CRM workflows, and clearer reporting.
### 🌐 Omnichannel agents
Thoughtly now supports a broader omnichannel model across voice, SMS, WhatsApp, iMessage (via Linq), email, webhooks, CRM sync, and automations. The docs now explain how these channels fit together around the same agent, contact, variable, history, and outcome model.
* New [Omnichannel agents](/platform/omnichannel) overview
* New [WhatsApp Business](/integrations/communication/whatsapp-business) setup guide
* New [iMessage / Linq](/integrations/communication/imessage-linq) messaging guide
* New [Email domains](/platform/settings/email-domains) setup and DNS troubleshooting guide
### 🧪 Beta environment for new features
Thoughtly now has a dedicated beta environment where selected teams can test new capabilities before they are promoted to production. Beta access gives customers and internal teams a safer place to validate workflows, share feedback, and confirm behavior before a broader rollout.
* Beta features are available in the beta environment first
* Production remains the stable environment for live workflows
* Contact your Thoughtly account team if you need beta access for a specific feature
* New [Dark windows](/platform/settings/dark-windows) guide for quiet hours
### ✅ Consent, suppression, and safer outbound
Audience settings now include clearer guidance for consent mode, per-channel suppression, opt-out keywords, suppressed History records, and how these controls affect outbound calling and messaging.
Suppressed calls and messages are documented as compliance-blocked activity rather than generic failures, making reports easier to interpret.
### 🛠️ Automations and extensibility
Automations gained stronger support for dynamic values, webhook validation, rate-limit retries, Send Email, Send SMS, Salesforce update requirements, CRM behavior, and the new Code integration.
* Dynamic variables in more numeric, date, prompt, and instruction fields
* Webhook trigger validation and manual-trigger guidance
* Automatic retry behavior for `429` webhook responses
* New [Code](/integrations/developer/code) guide with sandbox limits and examples
* Updated Salesforce, HubSpot, and GoHighLevel integration notes
### 🤖 Agent builder, Vibes, and voice improvements
New agent docs cover Vibes as a guided AI assistant, call screening bypass, early summaries for handoffs, richer testing metadata, channel-aware variables, and updated ElevenLabs BYOK behavior.
* New [Vibes AI assistant](/agents/vibes-assistant) guide
* New [Call screening bypass](/agents/call-screening-bypass) guide
* New [Branded calling](/phone-number/branded-calling) guide
* Updated testing, variables, voice selector, and BYOK docs
### 📊 History, analytics, roles, and billing clarity
History docs now explain statuses, filtering, exports, and why completed calls should not be treated as success by default. Platform docs also now clarify beta features, workspace roles, developer settings, Flex/Enterprise billing, AppSumo billing, and granted-credit trial behavior.
### 🧹 Reliability and polish
This release also rolls up many smaller improvements that do not need standalone docs pages: dashboard polish, duplicate invite fixes, navigation fixes, export stability, call pickup fixes, iMessage consent fixes, webhook/iMessage opt-out fixes, and dependency/security patches.
## Your Voices, Your Variables, Your Platform 🚀
March was our biggest month yet for customization and control. You can now bring your own ElevenLabs voices to Thoughtly and drop dynamic variables into nearly every part of the builder. We also shipped a long list of scheduling, reliability, and polish improvements across the dashboard.
### 🔑 Bring Your Own ElevenLabs Voices
This is the one we've been waiting to ship. You can now connect your own ElevenLabs account to Thoughtly, which means your agents can speak in the custom voices you've already cloned, and voice usage runs on your ElevenLabs plan. For teams that have invested in a distinctive brand voice, this is the cleanest path yet to putting it on live calls. A built-in **Test Connection** button confirms everything is wired up before you save. See [Voice BYOK](/agents/voice-byok) to get started.
### 🧠 Variables in More Places
Variables are the backbone of truly dynamic agents, and this month we brought them to three of the most-requested parts of the builder. Rolling out progressively:
* **[Advanced Prompt](/agents/settings)** now accepts variables, filled in with real values at call time.
* **[Extraction Instructions](/agents/variables)** let you drop variables straight in through the data picker.
* **[Transfer Node Extensions](/agents/nodes)** support variables and metadata, matching how the Phone Number field already works.
The principle is simple: if a field takes text, it should take your data.
### 📅 Smarter Scheduling with Cal.com & Calendly
**[Create Booking](/integrations/scheduling/cal-com)** (Cal.com) and **[Schedule Event](/integrations/scheduling/calendly)** (Calendly) no longer require a Check Availability node on your agent canvas. You can now fetch availability in an automation before the call starts and pass it to the agent, so the booking flow is ready from the moment the conversation begins. Cleaner canvases, faster scheduling, and no awkward in-call latency while the agent waits for a calendar to respond.
### ✨ A More Polished Dashboard
We put real investment into the everyday experience this month:
* **[Test Agent text chat](/agents/testing)** now lets you set example metadata values, so you can test how your agent handles real caller info without making a call.
* **Cartesia voice volume** is adjustable directly in voice settings.
* **Uninterruptible opening messages.** A new option on the start node lets your agent finish its greeting without being cut off.
* **Automations retry automatically** when they hit a temporary rate limit, instead of failing on the first try.
* **Last Call column** on the Agents table makes it easy to spot inactive agents. Shared response pages now show the agent name and node number.
* **Global filters** are coming to the History page, matching the filtering experience elsewhere in the dashboard.
* **Unified button styling** across the dashboard, a redesigned help menu and keyboard shortcuts panel, and clearer error messages for invalid number inputs.
* **Searches on Agents and Automations pages** no longer carry over between pages unexpectedly.
* **More accurate call duration tracking** for better reporting on short calls.
### 🛡️ Continued Investment in Reliability
We care a lot about making Thoughtly feel fast and dependable, and this month we landed several fixes that you should notice right away:
* **Europe is fast again** on agent and contact creation.
* **No more missing recordings** on long calls.
* **SMS usage is counted correctly** in usage reports.
* **Contact creation is reliable again** and no longer returns blank data.
### 🧭 Legacy v1 Agents Are Now Read-Only
As part of our ongoing v1 wind-down, v1 agents are now locked down for most fields. Transfer numbers and titles remain editable, but the rest is protected to prevent accidental edits on stable production configurations. Rolling out progressively. If you're still on v1, the [v1 migration guide](/agents/migration-guide) walks you through planning your move.
### 🧯 Additional Fixes
* The variable picker no longer crashes when a node points to an integration that's been removed.
* The agent rule builder correctly replaces variables instead of adding them side-by-side.
* Switch and Filter nodes no longer crash when a condition is left blank.
* Webhook nodes now correctly report rate-limit errors and retry automatically.
* Voicemail detection on Telnyx now handles greetings in the right order.
* Only one recording plays at a time on the History page.
* The Billing page now shows the correct plan and subscription button for Flex and Enterprise customers.
* Fixed a regression where some agent sub-pages (responses, deploy, phone, widget) stopped loading correctly.
### 🔮 Looking Ahead
Everything we shipped this month was groundwork. Next month, we're launching the biggest release in Thoughtly's history. More soon. 👀
## UI v2, Voices, and Scheduling Improvements ✨
This month focused on a major UI refresh, more expressive voice delivery, smoother scheduling, and reliability upgrades across core workflows.
### ✨ UI v2
UI v2 is now rolling out as a comprehensive redesign of the dashboard built for clarity, performance, and scalability.
The new experience introduces a cleaner visual system, improved navigation patterns, more consistent layouts, and refined table interactions across the platform. Workflows are more intuitive, transitions are smoother, and the overall experience is more cohesive.
### 🎙️ Expressive Voices with Cartesia
We’ve introduced Cartesia real-time streaming voices, delivering more expressive, natural, and dynamic conversations.
Agents now benefit from richer tone, improved pacing, and more engaging delivery on live calls. Voice speed controls provide additional flexibility, and the rebuilt Voice Picker and Voice Library make it easier to discover, preview, and manage voices.
### 📅 Improved Meeting Scheduling
Meeting booking is now more streamlined and user-friendly, with a simplified scheduling experience that reduces friction and makes coordinating calls easier.
### 🧠 Calling & Conversation Enhancements
Voicemail handling is more reliable and cleaner, agents clearly identify as AI when asked, and re-engagement prompts now align more consistently with the selected conversation language.
### 🔧 Additional Improvements
**Agent Builder & Editing**
* More reliable saving and syncing in the Agent Editor.
* Improved mid-call action management with clearer controls.
**History & Reporting**
* Call logs now display accurate timestamps.
* History navigation and filtering improvements for smoother review.
**Accounts & Access**
* More stable onboarding flow and team management.
**Automations**
* Dynamic and nested inputs load more reliably.
* Loop execution is more resilient and less prone to getting stuck.
**Integrations**
* Improved reliability for HubSpot integration.
* Cal.com integration updates and general integration stability improvements.
**UI Polish**
* Copy and labeling improvements across settings (including clearer workspace vs profile wording).
* General UI consistency and performance improvements across key pages.
## Smoother, Clearer, More Polished ✨
This month was all about making the dashboard feel faster, cleaning up UI, and removing confusing edge cases.
### 🛠️ Platform Improvements
**✨ Better Outcomes experience**\
Creating and editing Outcomes is now cleaner and easier to understand, with improved layout and clearer options.
**⚡ Faster, simpler Agent Builder**\
The Agent Builder feels lighter when working with actions — less clutter, quicker to navigate.
**📊 Cleaner tables + column resizing**\
Dashboard tables now look more consistent, and you can resize columns to fit your workflow.
**📱 Phone Numbers page loads more predictably**\
Less “empty state flashing,” clearer loading behavior, and a smoother experience when numbers are syncing.
**🔗 Webhook settings show saved values immediately**\
No more opening a config and seeing a blank field until you click around — saved values appear right away.
**🧭 More consistent page headers**\
Search + header patterns across the dashboard are now more unified, so pages feel more consistent.
**🧾 Team status pages (Deleted / Trial Ended)**\
If a team is deleted or a trial ends, you’ll now see a clear page explaining what happened and what to do next.
**🔌 Disconnect carriers from the dashboard**\
You can now disconnect an existing phone carrier connection directly from the Phone Numbers page, with a confirmation step so you don’t remove numbers by accident.
### 🧯 Bug Fixes & Reliability
A long list of fixes across calls, voicemail, messaging, automations, permissions, and integrations — focused on making everyday usage more reliable and reducing weird edge-case behavior users were hitting.
## Winter Polish ❄️✨
December focused on workflow flexibility, telephony setup, and UI clarity. We also delivered a long list of fixes across automations, integrations, and calls.
### 🚀 What's New
**In-dashboard Telnyx number purchases** ☎️💳\
You can now buy Telnyx phone numbers without leaving the dashboard.
**Draft-mode automation runs** 🧪⚡\
The Run Automation button is now available in Draft mode for quicker testing.
**Post-call triggers by agent** 🎯🤖\
Post-call triggers can target all agents or only selected agents.
**Recursive variables** 🧩🔁\
Nested variable interpolation is now supported for more powerful workflows.
### 🛠️ Platform Improvements
**Manage columns in tables** 📊👀\
Customize table views with a new Manage Columns control.
**Automation builder polish** ✨🧱\
Canvas toolbar and Speak action slideover updates make editing faster and clearer.
**Faster automations and dialing** ⚡📞\
Automations pages load faster, and outbound dialing starts more quickly.
### 🧯 Reliability & Fixes
* Fixed duplicate phone-number charges and improved transfer messaging.
* Resolved automation builder issues with node deletion sync and trigger UI.
* Improved integration stability, including GoHighLevel, Cal.com, and integration account refresh.
* Addressed SMS system variable gaps, conversation history formatting, and select component issues.
* Fixed UI issues with voices page loading, pagination visibility, onboarding modals, and trial redirects.
* Refined silence timeout behavior and reduced unnecessary reprompts.
## Reliable Everyday Tools 🛠️✨
We focused on making your everyday tools more reliable and predictable.
### 🚀 What’s New
**Variable Extraction** 📅⏰\
Date and time extraction is now more accurate across voice and text. It handles relative phrases like “this Friday” or “next week” better, and the **Extract fields** action is back with improved stability.
**Voice Agent Improvements** 🎙️⚡\
We upgraded the underlying model for voice calls, delivering faster, more consistent responses and better variable extraction.
**Calendly Integration** 📆🌍\
Scheduling now features improved timezone handling, booking flows, and clearer error messages. You can now use variables for both desired time and timezone.
**Cleanup** 🧹\
Unused delay time fields were removed from **Call Phone Number** and **Call Contact** nodes. Batch jobs have been sunset — build these workflows with **Automations** instead. See the [Call tagged contacts automation guide](/resources/outbound-automation-tagged-contacts).
## Faster, Smarter, and More Connected ⚡
October brought major upgrades across performance, integrations, and usability. Our small engineering team has delivered a faster, more reliable platform — plus a brand-new documentation experience to help you build better with Thoughtly.
### 🧠 What's New
**Cal.com Integration** — Use **Cal.com** alongside Calendly for scheduling. Supports dynamic links, time zones, and physical location mapping for smoother appointment booking.
**Cartesia Sonic-3** — Experience expressive, natural-sounding voices with adjustable speed and loudness for more human-like interactions.
**Dynamic Genius Selection in Automations** — Automations can now choose specific Genius databases per call, improving context accuracy and eliminating “catch-all” confusion.
**Multi-Account Integrations** — Connect multiple accounts per integration (e.g., Cal.com, Calendly) for flexible multi-brand or multi-workspace setups.
**Smarter Transfers** — Transfer nodes now support dynamic variables and metadata keys for cleaner, more contextual hand-offs between AI and human agents.
**Documentation Overhaul** — Our docs got a complete makeover! Clearer guides, real-world examples, and intuitive structure make building with Thoughtly faster than ever.
### ⚙️ Platform Improvements
Performance upgrades to call initialization, automation concurrency, and variable extraction make the platform faster, smoother, and more consistent overall.
### 🔧 Reliability & Fixes
Various fixes for Telnyx call handling, automations, multi-tenancy, and outbound agent flows — improving reliability across the platform.
### 💡 Quality of Life
Enhanced Telnyx billing transparency for short-duration calls, refined scheduling UX for Cal.com and Calendly, and improved analytics via PostHog integration.
### 🔮 Coming Soon
We’re adding **Cartesia emotion controls**, and some cool, very **cool** stuff, so stay tuned 😉.
## Faster & More Reliable 🚀
September focused on speed and stability. We've dramatically reduced call connection times, enhanced platform reliability, and fixed critical issues reported by customers. These improvements make your agents faster, smarter, and more dependable than ever.
### 🛠️ Platform Enhancements
**Smarter Transfers** - A redesigned transfer experience with a cleaner UI, dynamic variables in the transfer destination, and more reliable handoffs to human agents.
**Genius in Automations** - Automations can now trigger specific Genius databases per call based on specific conditions via the Call Phone Number node. This prevents a single, massive “catch-all” Genius from causing hallucinations and helps agents provide more accurate responses.
**Updates to Calendly V2 API** - Fixed all timezone, location, and scheduling edge cases through direct partnership with Calendly.
**Enhanced Variable System** - Improved extraction logic, better loop handling in conditional navigation, and fixed display issues for smoother workflow building.
### 🔧 Critical Fixes
* **Telnyx Reliability** - Resolved concurrency failures, duplicate call initialization, and codec handling issues
* **Multi-Tenancy** - Fixed Connect to Agent tenant ID problems and improved account isolation
* **Automation Engine** - Fixed stuck logs, improved credit limit enforcement, and enhanced CRON trigger reliability
* **UI/UX Polish** - Fixed agent library pagination, summary displays, PDF uploads in Genius, and export functionality
* **Bulk Operations** - Significantly faster processing with improved error handling
### 💡 Quality of Life
* **Improved Telnyx Billing** - Enhanced short-duration call tracking for transparent, precise usage reporting
* **Better Team Management** - Streamlined team deletion workflows and improved our team member invite system
### 🔮 Coming Soon
We're working on a complete documentation revamp to make building with Thoughtly even easier. Expect clearer guides, more examples, and better organization to help you get the most out of the platform.
## Smarter Conversations 🧠
This August, we introduced game-changing navigation capabilities that make your agents more intelligent and responsive. Our team delivered significant improvements to speech recognition, call quality, and automation reliability. We've also completed our migration to Telnyx as our primary telephony provider, bringing better call quality and features to all users. These updates lay the foundation for even more powerful agent capabilities coming this fall.
### 🚀 What's New
* **Conditional Navigation (Beta)** - Your agents can now use deterministic, logic-based routing to navigate conversations. Think traditional programming conditionals - if/then statements, equals, greater than, contains - but in your voice flows. No more hoping the AI interprets navigation correctly. When a caller says their order is over \$100, your agent follows the exact path you defined, every single time. Zero risk of hallucinations, 100% predictable routing. *Currently in beta - contact [support@thoughtly.com](mailto:support@thoughtly.com) to join the testing group*

* **All-New Variable Management System** - We've completely reimagined how variables work in Thoughtly. Variables now live directly in every node and are easily accessible from a new sidebar, giving you unprecedented control over data flow throughout your conversations. This powerful new system replaces the old "Extract Text Mid-Call" action with an intuitive UI that makes variable extraction seamless
* **Gladia Speech Recognition** - We're progressively rolling out a new speech recognition option with superior accuracy, better accent handling, and smoother interruption management. *Available for select workspaces*
* **Enhanced Voicemail Detection** - Improved detection accurately identifies answering machines and voicemail systems using the latest AI models
### 🛠️ Platform Enhancements
* **Telnyx Migration Complete** - All new accounts now use Telnyx as the default telephony provider, delivering improved call quality, better international support, and more reliable transfers
* **Natural Conversation Flow** - Completely rebuilt how agents handle silence and pauses for more human-like interactions
* **Smoother Interruptions** - Agents now respond more naturally when interrupted, creating better two-way conversations
* **Calendly Partnership** - We've integrated with Calendly's V2 API and are working directly with their team as an official partner to ensure flawless appointment booking
### 🔧 Important Fixes
* **Automation Reliability** - Variables now maintain their values correctly, filters work as expected, and execution logs provide clear status updates
* **Login & Access** - Resolved all reported login issues and page loading problems
* **Caller ID Management** - Improved number verification workflow and display
* **Call Transfers** - More reliable handoffs between agents and to external numbers
### 💡 Quality of Life Updates
* **Stop Running Automations** - New ability to halt automations that are in progress
* **Better Usage Tracking** - More accurate call duration calculations and detailed reporting by credit type in the usage dashboard
* **Faster Response Times** - Performance optimizations across the platform
* **Improved Error Messages** - Clearer feedback when something goes wrong
### 🔮 Coming Soon
We're putting the finishing touches on several exciting features that will dramatically expand what your agents can do. September will bring new integration capabilities and advanced agent behaviors that our enterprise customers have been requesting. Stay tuned!
## Enhanced Calling Experience 📞
This July, we focused on making your agents smarter with voicemail handling and more responsive during calls. We've improved automation reliability, enhanced call quality, and added powerful new capabilities for SMS interactions. Behind the scenes, we've been laying the groundwork for infrastructure improvements that will deliver even better performance in the coming months.
### 🚀 What's New
* **Voicemail Variables** - Personalize voicemail messages with dynamic variables like caller name, company, or custom fields
* **Advanced Answering Machine Detection** - Significantly improved accuracy in detecting voicemail systems versus live callers
* **Mid-Call SMS Reading** - Agents can now read and respond to SMS content during active calls for verification codes or additional information
* **Precise Call Duration Tracking** - Better billing transparency with accurate call timing down to the second
### 🛠️ Platform Enhancements
* **Arabic Language Support** - Enhanced speech recognition accuracy for Arabic speakers
* **Automation Engine Improvements** - Better loop handling, fixed duplication issues, and full timezone support for scheduled triggers
* **Smoother Call Transfers** - Updated transfer APIs for more reliable agent handoffs
* **Smart Rate Limiting** - Optimized performance during high-volume periods
### 🔧 Important Fixes
* **Login Stability** - Resolved infinite loading screens and authentication issues
* **Automation Loops** - Fixed triggers that were causing infinite execution loops
* **Call Transfer Reliability** - Resolved streaming issues during transfers
* **SMS Content Handling** - Fixed issues with SMS content not being passed correctly to automations
* **UI Improvements** - Fixed pagination, keyboard shortcuts, and various display issues
### 💡 Quality of Life Updates
* **Clearer Error Messages** - More helpful feedback when automations encounter issues
* **Improved Dashboard Performance** - Faster load times for agent and automation pages
* **Better Call Logs** - Enhanced detail in call transcripts and recordings
### Infrastructure Update
We're preparing to enhance our infrastructure for improved performance and reliability. This work is happening behind the scenes with no impact to your current service. You'll start seeing the benefits of these improvements in the coming months.
## Bring Your Own Carrier (BYOC)
You can now use **Bring Your Own Carrier** (BYOC) to connect your preferred telecom provider, such as Twilio or Telnyx, directly to Thoughtly. This offers you greater control, more flexibility, and fewer restrictions.
### Why BYOC?
* **Use Your Preferred Provider**: Twilio, Telnyx, or any supported provider.
* **No Hidden Fees**: You pay your carrier directly—Thoughtly adds nothing on top.
* **More Control**: Choose terms, compliance settings, and support standards that suit your business.
[Learn more about BYOC](/platform/settings/general#bring-your-own-carrier-byoc) and how to set it up.
## Powering Up 🏗️
This April, our team focused on improving Thoughtly at its core. We updated key systems and added a few new features you can use right away. Most of our work happened behind the scenes to fix issues that were slowing us down. Thanks to these changes, we can now build and release new features much faster in the coming months. You'll start to see the benefits of this work very soon.
### 🚀 What's New
* **Speak Node Prompt Toggle** - Switch between simple agent messages and complex instruction prompts with a single click, giving you flexibility in how you control your agent responses
* **Raw JSON for Automations** - For power users who've been asking for more control, you can now structure automation inputs using raw json text
* **DTMF Input Support** - First step toward full IVR capabilities! Your agents can now press phone keys at the beginning of calls
### 🛠️ Platform Enhancements
* **Architecture Improvements** - We've optimized our core services for better performance across the board
* **Better Connectivity** - Upgraded carrier connectivity for increased performance and call quality
* **Latest Models** - Upgraded to Deepgram Nova-3, ElevenLabs Flash-2.5, and Cartesia's sonic-preview
* **Query Speed Boost** - We've improved how we handle queries, leading to increased database performance
### 🔧 Important Fixes
* **SMS Reliability** - Fixed all reported bugs related to our SMS feature and made general improvements
* **Automation Stability** - Enhanced automations to deliver more reliable performance across various use cases
* **Calendly** - Vastly improved this integration to handle timezones and contacts correctly, resulting in significantly more reliable booking experiences
### 💡 Quality of Life Updates
* **Promptbooks** - We've added video tutorials to the docs to help you get up to speed faster. Check them out: [docs.thoughtly.com/promptbooks/browse](https://docs.thoughtly.com/promptbooks/browse)
* **Transactional Email Redesign** - Fresh new look for all system-generated emails
* **Better Number Reading** - AI Voice models now handle and read long numerical sequences more naturally
* **Better Table Views** - We've redesigned tables throughout the app for better usability and consistency
## Instant Voice Cloning
We're excited to introduce **[Instant Voice Cloning](/agents/voice-cloning)**, a groundbreaking new feature that allows you to create hyper-realistic AI voices in seconds. With just a short audio sample, you can generate a high-quality AI voice that mimics tone, pitch, and cadence with near-perfect accuracy.
[ ](https://app.arcade.software/share/MaOO9bPhyHAP5ZdOq8Gt)
### How It Works
1. **Record or Upload** – Provide a short voice sample (as little as 10 seconds).
2. **AI Processing** – Our system instantly analyzes the sample using Cartesia’s `sonic` model.
3. **Preview & Adjust** – Listen to the cloned voice and fine-tune pitch, speed, and intonation.
4. **Deploy** – Use your new AI voice in any Thoughtly Virtual Agent.
### Key Features:
* **Lightning-Fast Cloning** – Get a fully functional AI voice in under a minute.
* **No Training Required** – Unlike traditional voice cloning, this process is instant and requires no manual tuning.
* **Ultra-Realistic Speech** – Powered by Cartesia's cutting-edge `sonic` model, delivering human-like quality.
* **Full Control** – Adjust pitch, speed, and emotion to refine the cloned voice.
* **Private & Secure** – Cloned voices are unique to your account and cannot be shared or accessed by others.
[Learn More](/agents/voice-cloning) about Instant Voice Cloning.
## Agent v1.5
The revolutionary new Thoughtly Virtual Agent, v1.5, is now available. This update includes a host of new features and improvements, including:
* **Mid-call Actions**: Agents can now perform actions during a call, such as sending an SMS, updating a CRM, or fetching real-time data.
* **Reduced Hallucinations**: Thanks to a proprietary combination of mathematical calculations and LLM reasoning, agents now generate more accurate responses with optimized context windows.
* **Improved Failure Tolerance**: The system now leverages multiple LLM vendors to enhance reliability and minimize downtime.
* **Lower Latency**: More efficient logic and scalable infrastructure reduce response times for a smoother user experience.
* **Enhanced Navigation**: Edges now carry meaning instead of relying on bloated context, leading to smarter conversation flows.
* **Advanced Node Controls**: Users now have more granular control over settings, including:
* **Voice Confidence Threshold** – Adjust response certainty.
* **Sensitivity Threshold** – Fine-tune agent responsiveness.
* **Verbatim Mode** – Force strict adherence to scripted responses.
* **Disable Interruption** – Prevent the agent from speaking over the user.
* **Small Talk & Music Handling** – Configure how the agent responds to casual conversation and background music.
* **Cartesia Voice Support**: Expanded capabilities with [Cartesia](/agents/voices) for hyper-realistic, low-latency voices.
Try it out by enabling experimental features in your [Developer Settings](https://app.thoughtly.com/settings/developer). Be sure to follow our [Tips & Tricks](/agents/tips-and-tricks) to prompt correctly and get the most out of the new Agent.
## Cartesia
We're excited to announce our partnership with Cartesia, a leading provider of AI voice models. Thoughtly now leverages Cartesia’s flagship Sonic model, the most advanced generative voice technology available.
**Why Sonic?**
* **Blazing Fast**: With a time-to-first-audio of 90ms, Sonic is the fastest generative voice model available, designed for real-time interactions.
* **Superior Quality**: Ranked #1 in voice quality in independent evaluations, delivering ultra-realistic AI-generated voices.
* **Fine-Tuned Control**: Adjust pitch, speed, emotion, and pronunciation for fully customized voice responses.
* **Multilingual Support**: Supports 15+ languages, including English, Spanish, French, Japanese, and German, with localized accents for seamless communication.
* **Scalability & Reliability**: Purpose-built for enterprise-grade AI voice applications, ensuring low-latency, high-accuracy voice synthesis.
Cartesia's voices are available from the [Voice Selector](/agents/voices) inside the Agent Builder. Voices are only available in v1.5 agents, not v1.
## New Integrations
This month, we've added or updated our integrations with:
* 🆕 [**Zoho**](/integrations/crm/zoho): Schedule appointments, create, find, and update records.
* ⬆️ [**GoHighLevel**](/integrations/crm/highlevel): Retrieve contacts, update contacts, and delete contacts.
## January Updates 🎉
* [**Gmail Integration**](/integrations/communication/gmail): Give your Agents the ability to send emails directly from your Gmail account, providing you with an all-in-one tool for getting a customer's email during a call or from your CRM, using AI to draft a message, then sending a follow-up after a call.
* [**New Mindbody Actions**](/integrations/scheduling/mindbody): Lookup a client by phone number and email.
* [**Slack Integration**](/integrations/communication/slack): Notify your team in Slack when a call is completed, or when other events occur.
* [**New Salesforce Trigger**](/integrations/crm/salesforce): Trigger workflows based on new objects created in Salesforce.
* New tables, filtering, and search: You can now filter, search, and sort columns in tables, such as the Library and Agent pages.
## December Updates 🎄
* [**Webhook Triggers**](/automations/triggers#webhook): Trigger workflows based on events like new leads, inbound calls, or completed calls.
* [**New Google Sheets Actions**](/integrations/productivity/google-sheets): Append a row to a Google Sheet via Automations.
* [**SMS Actions**](/automations/actions#sms): Send SMS messages via Automations.
* [**Smartsheet Integration**](/integrations/productivity/smartsheet): Connect Thoughtly to Smartsheet for seamless data management.
* [**New Acuity Actions**](/integrations/scheduling/acuity): Added new actions for the Acuity Scheduling integration.
* **Multi-Region Services**: Thoughtly's services are now intercontinental 🚀
* In addition to our main data center in **Virginia,** we now have data centers in **Oregon,** **Belgium,** and **Taiwan** to support our growing global customer base. The web platform will automatically route you to the nearest data center and should provide a much faster experience for users outside of the U.S.
* Note that our telecom services are still being routed through our Virginia data center, but we're working on global deployments as soon as possible to improve call quality and latency for international calls.
## Automations 🔁
We’re thrilled to announce the launch of **Automations**, a game-changing feature that empowers you to create dynamic workflows for your Voice Agents. Connect your Voice Agents to the tools you love, automate tasks, and streamline your operations like never before.
### What Are Automations?
Automations are customizable workflows that allow you to trigger actions before, during, and after calls. Whether it's updating your CRM, scheduling follow-ups, or connecting Voice Agents to real-time data, Automations let you streamline operations like never before.
#### Key Features:
* [**Triggers**](/automations/triggers): Initiate workflows based on events like new leads, inbound calls, or completed calls.
* [**Actions**](/automations/actions): Perform tasks like making calls, sending SMS, updating records, or fetching real-time data.
* [**Integration Support**](/integrations): Seamlessly connect to tools like Salesforce, Typeform, HubSpot, and Google Sheets.
* [**AI-Generated Variables**](/automations/getting-started#variables): Dynamically extract and use data from call transcripts to enrich workflows.
* [**Conditionals**](/automations/actions#conditionals): Add branching logic with filters, switches, and if/else statements for complex workflows.
#### Real-World Use Cases:
* **Call Leads Instantly**: Trigger a call to new leads added to your CRM and update the CRM with the call outcome.
* **Automated Data Retrieval**: Fetch real-time stock prices or customer history before connecting a call.
* **Scheduled Outreach**: Set recurring workflows to check in with customers or send appointment reminders.
* **Dynamic Call Flows**: Adapt conversations in real-time using AI-extracted keywords and context.
Learn more and get started with Automations on the [**Automations Docs Page**](/automations/getting-started) 📖
***
### 🔌 New Integrations
Thoughtly now integrates natively with dozens of popular tools. This November, you can now connect your Voice Agents to:
* [**HubSpot**](/integrations/crm/hubspot): Automate tasks, update records, and trigger workflows in HubSpot.
* [**PipeDrive**](/integrations/crm/pipedrive): Create, update, and delete objects in PipeDrive.
* [**Acuity Scheduling**](/integrations/scheduling/acuity): Automate appointment booking, rescheduling, and cancellations.
* [**Keap**](/integrations/crm/keap): Create, update, and delete objects in Keap.
* [**Mindbody**](/integrations/scheduling/mindbody): Automate appointment booking, rescheduling, and cancellations in Mindbody.
* [**Salesforce**](/integrations/crm/salesforce): Execute SOQL queries, create, update, and delete objects in Salesforce.
* [**Trello**](/integrations/productivity/trello): Create, update, and delete cards in Trello.
* [**Zendesk**](/integrations/ticketing/zendesk): Create, update, and delete tickets in Zendesk.
* [**Google Sheets**](/integrations/productivity/google-sheets): Create, update, and delete rows in Google Sheets.
***
### New & Improved
* You can now provide an extension number when transferring calls.
* Added in new [languages](/resources/faq#what-languages-does-thoughtly-support) for Voice Agents.
* You can now acquire phone numbers in more regions without contacting support by creating a [regulatory bundle](/phone-number/getting-started#buying-international-phone-numbers) for that region.
## The Thoughtly Voice Library 🗣️
Add a unique personality to your Voice Agents by browsing thousands of professional pre-made voices from our voice partners like ElevenLabs.
Filter a diverse range of voices by language, gender, and style to find the perfect match for your brand. Listen to voice previews before selection and save your favorites for quick access in the Agent Builder.
Learn more on the [Exploring Voices](/agents/voices#explore-tab) docs page.
***
## Credits & Lower Pricing! 🎉
Instead of having to pay for phone numbers, minutes, and upcoming usage-based features separately, credits makes it easy with one, straightforward virtual currency. Enjoy our lower, simplified pricing.
Learn more on the [**Billing docs page**](/platform/billing) 📖
***
#### New & Improved
* Calls that go to voicemail without voicemail drops enabled will no longer incur charges.
* Credit usage is now accurately billed, eliminating rounding up to 10 credits for calls under one minute.
* Verified business accounts can now make international calls.
* Agent tools now support query strings for Calendly URLs, such as for the purpose of UTM tracking.
## Conversational SMS 💬
This update brings powerful new capabilities to enhance how you interact with your customers via text, even during active phone calls.
You can now initiate and continue full AI-powered Thoughtly conversations over SMS, just like you would during a call. This allows for seamless, real-time text interactions with your customers, powered by the same advanced AI that runs your voice conversations.
To use these new SMS features, ensure your business is verified. Once approved, you can start leveraging this powerful tool immediately.
Learn more on the [Conversational SMS](/agents/deployment#sms) docs page.
## Caller ID Masking for Outbound Calls
This feature allows you to ensure that your outbound calls appear to come from a specific phone number of your choice, providing a consistent and professional experience for your customers.
With Caller ID masking, you can mask your outbound phone calls to display a specific phone number that you’ve added and verified on the platform. This is useful for businesses that want all calls to appear as if they are coming from a central or recognized number that is not owned by Thoughtly itself.
**Setup**
To enable Caller ID masking, navigate to the "Phone Numbers" section on the left-hand side of the platform, then select "Caller ID" in the top right corner. Enter the phone number you want to use, and click "Enable."
After entering your phone number, you'll receive a validation call. Simply enter the six-digit validation code to confirm ownership, and you're all set!
**Use Cases**
* BYON (Bring Your Own Number): Use your existing phone number for outbound calls, then forward inbound calls to your Thoughtly agent.
* Consistent Branding: Ensure that all customer interactions, whether by phone or text, reflect your brand's central contact number.
* Improved Customer Trust: Calls appearing from a recognized number are more likely to be answered, leading to better engagement and fewer missed connections.
Learn more on the [Caller ID](/phone-number/configuration) docs page.
***
## Rules & Training 🥇
This update allows you to fine-tune and customize the behavior of your AI agents with unprecedented precision, ensuring they respond exactly the way you want in any given scenario.
You can now train your AI agents directly through an intuitive interface. Simply interact with your agent, and if a response doesn't meet your expectations, you can modify it instantly. This allows for a more natural and efficient training process.
Each rule you create is tied to a specific node in the conversation flow. This means you can manage, edit, or add new rules to individual parts of the conversation, giving you granular control over how your agent interacts with callers.
Learn more on the [Rules & Training](/agents/outcomes) docs page.
# Get support from Thoughtly
Source: https://docs.thoughtly.com/support/getting-help
Contact Thoughtly's support team for help with voice agents, automations, integrations, billing, and account issues, plus community and self-serve resources.
## Getting Help
To get help with Thoughtly, just click on the Thoughtly logo in the bottom-right corner of the platform. If you're on a **Flex** or **Enterprise** plan, you'll see our in-app support chat widget, powered by [Tessa](/resources/faq#who-is-tessa)—our helpful AI support agent.
Tessa can guide you to the right resource, whether it's documentation, a product walkthrough, or a way to reach our team. If she can't solve your issue, she'll offer to connect you with a human on the support team.
### Not on a Flex or Enterprise Plan?
If you're on a **trial** or **AppSumo** plan and don't see the chat widget, don't worry—help is still available.
You have a few options:
* **Search or post questions in our [Skool Community](https://www.skool.com/thoughtly)**: The community is the best place to get fast answers to general questions, prompts and scripting, or general how-to guidance.
* **Email us** at [support@thoughtly.com](mailto:support@thoughtly.com): If your question can't be answered in the community, feel free to email us. We'll do our best to respond within 7-10 business days, though we can't guarantee a response time for AppSumo or trial users.
* **Book a demo** at [thought.ly/demo](https://thought.ly/demo): If you're on a trial or exploring Thoughtly for your team, we recommend booking a quick demo. A team member will walk you through the platform and help answer any sales or setup-related questions.
***
## Submitting a Ticket
If you're on a Flex or Enterprise plan, Tessa will walk you through submitting a support ticket if your issue requires human review. We will respond to your ticket within 1-2 business days. You can also email us directly at [support@thoughtly.com](mailto:support@thoughtly.com)— be sure to use the email address linked to your Thoughtly account so we can verify your identity.
***
## Phone Support (Enterprise Only)
If you're on an **Enterprise Plan**, you can reach our support team by phone at **+1 (646) 982-3580**.
Please call from the phone number linked to your Thoughtly account so we can verify your identity.
# Thoughtly referral program
Source: https://docs.thoughtly.com/support/referral-program
Earn cash rewards and credit by referring customers to Thoughtly — join the referral program, share your link, and track referrals and payouts.
At Thoughtly, we believe great products grow best through word of mouth. That's why we've launched the **Thoughtly Referral Program** — a way to thank our customers and partners for helping us connect with businesses that can benefit from our platform.
***
### How It Works
It's simple: If you refer a new customer to Thoughtly and they remain an active customer for at least **three months**, you'll receive a **\$1,000 gift card** as our way of saying thank you.
There are two easy ways a referral can be recorded:
1. **Direct Introduction**: Introduce the potential customer to a Thoughtly sales representative.\
Our team will note the referral and ensure you're credited if the customer joins.
2. **Customer Mention**: If the new customer tells their Thoughtly account executive that you referred them, we'll log that referral and make sure you're recognized.
***
### Eligibility
* The referred business must be a **new customer** to Thoughtly.
* The referral reward will be issued **after the new customer has been active for three full months**.
* There is **no limit** to the number of referrals you can make — refer as many businesses as you'd like!
***
### Why Refer?
By referring businesses to Thoughtly, you're not just earning a reward — you're helping others unlock the power of AI voice agents to engage leads, improve sales, and grow revenue.
Plus, your referrals will know they're in good hands with a platform trusted by **leading enterprises across industries**.
***
Have someone in mind? **Introduce your contact** directly to your Thoughtly account executive. Our team will handle the rest — and you'll be on your way to earning that \$1,000 reward.
If you have any questions about the program, reach out to **[support@thoughtly.com](mailto:support@thoughtly.com)**. We're happy to walk you through the details and help ensure you get credit for every referral you send our way.