---
name: thoughtly
description: Use when building, testing, and deploying AI voice agents for inbound and outbound calls. Reach for this skill when agents need to design conversation flows, configure integrations, set up automations, or troubleshoot voice agent behavior.
metadata:
    mintlify-proj: thoughtly
    version: "1.0"
---

# Thoughtly Skill Reference

## Product Summary

Thoughtly is a no-code platform for building and deploying AI voice agents that handle inbound and outbound calls. Agents use the visual Agent Builder to design conversation flows with nodes (Start, Speak, Transfer, End), configure routing logic with outcomes, capture caller data with variables, and trigger mid-call actions via integrations. Deploy agents to phone numbers (purchased or imported via BYOC), automate workflows with Automations (triggers + actions), and sync data with 20+ native integrations (Salesforce, HubSpot, Calendly, etc.). Key entry points: **Agent Builder** (create agents), **Automations** (trigger calls and post-call workflows), **Integrations** (connect CRMs and tools), **Phone Numbers** (inbound/outbound deployment). Primary docs: https://docs.thoughtly.com

## When to Use

Reach for this skill when:
- **Building agents**: Designing conversation flows, adding nodes, defining outcomes, capturing variables, testing with Test Agent or Call Me
- **Configuring integrations**: Connecting CRMs, schedulers, or webhooks to enable mid-call lookups or post-call data sync
- **Setting up automations**: Creating workflows that trigger calls on schedule, from CRM events, or via webhooks; running post-call actions like tagging or SMS
- **Deploying to production**: Assigning phone numbers, configuring voicemail, tuning presence settings, enabling SMS
- **Troubleshooting**: Debugging conversation logic, fixing variable extraction, resolving action failures, or optimizing voice quality
- **Testing before launch**: Running text-based Test Agent chats or live Call Me tests to validate flows and voice experience

## Quick Reference

### Node Types
| Node | Purpose | Key Settings |
|------|---------|--------------|
| **Start** | Opens call; first thing caller hears | Keep short; use verbatim text; no variables |
| **Speak (Message)** | Fixed line with minimal variation | Enable "Repeat verbatim" for exact copy; "Spell Numbers" for IDs |
| **Speak (Prompt)** | Adaptive response using context/data | Compose from variables; use for dynamic Q&A |
| **Transfer** | Hand off to human or another agent | Phone Router (number + optional extension) or Agent Transfer |
| **End** | Close conversation gracefully | Use verbatim text; create multiple for different branches |

### Outcome Types
| Type | When to Use | Example |
|------|------------|---------|
| **Prompt-based** | Open-ended replies, varied phrasing | "Wants to book" vs "Interested, send info" |
| **Rule-based** | Structured data, compliance, action results | `email_valid == true` → next step; Else → re-ask |

### Variable Formats
| Format | Use Case | Example |
|--------|----------|---------|
| **Text** | Names, emails, addresses | `email`, `first_name` |
| **Number** | Budgets, scores, quantities | `budget >= 250000` |
| **Boolean** | Consent, qualification flags | `callback_ok == true` |

### Automation Triggers
| Trigger | When It Fires | Common Use |
|---------|---------------|------------|
| **Inbound Call** | When call arrives at agent's number | Fetch CRM data before routing |
| **Recurring Schedule** | On fixed time/day/week | Daily lead calls, appointment reminders |
| **CRM Event** | New lead, contact updated | Call lead immediately after form submission |
| **Webhook** | External system posts data | Trigger from Zapier, Make, or custom API |
| **Call Completed** | After agent call ends | Update CRM, send SMS, tag conversation |

### Integration Setup Pattern
1. Navigate to **Settings → Integrations** (or **Tools → Integrations**)
2. Select integration (Salesforce, HubSpot, Calendly, etc.)
3. Authenticate via OAuth, API key, or credentials
4. Verify connection status
5. Use in **Automations** (post-call actions) or **Agent Builder** (mid-call actions)
6. If multiple accounts: select account in **Account** tab when configuring actions

## Decision Guidance

