qa-sources

Q&A Sources#

Create explicit question-answer pairs for your agent. Q&A sources have the highest retrieval priority, making them perfect for FAQs and common customer questions.

What are Q&A Sources?#

Q&A sources are structured question-answer pairs that your agent uses to provide specific, accurate responses. Unlike documents or text sources, Q&A pairs:

• ✅ Have high retrieval priority (more likely to be used)
• ✅ Support multiple question variations (different ways to ask the same thing)
• ✅ Can include images in answers
• ✅ Are stored in the "examples" namespace for prioritized retrieval

How It Works#

1. Create Q&A Pair → Question(s) + Answer + Optional Image
   ↓
2. Immediate Chunking → ChunkManager.storeChunksWithNamespace()
   - Chunk size: 10,000 characters (larger than docs)
   - Namespace: "examples" (high priority)
   ↓
3. Generate Embeddings → embedding-generation queue
   - Creates embeddings for ALL question variations
   ↓
4. Status: Ready (30-60 seconds)

Processing Time: 30-60 seconds per Q&A pair

Step-by-Step: Adding a Q&A Source#

1. Navigate to Knowledge Base#

1. Go to your agent's dashboard
2. Click Knowledge Base tab
3. Click Add Source → Q&A

2. Enter Your Question#

Question (required)

• The main question users might ask
• Be natural - write it as users would ask it
• Examples:
  • "What are your business hours?"
  • "How much does the Pro plan cost?"
  • "How do I reset my password?"

Alternative Questions (optional but recommended)

• Different ways users might ask the same thing
• Click Add Alternative to add more variations
• Examples for "What are your business hours?":
  • "When are you open?"
  • "What time do you close?"
  • "Are you open on weekends?"

Why alternatives matter: Users ask the same question in different ways. More variations = better match rate.

3. Enter Your Answer#

Answer (required)

• The response your agent will give
• Be clear, concise, and complete
• Can include:
  • Multiple paragraphs
  • Bullet points
  • Links
  • Formatting (though plain text recommended)

Good answer example:

We're open Monday through Friday from 9:00 AM to 5:00 PM EST.

Weekend hours:
- Saturday: 10:00 AM - 3:00 PM
- Sunday: Closed

Holiday hours may vary. We're closed on Thanksgiving, Christmas, and New Year's Day.

Bad answer example:

check website

4. Add Image (Optional)#

When to add images:

• Visual instructions (screenshots, diagrams)
• Product photos
• Charts or graphs
• Infographics

Supported formats: JPG, PNG, GIF, WEBP Max size: 5MB per image

How to add:

1. Click Add Image
2. Drag and drop or browse for file
3. Image preview appears
4. Image is stored in Supabase Storage

Note: Images are displayed to users but not analyzed by default (premium feature: AI Vision analysis).

5. Configure Settings#

Priority (optional)

• Q&A sources default to high priority (0.7)
• Can be increased to 1.0 for critical info
• Usually no need to change

Mark as Price Information (checkbox)

• Check if this is pricing-related
• Auto-sets priority to 1.0 (highest)
• Pricing queries will prioritize this Q&A

6. Add and Train#

1. Click Add Q&A Source
2. Source appears in "Processing" status
3. Click Train Agent
4. Wait 30-60 seconds for "Ready" status

Your agent will now use this Q&A to answer matching questions!

Best Practices#

Writing Good Questions#

✅ Do:

• Write naturally (as users would ask)
• Include common variations
• Use conversational language
• Cover different phrasings

❌ Don't:

• Use robotic or formal language only
• Add only one question variation
• Include typos (unless users commonly make them)
• Make questions too specific

Example:

Good (multiple variations):

• Main: "How do I cancel my subscription?"
• Alt 1: "Can I cancel anytime?"
• Alt 2: "What's the cancellation policy?"
• Alt 3: "I want to stop my subscription"

Bad (single, rigid):

• "What is the process for subscription cancellation?"

Writing Good Answers#

✅ Do:

• Be clear and concise
• Include all necessary details
• Use step-by-step instructions when appropriate
• Provide examples
• Include relevant links or contact info

❌ Don't:

• Be vague ("check our website")
• Use jargon without explanation
• Leave out important details
• Make answers too long (>500 words)

Example:

Good answer:

To cancel your subscription:

1. Log in to your account at alonchat.com
2. Go to Settings → Billing
3. Click "Cancel Subscription"
4. Confirm cancellation

You'll retain access until the end of your current billing period.
No refunds for partial months, but you won't be charged again.

Need help? Contact support@alonchat.com

Bad answer:

You can cancel in settings.

Using Images Effectively#

When images help:

• Step-by-step visual guides
• Product features ("What does the Pro dashboard look like?")
• Diagrams or flowcharts
• Before/after comparisons

When images aren't needed:

• Simple text answers
• Policies or rules
• Contact information
• Hours or pricing

