> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wittify.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Best Practices
> Cross-system guidelines for accuracy, brand consistency, customer experience, and a smooth human handoff. Apply these whether you're building agents, transcribing audio, or running call center QA.
This page is opinionated guidance, not a reference. The do-this / avoid-this rules below come from real customer deployments. Where a rule is product-specific, the heading says so; otherwise the rule applies to every Wittify product. Each section ends with a **Where to apply it** strip pointing at the page in the docs that holds the actual control.
## 1. Define clear objectives before you build
Before you click **Create Agent**, **Create A Voice**, or **+ New Project**, decide three things:
| Question | Why it matters |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| What is the **primary mission**? | Answer FAQs, qualify leads, schedule appointments, transcribe meetings, monitor call center quality. Pick one mission per agent or project; mixing missions makes prompt tuning fight itself. |
| Who is the **target audience**? | Region, dialect, formal versus casual register, the channels they use. The audience drives language, tone, and channel mix. |
| How will you **measure success**? | Number of conversations, resolution time, conversion rate, CSAT, transcription accuracy, alert response time. Pick the metrics first, then design backwards from them. |
**Where to apply it:** [AI Agents Wizard, Text Settings](/en/Systems/AI-Agents/Overview) for the Core Instructions field; [CCQA Goals](/en/Systems/Contact-Center-QA/Goals) for measurable KPI targets.
## 2. Train with comprehensive and relevant knowledge (AI Agents)
The Knowledge Base is what makes the agent yours. Three sources, used together:
| Source | Best for | Limit per agent |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| **Files** (PDF, DOCX, XLSX, TXT, CSV, PNG, JPG) | Long-form material like manuals, policy docs, FAQs already in PDF, product catalogues. | 100 MB total, 10 MB per file. |
| **URLs** | Pages on your live website. The crawler indexes the page contents and re-indexes when you ask it to. | One URL per row. |
| **FAQs** | Short, fixed answers (pricing, refund policy, return windows). FAQs win against everything else when the user asks a near-exact question. | Up to 500 rows per CSV import. |
Three rules that pay back ten times over:
1. **Cover multiple phrasings.** Your customers don't ask the question the same way you wrote the help article. Add three or four FAQ entries that paraphrase the same answer.
2. **Update on a schedule, not on a panic.** Pricing changes, policy changes, product launches; pick a monthly cadence and stick to it.
3. **Remove outdated sources.** Stale data is worse than missing data; the agent will confidently quote a number that hasn't been true for six months.
**Where to apply it:** [Knowledge Base wizard step](/en/Systems/AI-Agents/Wizard/Knowledge-Base).
## 3. Customize tone, language, dialect, and voice
The agent's personality lives in three controls:
| Control | What it does | Default |
| ---------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------- |
| **Core Instructions** | The system prompt. Defines role, goals, tone, restrictions, fallback behaviour. | Empty until you write it. |
| **Creativity Level** (Temperature) | Controls how varied the model's wording is. Low for facts, high for marketing copy. | `0.5` (balanced). |
| **Voice** (voice agents) | Pick a voice from the Voice Picker modal. Preview with **Play**, apply with **Use Voice**. | None until you pick one. |
Tone tips:
* **Professional / formal** for banking, legal, government.
* **Friendly / conversational** for retail, hospitality, e-commerce.
* **Playful** for entertainment, lifestyle, social media.
Dialect tips:
* For Arabic, write the dialect explicitly in Core Instructions: *"Speak in Saudi Najdi Arabic only."* The model picks up on the cue and stays in that register.
* For mixed-language deployments, write: *"Reply in the same language the user wrote in. If the user mixes Arabic and English, mirror that mix."*
**Where to apply it:** [Text Settings](/en/Systems/AI-Agents/Wizard/Text-Settings), [Voice Settings](/en/Systems/AI-Agents/Wizard/Voice-Settings), [Voice Picker](/en/Systems/Text-to-Speech/Voice-Picker).
## 4. Connect knowledge sources to live data when accuracy matters
For order tracking, calendar booking, payments, or any data that changes more than once a day, the Knowledge Base is the wrong tool; integrate live tools instead:
| Use case | Built-in tool |
| ---------------- | ------------------------------------------------------------------------------------------------------ |
| Order tracking | **Order Tracking** in the Integrations step. Set the endpoint, method, auth header, and lookup fields. |
| Calendar booking | **Calendar Booking**. Add a Google Calendar or Calendly URL and the durations you offer. |
| Payments | **Payment Collection**. Drop in a payment link and currency. |
| Live handoff | **Human Handoff**. Set the trigger, channel, and target. |
| Anything else | **Custom API Tools** or an **MCP Connector**. |
**Where to apply it:** [Integrations and Tools](/en/Systems/AI-Agents/Wizard/Integrations-and-Tools).
## 5. Deploy strategically, not everywhere at once
Pick your beachhead channel first; expand to the rest only after the first one performs.
| Channel | When to start there |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| **Website widget** | If you already have website traffic and want a low-friction launch. |
| **WhatsApp** | If most of your inbound traffic is on WhatsApp Business. Requires a verified Meta Business account. |
| **Telephony** (Twilio / Telnyx / SIP Trunk / WhatsApp Calls) | If your audience calls instead of writes. |
| **Messenger / Instagram / X / Telegram** | After the website widget proves the agent works end-to-end. |
Two cross-channel rules:
* **Allowed Domains.** Restrict where your widget can render. Empty list means it works everywhere; that's almost never what you want.
* **Test on real devices.** Mobile and desktop behave differently for voice (microphone latency, network instability). Run through the [Test Your Agent](/en/Systems/AI-Agents/Manage-Agent/Test-Your-Agent) flow on both before launch.
**Where to apply it:** [Deployment](/en/Systems/AI-Agents/Wizard/Deployment).
## 6. Monitor, analyze, and improve (CCQA)
For call center deployments, the cycle is **monitor → analyze → improve**, weekly or monthly:
| Surface | What to watch | How often |
| ------------------------------------------------------------------ | ------------------------------------------------------------- | ------------------------------- |
| [CCQA Overview](/en/Systems/Contact-Center-QA/Overview-Page) | Volume, average handle time, days analysed. | Daily glance. |
| [Sentiment](/en/Systems/Contact-Center-QA/Sentiment-Analysis) | Negative share trend, top intents tied to negative sentiment. | Weekly. |
| [Speaker Timeline](/en/Systems/Contact-Center-QA/Speaker-Timeline) | Silence ratio, talk-over ratio, dead-air events. | Weekly. |
| [Agent Scorecards](/en/Systems/Contact-Center-QA/Agent-Scorecards) | Per-agent sentiment delta, FCR, escalation rate. | Weekly or per shift. |
| [Compliance](/en/Systems/Contact-Center-QA/Compliance) | Greeting / privacy / verification phrase hit rate. | Daily for regulated industries. |
| [Alerts](/en/Systems/Contact-Center-QA/Alerts) | Triggered events on the rules you defined. | Real time, plus daily review. |
| [TimeLens AI](/en/Systems/Contact-Center-QA/TimeLens-AI) | Streamed narrative summary of the date range. | Monthly executive review. |
## 7. Plan for smooth human handoff
The agent should never feel like a wall. Three triggers, in order of urgency:
| Trigger | What the agent does |
| ------------------- | ------------------------------------------------------------------- |
| Negative sentiment | Hand off to a human after two consecutive negative-sentiment turns. |
| VIP customer | Hand off immediately on a flagged customer ID. |
| Unrecognized intent | Hand off after the agent fails to answer twice in a row. |
The agent's handoff message should be specific (*"I'll connect you with someone from our team"*), not generic (*"Please hold"*). Train the human team to **read the recent transcript before responding**, not to ask the customer to repeat themselves.
**Where to apply it:** [Integrations and Tools, Human Handoff](/en/Systems/AI-Agents/Wizard/Integrations-and-Tools), [Manage Agent → Chat / Voice Conversations](/en/Systems/AI-Agents/Manage-Agent/Chat-Conversations).
## 8. Prioritize security and privacy
Security on Wittify is a shared responsibility. The platform takes care of secure transport (HTTPS), encrypted storage, and keeping API keys server-side so they never reach your visitors' browsers. You take care of:
| Rule | Where you control it |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Only request essential PII.** | Tickets and Leads step, custom field list. Less is more. |
| **Lock down deployment domains.** | Deployment, Allowed Domains list. Empty equals world-readable. |
| **Use https everywhere.** | Company URL, webhook URLs, custom API endpoints, MCP connectors. The app rejects http URLs by design. |
| **Rotate integration credentials.** | Twilio, Telnyx, OpenAI keys, Composio tokens; rotate on a schedule. |
| **Disable the search tool when scope matters.** | Knowledge Base, Search tab. The default is off; turn it on only after you've added the URL whitelist. |
## 9. Test and refine before scaling
A pilot beats a launch every time. The launch checklist:
| Check | How |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Happy-path flows | Run five canonical conversations through [Test Your Agent](/en/Systems/AI-Agents/Manage-Agent/Test-Your-Agent). |
| Edge cases | Slang, typos, code-switching, empty input. The agent should fall back gracefully, never echo a stack trace. |
| Language switching | Send the same question in EN and AR. The agent should mirror the user's language. |
| Lead capture | If lead collection is on, fill in a fake lead and confirm it lands in [Manage Agent → Leads and Tickets](/en/Systems/AI-Agents/Manage-Agent/Leads-and-Tickets). |
| Domain whitelist | Drop the embed snippet on a non-whitelisted page. The widget should refuse to load. |
| Voice timing | If the agent talks over the user, increase **Min Silence Duration**. If it cuts users off, increase **End Call on Silence**. |
After launch, set a recurring 30-minute review on your calendar for the first two weeks. Most issues surface in week one and stay there if you don't catch them.
## 10. Disclaimer
All AI agents and workflows created with Wittify.ai must comply with our official policies and legal guidelines. By using Wittify.ai, you agree to:
* [Terms of Service](https://wittify.ai/terms-of-service)
* [Prohibited Use Policy](https://wittify.ai/prohibited-use-policy)
* [Privacy Policy](https://wittify.ai/privacy-policy)
Failure to comply may result in suspension or termination of your account.
## Common questions
The **Creativity Level** (Temperature) is too high. Drop it to `0.3` or `0.4` for factual deployments. The lower the value, the more deterministic the wording.
FAQs only fire on near-exact matches. Add paraphrased variants of the same question, or move the answer into a **File** so it's part of the broader retrieval pool.
Increase **Min Silence Duration** in [Voice Settings](/en/Systems/AI-Agents/Wizard/Voice-Settings). Default is `0.5` seconds; try `0.8` or `1.0` for slow speakers. Also increase **Min Speech Duration** so very short noises don't trigger a response.
Increase **End Call on Silence**. Default is `60` seconds; try `90` or `120`. Also check microphone permissions and network stability on the caller's side.
Remove the URL from the list and add it again to force a re-crawl. There is no in-place re-index button today.
You forgot to set **Allowed Domains** in [Deployment](/en/Systems/AI-Agents/Wizard/Deployment). Empty list means the widget works on every domain. Add only your real domains and click **Activate** for each.
Start with the seed rule **Negative sentiment share** at `≥ 10%` (high severity, in-app + email). After two weeks of data, tighten to your real-world baseline. Without a baseline you'll drown in alerts; the page-level [Alerts deep dive](/en/Systems/Contact-Center-QA/Alerts) walks through the seed library.
Use the **Add script** dropdown in the Edit Library dialog to start from the four templates (greeting, identity, privacy, verification). Tweak the phrase **keywords** in EN + AR; do not over-edit the regex unless you know exactly what you're doing. Run the score against a one-week filter window first to validate.
Trim the field list. Required fields create friction. Most lead-collection deployments survive on Name + Phone + (optionally) Email. Move everything else to optional, or capture it after the conversation has already led to a callback.
Clone the agent (Manage Agent menu → **Clone**), edit the system prompt on the clone, and split traffic at the channel level (deploy each agent on a separate domain or campaign). The platform doesn't have a built-in split-test today.
***
> 💡 **Need help getting started?**
> Book a **free onboarding session** with one of our Customer Success Engineers and get personalized guidance on setting up your first Wittify product.
>
> 📅 **Book here:** [Schedule a Free Onboarding Session](https://calendly.com/d/cv9n-48c-kr2/wittify-ai-support-team)