Skip to main content
Solutions to common issues when building with ToughTongue AI.

​
Iframe Issues

Symptoms: Microphone button is grayed out or not respondingSolutions:
  1. Ensure HTTPS: Microphone access requires HTTPS in production
    • Use http://localhost for local development
    • Deploy to HTTPS-enabled hosting in production
  2. Check Browser Permissions:
    • Click the lock icon in the address bar
    • Ensure microphone permission is set to “Allow”
  3. Verify iframe attributes: 
    <iframe
  src="..."
  allow="microphone"  ← Make sure this is present
></iframe>
  4. Test in supported browsers:
    • ✅ Chrome (recommended)
    • ✅ Firefox
    • ⚠️ Safari (limited support)
    • ❌ Internet Explorer (not supported)
Symptoms: Blank iframe or loading errorSolutions:
  1. Verify Scenario ID: Check that your scenario ID is correct 
    <!-- Wrong -->
<iframe src=".../embed/abc123"></iframe>

<!-- Right -->
<iframe src=".../embed/YOUR_ACTUAL_SCENARIO_ID"></iframe>
  2. Check is_public setting:
    • Scenario must have is_public: true
    • Check in dashboard or via API: 
      const scenario = await fetch(`/api/scenarios/${id}`).then(r => r.json());
console.log('is_public:', scenario.is_public);
  3. Review browser console:
    • Open DevTools (F12)
    • Check Console tab for errors
    • Look for CORS or CSP errors
  4. Check Content Security Policy: 
    Content-Security-Policy: frame-src https://app.toughtongueai.com;
Symptoms: Not receiving onStart or onStop eventsSolutions:
  1. Verify origin check: 
    window.addEventListener('message', (event) => {
  // Don't be too strict with origin check during debugging
  console.log('Received from:', event.origin);
  
  if (event.origin !== 'https://app.toughtongueai.com') {
    console.warn('Origin mismatch!');
    // return;  // Comment out during debugging
  }
  
  console.log('Event data:', event.data);
});
  2. Check event listener timing:
    • Ensure listener is set up before iframe loads
    • Or set up in DOMContentLoaded or useEffect
  3. Verify iframe URL:
    • Events only work with embed URLs
    • Not regular app URLs

​
API Issues

Symptoms: API returns 401 errorSolutions:
  1. Check Authorization header: 
    // Wrong
headers: { 'Authorization': 'YOUR_TOKEN' }

// Right
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  2. Verify token is valid: 
    curl -X POST https://api.toughtongueai.com/api/public/test \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "test"}'
  3. Check token hasn’t expired:
    • Tokens don’t expire by default
    • But can be manually revoked
    • Create a new token if needed
  4. Ensure token is from correct environment:
    • Development vs. production tokens
    • Organization-scoped tokens
Symptoms: CORS policy blocks requestSolutions:
  1. Use backend proxy (recommended): 
    // Frontend: Call your backend
fetch('/api/analyze', { method: 'POST', body: ... });

// Backend: Proxy to ToughTongue AI
app.post('/api/analyze', async (req, res) => {
  const response = await fetch('https://api.toughtongueai.com/...', {
    headers: { 'Authorization': `Bearer ${process.env.TTAI_TOKEN}` }
  });
  res.json(await response.json());
});
  2. Never call API directly from frontend:
    • ❌ Exposes your API token
    • ❌ CORS issues
    • ✅ Always use backend proxy
Symptoms: Too many requests errorSolutions:
  1. Implement retry with backoff: 
    async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      await new Promise(resolve => 
        setTimeout(resolve, retryAfter * 1000)
      );
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}
  2. Cache responses:
    • Cache scenario data (rarely changes)
    • Cache session analysis results

​
Session Issues

Symptoms: 404 when fetching sessionSolutions:
  1. Wait for session to be saved:
    • Session may not be immediately available after onStop
    • Add a small delay (1-2 seconds) before fetching
  2. Verify session ID:
    • Check you’re using the full session ID
    • Not a truncated version
  3. Check permissions:
    • Ensure API token has access to the session
    • Organization-scoped tokens may have limited access
Symptoms: Analysis endpoint returns empty or incomplete dataSolutions:
  1. Wait for analysis to complete:
    • Analysis can take 5-30 seconds
    • Implement polling or show loading state
  2. Check if analysis is restricted:
    • Scenario may have restrict_analysis: true
    • Check scenario settings
  3. Verify session completed:
    • Session must be in “completed” status
    • Not “terminated” or “failed”

​
Development Issues

Solutions:
  1. Check .env file location:
    • Should be in project root
    • Not committed to git
  2. Restart development server:
    • Changes to .env require restart
  3. Verify variable names: 
    # Flask
TTAI_TOKEN=...

# Next.js
TOUGH_TONGUE_API_KEY=...
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=...  # For client-side
  4. Check loading method: 
    // Node.js
require('dotenv').config();

// Next.js (automatic in .env.local)
process.env.TOUGH_TONGUE_API_KEY
Flask:
  • Check Python version: python --version (need 3.9+)
  • Reinstall dependencies: pip install -r requirements.txt
  • Check for conflicting packages
Next.js:
  • Check Node version: node --version (need 18+)
  • Clear cache: rm -rf .next node_modules pnpm-lock.yaml
  • Reinstall: pnpm install
  • Check TypeScript errors: pnpm build

​
Best Practices

Always use HTTPS in production
Verify iframe message origins
Store API tokens in environment variables
Use backend proxy for API calls
Implement proper error handling
Add loading states for async operations
Cache API responses when appropriate
Test in multiple browsers

​
Still Having Issues?

Discord Community

Ask the community for help

API Reference

Test API endpoints

Email Support

Contact our support team

​
Debug Checklist

When debugging issues, gather this information:
  • Browser and version
  • Error messages from console
  • Network tab showing failed requests
  • Scenario ID being used
  • API token validity (test endpoint)
  • Environment (local, staging, production)
  • Steps to reproduce the issue
Include this information when asking for help for faster resolution.