Skip to main content

Agent Won’t Connect

Symptom

Agent fails to connect to the platform

Common Causes

  1. Invalid Credentials
  2. Network Issues
  3. Firewall Blocking
  4. Platform Unavailable

Solutions

1. Verify Credentials

# Check API key format
api_key = os.getenv('CONVERSIMPLE_API_KEY')
print(f"API Key: {api_key[:10]}...")  # Should start with cs_live or cs_test

# Check customer ID
customer_id = os.getenv('CONVERSIMPLE_CUSTOMER_ID')
print(f"Customer ID: {customer_id}")  # Should start with cust_

2. Test Platform Connectivity

import aiohttp

async def test_connection():
    try:
        async with aiohttp.ClientSession() as session:
            async with session.get('https://app.conversimple.com/health') as response:
                print(f"Platform status: {response.status}")  # Should be 200
    except Exception as e:
        print(f"Connection error: {e}")

asyncio.run(test_connection())

3. Check WebSocket URL

# Correct URLs
production_url = "wss://app.conversimple.com/sdk/websocket"  # Production
dev_url = "ws://localhost:4000/sdk/websocket"  # Local development

# Verify your URL
agent = ConversimpleAgent(
    api_key=api_key,
    customer_id=customer_id,
    platform_url=production_url  # Check this is correct
)

Connection Drops

Symptom

Agent connects but disconnects frequently

Solutions

Enable Auto-Reconnect

class RobustAgent(ConversimpleAgent):
    async def start_with_retry(self, max_retries=3):
        """Start with automatic retry"""
        for attempt in range(max_retries):
            try:
                await self.start()
                print("✅ Connected successfully")
                return
            except Exception as e:
                if attempt < max_retries - 1:
                    wait_time = 2 ** attempt
                    print(f"Retry in {wait_time}s...")
                    await asyncio.sleep(wait_time)
                else:
                    raise

Monitor Connection

class MonitoredAgent(ConversimpleAgent):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.connected = False

    async def start(self):
        """Track connection status"""
        await super().start()
        self.connected = True
        print("Connected to platform")

    def on_error(self, error_type, message, details):
        """Handle disconnection"""
        if error_type == "connection_error":
            self.connected = False
            print("Lost connection - will retry")

Timeout Errors

Symptom

Connection attempts timeout

Solutions

Increase Timeout

agent = ConversimpleAgent(
    api_key=api_key,
    customer_id=customer_id,
    connection_timeout=30  # Increase to 30 seconds
)

Check Network

# Test DNS resolution
nslookup app.conversimple.com

# Test connectivity
ping app.conversimple.com

# Test WebSocket
curl -i -N -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  https://app.conversimple.com/sdk/websocket

Firewall Issues

Symptom

Connection blocked by firewall

Solutions

Allow WebSocket Connections

# Allow outbound WebSocket connections on port 443
sudo ufw allow out 443/tcp

# For corporate firewalls, ensure these are allowed:
# - Outbound HTTPS (443)
# - WebSocket protocol (wss://)

Quick Fixes

IssueQuick Fix
Invalid API keyVerify key in dashboard
Wrong URLUse wss://app.conversimple.com/sdk/websocket
TimeoutIncrease timeout to 30s
FirewallAllow port 443 outbound
Platform downCheck status page

Still Having Issues?

If problems persist:
  1. Enable debug logging
  2. Check platform status page
  3. Contact support with logs