Troubleshooting

Having issues? This page covers the most common problems and their solutions. If you can't find what you’re looking for, visit the Support page.

Connection Issues

Bot Not Responding to Messages

1. Check agent status — Make sure the agent is set to “Active” in the dashboard.
2. Verify WhatsApp connection — Go to Settings → WhatsApp and confirm the status shows “Connected”.
3. Check message quota — Free plan bots go offline when the monthly quota is reached.
4. Review conversation window — WhatsApp has a 24-hour customer service window. If more than 24 hours have passed since the customer's last message, you need a pre-approved template to reply.

WhatsApp Disconnected

If the connection status shows “Disconnected”:

• The access token may have expired. Re-authorize via Settings → WhatsApp → Reconnect.
• Meta may have revoked access due to policy violations. Check your Meta Business Manager for notices.
• The phone number may have been deregistered. Verify in the WhatsApp Business Manager.

Webhook Errors

If you’re using manual API setup and webhooks aren’t firing:

curl -I https://api.wazbot.io/v1/webhooks/whatsapp/YOUR_BOT_ID

Expected response: 200 OK. If you get 404 or 500, contact support.

AI Response Issues

Bot Gives Incorrect Answers

• Review the system prompt — Ensure it clearly defines the agent's role and limitations.
• Check the knowledge base — Outdated or conflicting documents can confuse the AI.
• Lower the temperature — A lower temperature (0.3–0.5) produces more factual, less creative responses.
• Switch models — GPT-4o generally provides better accuracy than GPT-4o-mini for complex queries.

Bot Responds in the Wrong Language

Add explicit language instructions to the system prompt:

IMPORTANT: Always respond in the same language the customer uses.
If the customer writes in Spanish, reply in Spanish.
If the customer writes in English, reply in English.

Bot Is Too Slow

Billing Issues

Payment Failed

• Verify your card details in Settings → Billing → Payment Methods.
• Ensure sufficient funds are available.
• Try a different payment method.
• Contact your bank to authorize the charge from “WAZBOT.IO”.

Unexpected Charges

Check your usage breakdown in Settings → Billing → Usage. Overage charges on the Pro plan are billed at $0.003 per message. See Billing for details.

API Issues

401 Unauthorized

• Verify the API key is correct and hasn't been revoked.
• Check that the key has the required permissions for the endpoint.
• Ensure the Authorization header is formatted correctly: Bearer YOUR_API_KEY.

429 Too Many Requests

You’ve hit the rate limit. Implement exponential backoff:

async function fetchWithRetry(url, options, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;
    const wait = Math.pow(2, i) * 1000; // 1s, 2s, 4s
    await new Promise(r => setTimeout(r, wait));
  }
  throw new Error('Rate limit exceeded after retries');
}