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

AI Agent 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 your usage limits — If your plan's monthly message or conversation limit has been reached, the AI agent pauses until the next cycle or until you upgrade. See Billing.
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://app.wazbot.app/api/v1/webhooks/whatsapp/YOUR_AGENT_ID

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

AI Response Issues

AI Agent 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.
• Try a more capable model — If your plan offers a choice of models, a higher-capability model generally provides better accuracy for complex queries.

AI Agent 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.

AI Agent 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 WazBot charge if it was declined.

Unexpected Charges

Check your usage breakdown in Settings → Billing → Usage. WazBot does not apply surprise overage billing — if you approach your plan limits you'll receive usage warnings and can upgrade to a higher plan. 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');
}

Problem-by-problem guide

Each entry below follows the same shape: the problem, its possible cause, what to check, what to do, and when to contact support.

Messages not appearing in your inbox

• Possible cause — WhatsApp is disconnected, or messages are being handled automatically and look “missing”.
• What to check — the WhatsApp connection status, and whether the chat is AI-active rather than unanswered.
• What to do — reconnect WhatsApp if needed (see WhatsApp Setup) and open the conversation inbox to confirm the chat exists.
• When to contact support — if WhatsApp shows connected but new customer messages never arrive.

AI agent not responding

• Possible cause — the agent is inactive, a human has taken over, usage limits are reached, or the 24-hour window has closed.
• What to check — agent status, whether the conversation is assigned to a person, your plan usage, and the time since the customer’s last message.
• What to do — activate the agent, release the conversation back to AI, or reply with an approved template if the window has closed.
• When to contact support — if the agent is active, within limits, and still silent.

Handoff to a human not working

• Possible cause — no teammate is available or assignment rules are not set up.
• What to check — your team and assignment setup and any automation that routes conversations.
• What to do — add team members, define who receives handoffs, and test with a sample conversation.
• When to contact support — if handoff rules are configured but conversations never reach a person.

Knowledge not being used in answers

• Possible cause — the document is still processing, contains only images, or the topic is not covered clearly.
• What to check — that the knowledge source finished processing and contains readable text about the question.
• What to do — re-upload readable content, use clear titles, and test with the exact customer question.
• When to contact support — if relevant, processed knowledge is still ignored.

Automation not running

• Possible cause — the workflow is inactive, the trigger never fired, or a condition excluded the case.
• What to check — that the workflow is active and the trigger and conditions match your scenario.
• What to do — enable the workflow, simplify conditions, and run a test that matches the trigger.
• When to contact support — if the trigger clearly matches but no actions run.

Campaign not sending

• Possible cause — the audience is empty, a template is not approved, or a plan limit is reached.
• What to check — the selected audience, template approval status, and your plan usage.
• What to do — confirm the audience has contacts, use an approved template, and upgrade if limits are reached.
• When to contact support — if everything is valid but delivery never starts.

Funnel not publishing

• Possible cause — required content is missing, or your plan’s funnel limit is reached.
• What to check — that the funnel has all required fields and that your plan allows another published funnel.
• What to do — complete missing content, unpublish an unused funnel, or upgrade your plan.
• When to contact support — if publishing fails with no explanation.

Form submission not creating a lead

• Possible cause — validation blocked the submission, or it matched an existing customer.
• What to check — required fields and format rules on the form, and whether a matching customer already exists.
• What to do — test a complete submission and check the CRM for a new or updated record.
• When to contact support — if valid submissions never appear as leads.

Login or account access problems

• Possible cause — wrong credentials, or you don’t have access to the business workspace.
• What to check — that you’re using the right email and that a teammate has invited you with a role.
• What to do — reset your password, or ask an admin of the business to add you (see Teams).
• When to contact support — if you cannot sign in after resetting your password.