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.
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. |
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. |
- 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.
- Update on a schedule, not on a panic. Pricing changes, policy changes, product launches; pick a monthly cadence and stick to it.
- 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.
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. |
- Professional / formal for banking, legal, government.
- Friendly / conversational for retail, hospitality, e-commerce.
- Playful for entertainment, lifestyle, social media.
- 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.”
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. |
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. |
| 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. |
- 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 flow on both before launch.
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 | Volume, average handle time, days analysed. | Daily glance. |
| Sentiment | Negative share trend, top intents tied to negative sentiment. | Weekly. |
| Speaker Timeline | Silence ratio, talk-over ratio, dead-air events. | Weekly. |
| Agent Scorecards | Per-agent sentiment delta, FCR, escalation rate. | Weekly or per shift. |
| Compliance | Greeting / privacy / verification phrase hit rate. | Daily for regulated industries. |
| Alerts | Triggered events on the rules you defined. | Real time, plus daily review. |
| 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. |
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. |
| 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. |
| 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. |
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: Failure to comply may result in suspension or termination of your account.Common questions
The agent gives different answers to the same question on different attempts.
The agent gives different answers to the same question on different attempts.
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.My Knowledge Base is full of FAQs but the agent ignores them.
My Knowledge Base is full of FAQs but the agent ignores them.
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.
My voice agent talks over my callers.
My voice agent talks over my callers.
Increase Min Silence Duration in 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.The agent ends voice calls too quickly.
The agent ends voice calls too quickly.
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.Updates I make to the URL in the Knowledge Base are not reflected.
Updates I make to the URL in the Knowledge Base are not reflected.
Remove the URL from the list and add it again to force a re-crawl. There is no in-place re-index button today.
My deployment widget loads on a competitor's page.
My deployment widget loads on a competitor's page.
You forgot to set Allowed Domains in Deployment. Empty list means the widget works on every domain. Add only your real domains and click Activate for each.
Best practices for sentiment alerts in CCQA?
Best practices for sentiment alerts in CCQA?
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 walks through the seed library.Best practices for the Compliance phrase library?
Best practices for the Compliance phrase 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.
The Tickets and Leads step asks for too much data; my conversion is dropping.
The Tickets and Leads step asks for too much data; my conversion is dropping.
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.
I want to A/B test two prompts.
I want to A/B test two prompts.
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