Support Playbook

This document is your guide to handling support requests efficiently and professionally.

Ticket Workflow

Workflow States

Unassigned → Assigned → In Progress → Waiting on Customer → Resolved → Closed

1. Unassigned: New ticket, no one claimed it
2. Assigned: Someone is working on it (you)
3. In Progress: Evidence of work (replied, investigating)
4. Waiting on Customer: We replied, waiting for their response
5. Resolved: Issue is fixed or properly explained
6. Closed: Ticket archived, won't reopen

SLA (Service Level Agreement)

Your response time targets:

Ticket Priority Guide

Critical (P1)

• Service is down for user
• Billing error preventing payment
• Account lockout with no recovery
• Data loss or corruption reported
• Security breach or suspicious activity

→ Respond immediately, escalate to dev team if needed

High (P2)

• Upload failing for all users
• Can't log in due to broken auth
• Files disappearing or inaccessible
• Storage quota wrong (charged incorrectly)
• Subscriptions not working

→ Respond within 4 hours

Normal (P3)

• General troubleshooting questions
• Feature clarifications
• Billing questions
• Account management questions
• Feedback or suggestions

→ Respond within 24 hours

Low (P4)

• Thank you emails
• Feature requests
• Compliments
• Newsletter signups

→ Respond within 72 hours if at all

First Response Template

Subject: RE: [Original Subject] - We're here to help

Hi [Customer Name],

Thanks for reaching out! We're looking into this right now.

[Your initial assessment or question]

Quick question to help troubleshoot:
- [Specific question about their setup]

I'll follow up with you by [date/time] with more info.

Thanks,
[Your name] — Support Team

Common Issues & Solutions

Login Issues

Problem: "Can't log in"

Ask:

• What error message do you see?
• Which login method (email, Google, Discord, GitHub)?
• Can you reset your password?
• Do you have 2FA enabled?

Troubleshooting:

1. Wrong password → Send password reset link

   Send email with reset link from /api/user/reset-password

2. 2FA locked out

   Ask: Do you have backup codes?
   If yes: Use backup code to log in, then re-setup 2FA
   If no: We can disable 2FA from admin side

3. Account doesn't exist → Check email used, suggest signup

4. OAuth failed (Google/Discord/GitHub) → Suggest:

   • Clear browser cache
   • Try different browser
   • Try email/password login instead
   • Check if OAuth connection is set up on their account

Upload Issues

Problem: "Upload failing" or "Upload won't complete"

Ask:

• What file size?
• What file type?
• What's the error message?
• What browser/app?

Troubleshooting:

1. File too large → Check their plan's upload limit

   Glow: 100MB
   Flare: 500MB
   Blaze: 5GB
   Inferno/Ember/Enterprise: 10GB

   Solution: Upgrade plan or split into smaller files

2. File type blocked → We automatically scan with 71+ antivirus engines

   If .exe, .bat, .sh, etc is flagged as malware:
   "Our security system detected this as potentially unsafe"
   
   Ask: Is this a custom tool you built?
   If yes: They can submit for manual review (takes 2-3 days)

3. Storage quota exceeded → Check user's used storage

   API: /api/admin/users/[userId]/storage
   Show them: Quota: 25GB, Used: 24.5GB
   Solution: Delete old files or upgrade plan

4. Network timeout → Suggest:

   • Retry upload
   • Try different network (WiFi/ethernet)
   • Try on different device
   • Contact us if still failing

5. Quota error but shows space → Might be cache issue

   Solution: Refresh dashboard
   If still stuck: Clear localStorage and try again
   Last resort: Contact dev team

Billing Issues

Problem: "Charged wrong amount" or "Subscription issues"

Ask:

• What date were you charged?
• What plan are you on?
• Do you have any active coupons or discounts?
• Is this a renewal or new purchase?

Troubleshooting:

1. Duplicate charges → Check Stripe transactions

   API: /api/admin/users/[userId]/payments
   Look for: Payment within 24 hours of complaint
   If duplicate: Process refund and apologize

2. Billed after cancellation → Check subscription status

   API: /api/admin/subscriptions/[subscriptionId]
   If status != "canceled": Cancel properly
   Process refund for final month (if appropriate)

3. Wrong amount → Check:

   • Plan pricing (plans-overview.mdx)
   • Coupons applied
   • Tax if applicable
   • Billing cycle (monthly vs. annual)

   Common: User bought annual ($119/yr) and thought it was monthly ($9.99/mo) → Explain difference, offer cancellation with refund if within 30 days