Image optimization:

• Compress images (use tools like TinyPNG)
• Use appropriate dimensions (800-1200px width)
• Keep file size under 1MB for faster loading
• Use clear, high-quality images

Common Use Cases#

1. Pricing Questions#

Q: "How much does the Pro plan cost?"

Alternatives:

• "What's the price of Pro?"
• "Pro plan pricing"
• "How much is Pro per month?"

Answer:

The Pro plan costs $99 per month (or $990 per year - save 2 months!).

Includes:
- 10,000 messages per month
- 5 agents
- Priority support
- Advanced analytics
- API access

Upgrade anytime from your dashboard: Settings → Billing → Upgrade

Is Price: ✓ Yes

2. Technical Support#

Q: "How do I reset my password?"

Alternatives:

• "Forgot my password"
• "Can't log in"
• "Password reset"

Answer:

To reset your password:

1. Go to alonchat.com/login
2. Click "Forgot Password?" below the login form
3. Enter your email address
4. Check your inbox for a reset link (check spam if not there)
5. Click the link and create a new password

The reset link expires in 1 hour.

Still having trouble? Email support@alonchat.com

Image: Screenshot showing "Forgot Password" link location

3. Feature Questions#

Q: "Can I integrate AlonChat with my website?"

Alternatives:

• "Website integration"
• "Add chat widget to my site"
• "Embed AlonChat on website"

Answer:

Yes! You can embed AlonChat on your website using our chat widget.

How to embed:
1. Go to your agent's dashboard
2. Click "Embed" in the top menu
3. Copy the widget code
4. Paste it in your website's HTML (before </body>)

The widget is fully customizable (colors, position, greeting message).

Need help? Check our embedding guide: docs.alonchat.com/embed

Image: Screenshot of embed code settings

Managing Q&A Sources#

Editing Q&A Pairs#

1. Find the Q&A in your Knowledge Base list
2. Click Edit (pencil icon)
3. Update question, alternatives, answer, or image
4. Click Save
5. Re-train your agent for changes to take effect

Organizing Q&A Sources#

Naming convention:

• Use descriptive names: "Q&A: Pricing", "Q&A: Password Reset"
• Group related Q&As with prefixes: "Support: ", "Billing: ", "Product: "

Archiving:

• Archive outdated Q&As (old pricing, deprecated features)
• Don't delete - you might need them later

Bulk Q&A Management#

For 10+ Q&As:

1. Create a CSV file with columns: Question, Alternatives (pipe-separated), Answer
2. Use the bulk import feature (Pro plan)
3. Review imported Q&As
4. Train your agent

CSV example:

Question,Alternatives,Answer
"What are your hours?","When are you open?|What time do you close?","We're open Mon-Fri 9-5 PM EST."
"How do I cancel?","Cancel subscription|Stop billing","Go to Settings → Billing → Cancel."

Troubleshooting#

"Agent Not Using My Q&A"#

Causes:

• Question asked doesn't match your variations
• Other sources have higher similarity scores
• Forgot to train after adding Q&A

Solutions:

• Add more question variations
• Mark as "Is Price" if pricing-related
• Test with exact questions you wrote
• Re-train your agent

"Image Not Displaying"#

Causes:

• Image file too large (>5MB)
• Unsupported format
• Upload incomplete

Solutions:

• Compress image to under 5MB
• Convert to JPG or PNG
• Re-upload image
• Check browser console for errors

"Q&A Conflicts with Other Sources"#

Problem: Multiple sources have similar information

Solution:

• Q&A sources have high priority - they should win
• If not, increase Q&A priority to 1.0
• Archive conflicting sources if Q&A is more accurate

Q&A vs Text vs File#

When to use Q&A:

• You have specific questions with known answers
• Need high retrieval priority
• Want to include images
• FAQ-style content

When to use Text instead:

• General information without specific questions
• Long-form content
• Policies or guides

When to use File instead:

• Content already in a document
• Need to preserve complex structure
• Multiple pages or sections

API Reference#

For developers adding Q&A sources programmatically:

Endpoint: POST /api/agents/[id]/sources/qa

Request:

const response = await fetch(`/api/agents/${agentId}/sources/qa`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`
  },
  body: JSON.stringify({
    question: 'What are your hours?',
    alternatives: ['When are you open?', 'What time do you close?'],
    answer: 'We\'re open Monday-Friday 9 AM to 5 PM EST.',
    priority: 0.7,
    isPrice: false,
    image: null // Or base64-encoded image data
  })
})

Response:

{
  "success": true,
  "source": {
    "id": "source-uuid",
    "name": "Q&A: What are your hours?",
    "type": "qa",
    "status": "processing"
  }
}

Limits#

Next Steps#

• Text Sources - Add unstructured text content
• File Sources - Upload documents
• Training Your Agent - Best practices for training
• Testing Your Agent - Verify Q&As work correctly