​

Integration Troubleshooting

​

Don’t Panic - Most Issues Are Simple to Fix!

Integration problems can seem scary, but most have simple solutions. The key is to approach them systematically: start with the basics, check the obvious things first, and work your way up to more complex solutions. Remember: integrations are designed to be reliable. If something isn’t working, it’s usually a quick fix away from being perfect again.

​

Quick Diagnostic Questions

Before diving into detailed troubleshooting, ask yourself these questions:

​

Basic Health Check

1. When did it last work? - helps identify if something changed
2. Did you make any changes recently? - new settings, password changes, etc.
3. Is it completely broken or just slow? - different problems need different solutions
4. Does it affect all customers or just some? - helps narrow down the cause
5. Are other parts of your system working normally? - isolates the problem

​

Quick Tests

• Try asking your AI agent a simple question related to the integration
• Check if you can still log into the connected platform (Shopify, Airtable, etc.)
• Look for any error messages in your dashboard or inbox
• Test from a different device or browser to rule out local issues

​

Common Integration Problems and Fast Fixes

​

Problem 1: “Integration Shows Connected But AI Can’t Access Data”

What you’ll see:

• Dashboard shows integration as “Connected”
• AI agent gives generic responses instead of specific data
• No error messages, but integration features don’t work

Quick fixes to try first:

1. Check agent settings - make sure integration capabilities are enabled
   • Go to your AI agent settings
   • Look for “Capabilities” or “E-commerce” section
   • Toggle on the features you want (product recommendations, order tracking, etc.)
   • Save changes
2. Test with specific questions:
   • “What’s the status of order #12345?” (for e-commerce integrations)
   • “Do you have [specific product] in stock?”
   • “What do you know about customer [name]?” (for database integrations)
3. Reconnect the integration:
   • Go to Integrations page
   • Disconnect the problematic integration
   • Wait 30 seconds
   • Reconnect following the setup process

​

Problem 2: “Connection Keeps Failing During Setup”

What you’ll see:

• Error messages during authorization
• Redirected back to integrations page without “Connected” status
• “Authorization failed” or similar messages

Quick fixes:

1. Check your login credentials:
   • Make sure you’re using the right username/password
   • Try logging into the platform directly first
   • Ensure your account has admin permissions
2. Browser issues:
   • Allow popups for your site
   • Try incognito/private mode
   • Clear browser cache and cookies
   • Try a different browser (Chrome usually works best)
3. Platform-specific checks:
   • Shopify: Make sure your store URL is correct (yourstore.myshopify.com)
   • Airtable: Verify your Personal Access Token is copied correctly
   • Meta: Ensure you have Facebook Business Manager access

​

Problem 3: “Integration Worked Yesterday But Not Today”

What you’ll see:

• Integration was working fine, then suddenly stopped
• No changes made on your end
• Other parts of your system still work

Quick fixes:

1. Check platform status:
   • Visit the platform’s status page (like status.shopify.com)
   • Look for maintenance announcements
   • Check if the platform is experiencing outages
2. Token/password refresh:
   • Some integrations require periodic re-authorization
   • Go to Integrations page and look for “Reconnect” buttons
   • Re-authorize even if it shows as connected
3. Wait and retry:
   • Temporary issues often resolve themselves
   • Wait 15-30 minutes and test again
   • Try during off-peak hours if possible

​

Problem 4: “AI Gives Wrong or Outdated Information”

What you’ll see:

• AI provides incorrect product prices or availability
• Order status information is wrong
• Customer data seems outdated

Quick fixes:

1. Force a data sync:
   • Go to integration settings
   • Look for “Sync Now” or “Refresh Data” button
   • Wait for sync completion before testing
2. Check source data:
   • Log into the connected platform directly
   • Verify the information is correct there
   • Make sure products are published/active
3. Clear cache:
   • Some systems cache data for performance
   • Look for cache clearing options in settings
   • Wait 10-15 minutes for fresh data to load

​

Platform-Specific Troubleshooting

​

Shopify Integration Issues

​

”Shopify shows connected but no product data”

Common causes:

• Products not published to “Online Store” channel
• Store is password protected
• Inventory tracking not enabled

Solutions:

1. Check product publication:
   • Go to Shopify admin → Products
   • Make sure products are published to “Online Store”
   • Verify products have descriptions and prices
2. Store accessibility:
   • Remove password protection temporarily
   • Ensure store is not in “Coming Soon” mode
   • Check that Shopify Payments or payment provider is set up

​

”Order tracking not working”

Common causes:

• Orders in draft status
• Fulfillment information missing
• Order number format issues

Solutions:

1. Check order status:
   • Orders must be “confirmed” not “draft”
   • Fulfillment information must be complete
   • Try with recent, confirmed orders