### When to Use Prompt vs Message Speak Nodes
| Scenario | Use | Reason |
|----------|-----|--------|
| Legal disclaimer, exact compliance copy | **Message + Verbatim** | Must be identical every time |
| Greeting with caller's name from CRM | **Prompt** | Compose from variables dynamically |
| Confirmation of extracted data | **Message** | Keep it short and fixed |
| Summarize lookup results to caller | **Prompt** | Adapt based on action output |

### When to Use Prompt-based vs Rule-based Outcomes
| Scenario | Use | Reason |
|----------|-----|--------|
| "Are you interested?" (varied replies) | **Prompt-based** | AI interprets intent flexibly |
| Email validation or budget check | **Rule-based** | Exact conditions, no ambiguity |
| After mid-call action (CRM lookup) | **Rule-based** | Check action flags (`lookup_found == true`) |
| Open Q&A loop | **Prompt-based** | Caller asks varied questions |

### When to Use Agent Actions vs Automations
| Task | Use | Why |
|------|-----|-----|
| Look up CRM data mid-call | **Agent Action** | Real-time, during conversation |
| Update CRM after call ends | **Automation** (Call Completed trigger) | Deterministic, post-call workflow |
| Send SMS during call | **Agent Action** | Immediate, in-call context |
| Send SMS after call | **Automation** (Call Completed trigger) | Scheduled, with call data |
| Validate email in real-time | **Agent Action** | Instant feedback to caller |
| Bulk tag calls by outcome | **Automation** (Call Completed trigger) | Batch processing, no caller wait |

### When to Use Test Agent vs Call Me
| Test Type | Use | Validates |
|-----------|-----|-----------|
| **Test Agent (text)** | Debugging logic, outcomes, variables | Conversation flow, routing, extraction |
| **Call Me (live call)** | Final polish before production | Voice quality, barge-in, latency, transfers |

## Workflow

### Building Your First Agent (15 minutes)
1. **Create agent**: Name it, set Conversation type (General, Sales, Support, etc.)
2. **Configure voice**: Open Settings → Voice Selector; preview and assign voice
3. **Build flow skeleton**: Add Start node → Speak (Prompt) → Transfer or End
4. **Define outcomes**: Add 3–4 prompt-based outcomes (e.g., "Book now", "Call back", "Not interested")
5. **Add variables**: Extract email, budget, or callback preference with clear instructions
6. **Test with Test Agent**: Send sample caller messages; verify outcomes and variable extraction
7. **Tune presence**: Adjust sensitivity, silence timeout, endpointing in Settings → Presence
8. **Call Me test**: Place a real call; listen for voice quality, interruptions, timing
9. **Deploy**: Assign phone number (buy or BYOC) in Phone Numbers settings
10. **Activate automations**: If using post-call workflows, activate them in Tools → Automations

### Adding Mid-Call Integrations (CRM Lookup)
1. **Verify integration is connected**: Settings → Integrations; confirm status is "Connected"
2. **Open Speak node**: Add an Action by clicking **+ Add new action**
3. **Select integration**: Choose CRM (Salesforce, HubSpot, etc.)
4. **Select account**: If multiple accounts, pick the right one in **Account** tab
5. **Configure fields**: Map variables to action inputs (e.g., `{{email}}` to lookup field)
6. **Add rule-based outcomes**: Check action results (e.g., `lookup_found == true` → enriched path)
7. **Test with Test Agent**: Verify action runs and variables update
8. **Call Me test**: Confirm action timing feels natural; add "One moment..." if needed

### Setting Up Post-Call Automation (CRM Sync)
1. **Navigate to Automations**: Tools → Automations
2. **Create new automation**: Click **Create Automation**
3. **Select trigger**: Choose **Call Completed** (or **Inbound Call** for pre-call setup)
4. **Add action**: Click **+ Add action**; select integration (e.g., "Create Contact" in Salesforce)
5. **Map variables**: Use field picker to connect call data to CRM fields (e.g., `{{caller_email}}` → Email)
6. **Test in Draft**: Click **Refresh Output** to simulate with sample data
7. **Activate**: Click **Activate** button (Draft automations never run)
8. **Verify**: Make a test call; check CRM for new record or update

