***
title: Hints
description: Speech hints improve recognition accuracy for domain-specific vocabulary, brand names, technical terms, and other words the STT engine might misinterpret.
slug: /guides/hints
max-toc-depth: 3
---------------------
For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt
[swaig-functions]: /docs/server-sdks/guides/swaig
### Why Use Hints?
### Adding Simple Hints
The hint methods accept a single string or a list of strings:
| Language | Single Hint | Multiple Hints |
| ---------- | ------------------------ | ----------------------------------------- |
| Python | `agent.add_hint("Acme")` | `agent.add_hints(["Acme", "SignalWire"])` |
| TypeScript | `agent.addHint('Acme')` | `agent.addHints(['Acme', 'SignalWire'])` |
#### Single Hint
```python
from signalwire import AgentBase
class MyAgent(AgentBase):
def __init__(self):
super().__init__(name="my-agent")
self.add_language("English", "en-US", "rime.spore")
# Add single hint
self.add_hint("Acme")
self.add_hint("SignalWire")
```
#### Multiple Hints
```python
## Add list of hints
self.add_hints([
"Acme",
"SignalWire",
"API",
"webhook",
"SWML"
])
```
### What to Hint
| Category | Examples |
| ------------------- | -------------------------------------------------- |
| **Brand Names** | Acme Corp, SignalWire, company name, product names |
| **Technical Terms** | API, webhook, OAuth, SDK, JSON |
| **Industry Jargon** | KYC, AML, SLA, EOD, PTO |
| **Names** | Employee names, customer names, location names |
| **Numbers/Codes** | Account numbers, ZIP codes, reference IDs |
| **Actions** | Transfer, escalate, reschedule |
### Hint Examples by Use Case
#### Customer Service
```python
self.add_hints([
"Acme", "Acme Pro", "Acme Enterprise",
"account", "billing", "refund", "exchange", "return",
"cancel", "upgrade", "downgrade",
"representative", "supervisor", "escalate", "ticket",
"case number", "reference number"
])
```
#### Technical Support
```python
self.add_hints([
"Windows", "macOS", "Linux", "Chrome", "Firefox",
"reboot", "restart", "reinstall", "cache", "cookies",
"browser", "firewall", "antivirus", "driver",
"error code", "blue screen", "crash", "freeze",
"not responding", "won't start"
])
```
#### Healthcare
```python
self.add_hints([
"appointment", "reschedule", "cancel", "follow-up",
"prescription", "refill", "pharmacy", "dosage",
"medication", "symptoms", "diagnosis",
"cardiology", "dermatology", "pediatrics", "radiology",
"Tylenol", "Advil", "Lipitor", "Metformin"
])
```
#### Financial Services
```python
self.add_hints([
"checking", "savings", "IRA", "401k", "Roth",
"transfer", "deposit", "withdrawal", "wire",
"ACH", "routing number", "account number",
"mortgage", "auto loan", "credit card", "overdraft",
"social security", "date of birth", "mother's maiden name"
])
```
### Pattern Hints (Advanced)
Pattern hints use regular expressions to match and normalize spoken input. They're useful for normalizing common mishearings of brand names, capturing structured data, and handling variations in how people say things.
#### Pattern Hint Syntax
```python
self.add_pattern_hint(
hint="what STT should listen for",
pattern=r"regex pattern to match",
replace="normalized output",
ignore_case=True # optional, default False
)
```
#### Common Pattern Examples
**Brand name normalization:**
```python
self.add_pattern_hint(
hint="Acme",
pattern=r"(acme|ackme|ac me|acmee)",
replace="Acme",
ignore_case=True
)
self.add_pattern_hint(
hint="SignalWire",
pattern=r"(signal wire|signalwire|signal-wire)",
replace="SignalWire",
ignore_case=True
)
```
**Account/Order numbers:**
```python
self.add_pattern_hint(
hint="account number",
pattern=r"\d{8}",
replace="${0}"
)
self.add_pattern_hint(
hint="order ID",
pattern=r"ORD[-\s]?\d{5,8}",
replace="${0}",
ignore_case=True
)
```
**Phone numbers:**
```python
self.add_pattern_hint(
hint="phone number",
pattern=r"\d{3}[-.\s]?\d{3}[-.\s]?\d{4}",
replace="${0}"
)
```
**Email addresses:**
```python
self.add_pattern_hint(
hint="email",
pattern=r"\S+@\S+\.\S+",
replace="${0}"
)
```
**Dates:**
```python
self.add_pattern_hint(
hint="date",
pattern=r"(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)[a-z]*\s+\d{1,2}(st|nd|rd|th)?",
replace="${0}",
ignore_case=True
)
```
#### Pattern Hint Tips
**Test patterns first:** Before adding pattern hints, test your regex at a site like regex101.com. STT output may vary from what you expect.
**Start simple:** Begin with basic patterns and refine based on actual transcription errors you observe.
**Use capture groups carefully:** `${0}` = entire match, `${1}` = first capture group, `${2}` = second capture group, etc.
**Debug with logging:** Enable debug logging to see what STT produces, then craft patterns to match.
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```
**Order matters:** If multiple patterns could match, they're evaluated in registration order. Put more specific patterns first.
### Organizing Hints
For large hint lists, organize by category:
```python
class OrganizedHintsAgent(AgentBase):
BRAND_HINTS = ["Acme", "Acme Pro", "Acme Enterprise"]
ACTION_HINTS = ["account", "billing", "refund", "cancel"]
SUPPORT_HINTS = ["representative", "supervisor", "escalate"]
def __init__(self):
super().__init__(name="organized-hints")
self.add_language("English", "en-US", "rime.spore")
self.add_hints(self.BRAND_HINTS)
self.add_hints(self.ACTION_HINTS)
self.add_hints(self.SUPPORT_HINTS)
```
### Dynamic Hints
Add hints based on context:
```python
class DynamicHintsAgent(AgentBase):
DEPARTMENT_HINTS = {
"sales": ["pricing", "quote", "demo", "trial", "discount"],
"support": ["ticket", "bug", "error", "fix", "issue"],
"billing": ["invoice", "payment", "refund", "charge"]
}
def __init__(self):
super().__init__(name="dynamic-hints")
self.add_language("English", "en-US", "rime.spore")
self.add_hints(["Acme", "account", "help"])
def on_swml_request(self, request_data=None, callback_path=None, request=None):
call_data = (request_data or {}).get("call", {})
called_num = call_data.get("to", "")
if "555-1000" in called_num:
self.add_hints(self.DEPARTMENT_HINTS["sales"])
elif "555-2000" in called_num:
self.add_hints(self.DEPARTMENT_HINTS["support"])
else:
self.add_hints(self.DEPARTMENT_HINTS["billing"])
```
### Hint Best Practices
**DO:**
* Hint brand names and product names
* Hint technical terms specific to your domain
* Hint common employee/customer names
* Hint acronyms and abbreviations
* Test with actual callers to find missed words
**DON'T:**
* Hint common English words (already recognized well)
* Add hundreds of hints (quality over quantity)
* Hint full sentences (single words/short phrases work best)
* Forget to update hints when products/terms change
### Testing Hints
Use swaig-test to verify hints are included:
```bash
## View SWML including hints
swaig-test my_agent.py --dump-swml | grep -A 20 "hints"
```
Check the generated SWML for the hints array:
```json
{
"version": "1.0.0",
"sections": {
"main": [{
"ai": {
"hints": [
"Acme",
"SignalWire",
"account",
"billing"
]
}
}]
}
}
```
### Complete Example
```python
#!/usr/bin/env python3
## hinted_agent.py - Agent with speech recognition hints
from signalwire import AgentBase, FunctionResult
class HintedAgent(AgentBase):
def __init__(self):
super().__init__(name="hinted-agent")
self.add_language("English", "en-US", "rime.spore")
self.add_hints(["Acme", "Acme Pro", "Acme Enterprise", "AcmePay", "AcmeCloud"])
self.add_hints(["SKU", "A100", "A200", "A300", "PRO100", "ENT500"])
self.add_hints(["account", "billing", "invoice", "refund", "cancel", "upgrade", "downgrade", "representative", "supervisor"])
self.add_hints(["API", "webhook", "integration", "OAuth", "SSO", "MFA"])
self.prompt_add_section("Role", "You are a customer service agent for Acme Corporation.")
self.define_tool(
name="lookup_product",
description="Look up product by SKU",
parameters={
"type": "object",
"properties": {
"sku": {"type": "string", "description": "Product SKU like A100 or PRO100"}
},
"required": ["sku"]
},
handler=self.lookup_product
)
def lookup_product(self, args, raw_data):
sku = args.get("sku", "").upper()
products = {
"A100": "Acme Basic - $99/month",
"A200": "Acme Standard - $199/month",
"A300": "Acme Premium - $299/month",
"PRO100": "Acme Pro - $499/month",
"ENT500": "Acme Enterprise - Custom pricing"
}
if sku in products:
return FunctionResult(f"{sku}: {products[sku]}")
return FunctionResult(f"SKU {sku} not found.")
if __name__ == "__main__":
agent = HintedAgent()
agent.run()
```
```typescript
import { AgentBase, FunctionResult } from 'signalwire-agents';
const agent = new AgentBase({ name: "hinted-agent" });
agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rime.spore' });
agent.addHints(['Acme', 'Acme Pro', 'Acme Enterprise', 'AcmePay', 'AcmeCloud']);
agent.addHints(['SKU', 'A100', 'A200', 'A300', 'PRO100', 'ENT500']);
agent.addHints(['account', 'billing', 'invoice', 'refund', 'cancel', 'upgrade', 'downgrade', 'representative', 'supervisor']);
agent.addHints(['API', 'webhook', 'integration', 'OAuth', 'SSO', 'MFA']);
agent.promptAddSection('Role', 'You are a customer service agent for Acme Corporation.');
const products: Record = { 'A100': 'Acme Basic - $99/month', 'A200': 'Acme Standard - $199/month', 'A300': 'Acme Premium - $299/month', 'PRO100': 'Acme Pro - $499/month', 'ENT500': 'Acme Enterprise - Custom pricing' };
agent.defineTool({ name: 'lookup_product', description: 'Look up product by SKU', parameters: { type: 'object', properties: { sku: { type: 'string', description: 'Product SKU like A100 or PRO100' } }, required: ['sku'] }, handler: async (args) => { const sku = (args.sku as string).toUpperCase(); return new FunctionResult(products[sku] ? `${sku}: ${products[sku]}` : `SKU ${sku} not found.`); } });
agent.run();
```
### Next Steps
You now know how to build and configure agents. Next, learn about [SWAIG functions][swaig-functions] to add custom capabilities.