4. Card declined → Explain: "Your card was declined. Please update your payment method in your dashboard and retry."

   If they update and it still fails: Escalate to billing team

Storage/Quota Issues

Problem: "Storage showing wrong" or "Can't upload because storage full"

Diagnostic:

# Check user's storage
curl -H "Authorization: Bearer ADMIN_KEY" \
  https://embrly.ca/api/admin/users/[userId]/storage
 
Response:
{
  "quota": 25000000000,        // 25GB
  "used": 24500000000,         // 24.5GB
  "remaining": 500000000       // 500MB
}

Solutions:

1. Actually out of space → They need to delete files or upgrade

   • "You're using 98% of your quota. Delete unused files or upgrade for more storage."

2. Shows full but dashboard shows space → Cache issue

   • Refresh dashboard
   • Clear browser cache
   • Try different browser
   • Wait 15 min (might be calculation delay)

3. Used storage shows wrong → Might be:

   • Files being compressed (OCR creates thumbnails)
   • Deleted files still in recycle bin
   • System error calculating total

   Action: Check Prisma for user's files:

   SELECT SUM(size) FROM File WHERE userId = [userId]

   If result differs from API, escalate to dev team

Custom Domain Issues

Problem: "My custom domain doesn't work" or "SSL errors"

Ask:

• What's the domain?
• What error do you see?
• Did you update DNS records?
• How long ago did you set it up?

Troubleshooting:

1. DNS not updated yet

   They need to add CNAME record:
   subdomain.example.com CNAME -> embrly.ca
   
   Can take 24-48 hours to propagate

2. Domain registered but DNS not changed → They need to:

   • Go to their domain registrar (GoDaddy, Namecheap, etc)
   • Find DNS settings
   • Add the CNAME record
   • Wait 24 hours

3. SSL certificate not issued → Might be:

   • CNAME not set up correctly (verify with dig/nslookup)
   • DNS takes 24+ hours before cert auto-generates
   • Tell them to wait 24 hours and try again

4. Domain appears to work but is slow → Check:

   curl -I https://custom.domain.com
   # Check if returning Cloudflare 200 OK

   If yes, might just be slow → Check their content size

Commands to help troubleshoot:

# Check if CNAME is set
dig custom.domain.com
# Should show: custom.domain.com CNAME embrly.ca.
 
# Check if they can access Emberly via that domain
curl -I https://custom.domain.com

OCR and Image Processing

Problem: "OCR isn't working" or "Images showing placeholder"

Ask:

• What file format?
• What size?
• Can you see the image?
• Are text results not showing?

Info to share:

• OCR is available on all plans (Spark through Enterprise)
• Works on PNG, JPG, PDF
• Processes automatically when file is uploaded
• Takes 5-30 seconds depending on file complexity

Troubleshooting:

1. Image uploads but takes time → Normal, might be:

   • Large file needs processing time
   • System busy with other files
   • Ask them to wait 5 minutes

2. Text not appearing → Explain: "OCR extracts text from images. If no text appears, the image might be too blurry, too small, or not contain readable text."

   Ask them to:

   • Check image is legible
   • Re-upload clearer version
   • Check settings in dashboard

3. Specific language not working → Check:

   • OCR supports 100+ languages
   • If text is handwritten, accuracy is lower
   • Fonts must be reasonably standard

   Solution: Re-upload or try different image

Two-Factor Authentication (2FA)

Problem: "Lost 2FA device" or "Can't access backup codes"

Troubleshooting:

1. Still have backup codes

   They can:
   1. Click "Can't access authenticator?"
   2. Enter backup code
   3. Log in
   4. Disable and re-setup 2FA

2. Lost backup codes and device

   We can help:
   1. Verify their identity (email + security questions or ID)
   2. Disable 2FA from our end
   3. They can re-setup fresh 2FA
   
   Security note: 2FA is authentication, so be thorough in verification

3. Code keeps showing wrong

   Might be:
   - Phone time is out of sync → Fix system clock
   - App still has old device time → Reinstall app
   - Using expired backup code → Get new code set

Escalation Process

When to escalate a ticket:

To Development Team