### Troubleshooting a Stuck Agent
1. **Test with Test Agent**: Send a message; check which node it reaches
2. **Verify outcomes exist**: Open Speak node; confirm at least 2–3 outcomes are defined
3. **Check for dead ends**: Ensure all nodes have outcomes (no node connects to itself)
4. **Add Else/Default**: In rule-based outcomes, add a fallback for unmatched cases
5. **Review variables**: Confirm extraction instructions are specific; test with sample data
6. **Check actions**: Verify integration is connected; test action separately in Automations
7. **Call Me test**: Place a real call; review response log to see exact path taken

## Common Gotchas

- **Forgetting to activate automations**: Draft automations never execute. Always click **Activate** when ready for production.
- **Using prompt-based outcomes after actions**: Actions set flags (e.g., `lookup_found`), but prompt-based outcomes cannot see them unless you speak the value aloud. Use rule-based outcomes after actions.
- **Missing Else/Default in rule-based outcomes**: Without a fallback, the agent gets stuck if no rule matches. Always add an Else outcome.
- **Vague variable extraction instructions**: "Get their contact info" is too broad. Be explicit: "Extract email in lowercase, no spaces. If absent, leave empty."
- **Skipping Test Agent before Call Me**: Test Agent catches logic errors cheaply. Always validate outcomes and variables in text before placing real calls.
- **Not testing data extraction before deployment**: Test extraction actions in the output tab with sample responses. If no output, the action will fail in production.
- **Enabling interruptions on action nodes**: Actions run mid-call; if interruptions are on, the caller can break the flow. Keep interruptions disabled by default on action nodes.
- **Forgetting to set phone number country**: Phone number validation depends on country selection. Mismatched country = validation errors.
- **Using special characters in prompts**: Characters like `*`, `^`, `$` can break parsing. Avoid them in node messages and outcomes.
- **Outdated Genius knowledge base**: If Genius contains old information (e.g., outdated pricing), the agent will repeat it. Review and update monthly.
- **Multiple accounts for same integration**: If you have multiple Salesforce orgs or HubSpot accounts, always verify you've selected the correct account in the **Account** tab when configuring actions.
- **Not handling empty variables**: If a variable is missing, rule-based outcomes may fail silently. Plan for empty values: add a re-ask loop or transfer to human.

## Verification Checklist

Before deploying an agent to production:

- [ ] **Flow logic**: Test with Test Agent; verify all outcomes route correctly
- [ ] **Variable extraction**: Confirm variables extract accurate data; test with edge cases (empty, invalid, multiple values)
- [ ] **Actions**: Verify integrations are connected; test action separately in Automations; check rule-based outcomes reference action results
- [ ] **Voice quality**: Run Call Me test; listen for mispronunciations, barge-in behavior, latency
- [ ] **Presence tuning**: Adjust sensitivity and endpointing based on Call Me feedback
- [ ] **Voicemail**: Enable and test voicemail message (under 20–25 seconds)
- [ ] **Phone number**: Assign number to agent; verify country and format are correct
- [ ] **Automations**: If using post-call workflows, activate them (not Draft)
- [ ] **Error handling**: Confirm fallback paths exist (Else outcomes, transfer to human on repeated failures)
- [ ] **Compliance**: For outbound calls, verify TCPA consent and legal disclaimers are in place
- [ ] **Data mapping**: If syncing to CRM, verify field mappings are correct and required fields are populated

## Resources

**Comprehensive navigation**: https://docs.thoughtly.com/llms.txt

**Critical documentation**:
- [Agent Builder Overview](https://docs.thoughtly.com/agents/overview) — Core concepts, node types, testing workflow
- [Automations Getting Started](https://docs.thoughtly.com/automations/getting-started) — Triggers, actions, post-call workflows
- [Integrations Getting Started](https://docs.thoughtly.com/integrations/getting-started) — Setup, authentication, multiple accounts, troubleshooting

---

> For additional documentation and navigation, see: https://docs.thoughtly.com/llms.txt