2. Test with different order formats:
   • Try full order number (like #1001)
   • Try just the number (1001)
   • Check if orders have tracking numbers

​

Airtable Integration Issues

​

”Can’t connect to Airtable”

Common causes:

• Wrong Personal Access Token
• Token doesn’t have correct permissions
• Account permissions insufficient

Solutions:

1. Create new token:
   • Go to airtable.com/create/tokens
   • Create new token with “data.records:read” scope
   • Copy entire token carefully (no extra spaces)
2. Check account permissions:
   • Make sure you’re creator or collaborator on the base
   • Verify base isn’t in a restricted workspace
   • Try with a base you definitely own

​

”AI can’t find customer data”

Common causes:

• Data in wrong format
• Table/field names don’t match expectations
• Records not properly linked

Solutions:

1. Standardize data format:
   • Use consistent field names (First Name, Last Name, Email)
   • Ensure all records have required fields filled
   • Remove special characters from field names
2. Test with simple data:
   • Create a test record with basic information
   • Ask AI to find this specific test customer
   • Gradually add complexity once basic lookup works

​

Meta Business Integration Issues

​

”Catalog sync failing”

Common causes:

• Products don’t meet Meta requirements
• Catalog not properly configured
• Business verification issues

Solutions:

1. Check product requirements:
   • Products must have title, description, price
   • Images must meet Meta specifications
   • No prohibited content or categories
2. Verify business account:
   • Business Manager account must be verified
   • Catalog must be approved for commerce
   • Check for any policy violations

​

”Can’t access advertising data”

Common causes:

• Insufficient permissions for ad account
• No active campaigns
• Account restrictions

Solutions:

1. Check ad account access:
   • Verify you have admin access to ad account
   • Ensure ad account is active and in good standing
   • Try with an account that has recent ad activity

​

Regional Platform Issues (Salla/Zid)

​

“Arabic content not displaying correctly”

Common causes:

• Character encoding issues
• Right-to-left text problems
• Language settings misconfigured

Solutions:

1. Check character encoding:
   • Ensure Arabic text is properly encoded
   • Verify language settings in the platform
   • Test with simple Arabic phrases first
2. Regional settings:
   • Set timezone to local region
   • Configure currency and pricing correctly
   • Ensure compliance with local regulations

​

Advanced Troubleshooting

​

When Basic Fixes Don’t Work

​

Check Integration Logs

1. Look for error messages in your dashboard
2. Check browser console for JavaScript errors (F12 → Console)
3. Review recent activity in your connected platforms
4. Look for pattern in failures - specific times, customers, or requests

​

Test Integration Components Separately

1. Test the connection - can you authorize successfully?
2. Test data access - can you see the data in the source platform?
3. Test AI responses - try very simple questions first
4. Test with different data - use different products, customers, or orders

​

Network and Performance Issues

1. Check internet connection - try from different network
2. Test at different times - some issues are time-dependent
3. Monitor response times - slow responses might indicate server issues
4. Try from different devices - mobile vs. desktop, different browsers

​

Data Format and Compatibility

​

Common Data Problems

• Missing required fields - integrations need specific data points
• Inconsistent formatting - dates, phone numbers, prices must be standardized
• Special characters - some characters cause encoding issues
• Empty or null values - missing data can break integration logic

​

Solutions

1. Standardize your data:
   • Use consistent date formats
   • Standardize phone number formats
   • Ensure all required fields are populated
   • Remove or escape special characters
2. Test with clean data:
   • Create test records with perfect data
   • Verify integration works with clean test data
   • Gradually identify problematic data

​

Getting Help When You’re Stuck

​

Information to Collect Before Contacting Support

Always include:

1. What integration you’re having trouble with
2. What you were trying to do - step by step
3. What actually happened - exact error messages
4. When it started - was it working before?
5. What you’ve already tried - saves time for support team

For connection issues specifically:

• Screenshots of error messages
• Browser and version you’re using
• Whether you can log into the platform directly
• Your account type/permissions on the connected platform

For data access issues specifically:

• Examples of questions that don’t work
• Screenshots of AI responses
• Examples of data in your source system
• Whether the integration shows as “Connected”

​

When to Contact Support vs. Keep Trying

Contact support when:

• You’ve tried all basic troubleshooting steps
• Error messages mention “server error” or “contact support”
• Integration worked before but stopped after platform updates
• Multiple customers reporting the same issue
• You see billing or account restriction messages

Keep trying on your own when:

• Issue started right after you made changes
• Only affects specific products/customers/orders
• Works sometimes but not others
• Similar to problems you’ve solved before
• Error messages suggest configuration issues

​

Early Warning Signs

Watch for these indicators:

• Slower than usual AI responses when using integration features
• Customer complaints about incorrect information
• Occasional “I don’t know” responses when AI should have the data
• Inconsistent responses to the same questions

When you notice these signs: Do proactive maintenance (test integrations, check connections, verify data) before they become bigger problems. Remember: Integrations are powerful but require some care and maintenance. Most issues are straightforward to fix once you know what to look for. When in doubt, start with the simplest explanation and work your way up to more complex solutions!