• Technical bug (file won't upload, quota calculation wrong)
• API issue (returns wrong data, crashes)
• Database issue (data corruption, missing files)
• Performance issue (whole system slow)

Email template:

Subject: [ESCALATION] [Ticket #] - Brief description

Customer: [Email]
Issue: [What they reported]
Evidence: [What you found]
Reproduction: [How to repeat it]
Impact: [How many users affected]
Urgency: [Critical/High/Normal]

Why escalating: [Explain it's beyond support scope]

To Billing Team

• Refund requests
• Subscription management issues
• Coupon/discount problems
• Tax or legal billing issues

To Moderation Team

• Account security concerns
• Potential abuse or TOS violation
• Reports of malicious behavior

To Executive/Management

• Expensive customer (enterprise) with serious issue
• Legal threat or PR risk
• Multiple customers with same critical issue
• Demand for CEO response

Response Templates

Generic Good Outcome

Hi [Name],

Great news! I found the issue. [Brief explanation of what was wrong].

Here's what I did to fix it:
[Step-by-step what you did]

Everything should be working now. [Next steps if needed].

Please let me know if you have any other issues!

Thanks for your patience,
[Your name]

Explaining Limitation

Hi [Name],

Thanks for asking about [feature]. Here's how it works:

[Explanation of feature]

Currently, [limitation]. We're working on [improvement] in the future.

In the meantime, you can [workaround if available].

Let me know if that helps!

[Your name]

Escalation Explanation

Hi [Name],

Thanks for reporting this. This sounds like a technical issue that needs our development team to investigate.

I've escalated this to our engineering team and they'll look into it. You should hear back from them within 24 hours.

Reference number: [Ticket #]

Thanks for your patience!

[Your name]

Rejection (Refund Request Outside Policy)

Hi [Name],

Thanks for reaching out about a refund.

I reviewed your account and see you've been subscribed for [X days]. Our refund policy allows refunds within 30 days of purchase if the service isn't working as intended.

Since your use case is [explain], we're unable to process a refund. However, you can cancel anytime if you'd like.

If you believe there's a technical issue preventing you from using the service, I'd be happy to help troubleshoot!

[Your name]

Metrics & Tracking

Daily Check-in

• How many unassigned tickets are there?
• What's the average age of unassigned tickets?
• Who has the most open tickets?

Weekly Report

• Tickets handled: [N]
• Average response time: [X hours]
• Customer satisfaction: [N%]
• Escalations: [N]

Track In Dashboard

Use the support ticket system to:

• Log all tickets
• Add time spent per ticket
• Document resolutions
• Log escalations

Tips for Great Support

1. Be Empathetic — User is frustrated, acknowledge that

   • "I understand how frustrating that must be"

2. Be Clear — Avoid jargon

   • Bad: "Your quota calculation failed due to cache invalidation"
   • Good: "Your storage number was outdated. Let me refresh it for you."

3. Be Complete — Answer the question fully

   • Don't leave them guessing
   • Explain the why, not just the what

4. Be Quick — Respond fast, even if just to say "I'm looking into this"

5. Be Professional — Don't make promises you can't keep

   • "I'll have this fixed immediately" - risky
   • "I'll investigate and get back to you within 4 hours" - good

6. Document Everything — Log your findings

   • Future support staff will thank you
   • Helps track patterns

Common Mistakes

Avoid: Promise a feature fix without confirmation

• You don't know if dev team can do it

Do this instead: "I've escalated this to engineering. They'll assess and get back to us."

Avoid: Tell customer to delete important data

• They might regret it

Do this instead: "You could delete old files to free space. Want help identifying which ones?"

Avoid: Process refund without checking company policy

• You might be giving away money

Do this instead: "Let me check our refund policy and get back to you."

Avoid: Get frustrated or sarcastic with customer

• They're paying you

Do this instead: Take a break, come back with fresh perspective

Support FAQ

Q: What if they're asking about a feature we don't have? A: Explain what we do have. Suggest workarounds. Log as feature request.

Q: What if they want a refund but policy says no? A: Politely explain policy. Offer to troubleshoot instead.

Q: What if they're abusive? A: You can close the ticket and escalate to moderation team.

Q: How long should I spend on one ticket? A: Start with 15 min. If not close to resolution, escalate.

Q: Should I give special treatment to enterprise customers? A: Yes. Prioritize their tickets. Escalate faster. Get manager involved sooner.

Resources

• Plans Overview — Feature limits
• Feature Matrix — What's in each plan
• FAQ — Common questions
• Admin API Reference — Tools to investigate issues
• Stripe Dashboard — Check billing
• Database — Check raw data when needed