Troubleshooting

The Smart AI Contact Form is designed to be as "plug-and-play" as possible. However, because it interacts with third-party APIs and your specific server environment, you might occasionally run into a hiccup.

Here are the most common issues and exactly how to resolve them.

1. The Widget Isn't Loading on My Site

If you pasted the embed code but don't see the form or the floating bubble, check the following:

• Incorrect File Path: This is the #1 issue. Ensure the src attribute in your <script> tag points exactly to where you uploaded the folder. If you uploaded the files to public_html/support, your script tag should look like <script src="https://yourwebsite.com/support/widget.js"></script>.
• Browser Caching: Browsers aggressively cache JavaScript files. If you recently uploaded a new version or changed a color, do a Hard Refresh (Ctrl + F5 on Windows, Cmd + Shift + R on Mac).
• Check the Console: Right-click on your website, click Inspect, and go to the Console tab. Look for red text (404 errors mean the file wasn't found; CORS errors mean your server is blocking the script).

2. "Error: Unable to communicate with AI"

If the widget loads, but you get a red error message when trying to send a message, the script is failing to talk to the AI provider (OpenAI, Gemini, or Groq).

• Missing API Key: Double-check your .env file. Ensure you placed the API key exactly inside the quotes, like OPENAI_API_KEY="sk-..." without any extra spaces.
• Out of Credits: If you are using OpenAI, you must have a billing account set up with pre-paid credits (at least $5). Free trial credits expire quickly. Log into your OpenAI platform dashboard to check your balance.
• cURL is Disabled: The script uses PHP cURL to securely contact the AI. Contact your hosting provider and ask: "Is the PHP cURL extension enabled on my server?" (It is enabled by default on 99% of hosts).

3. Emails Are Not Sending

If the AI works, but fallback requests aren't reaching your inbox, there is an issue with your SMTP configuration in the .env file.

• Incorrect Credentials: Verify your SMTP_USER and SMTP_PASS. Remember, if you are using Gmail, your normal login password will not work. You must generate an "App Password" (see the SMTP Setup guide).
• Blocked Ports: Some strict hosting providers block outgoing connections on port 465 or 587 to prevent spam. Contact your host and ask them to open these outgoing SMTP ports.
• Check the Error Log: To see exactly why the email failed, you can temporarily open ai-handler.php, search for $mail->SMTPDebug = 0; and change it to $mail->SMTPDebug = 2;. This will print the exact server error to your browser console when you try to send a message. (Remember to change it back to 0 when done!)

4. The AI is Unresponsive or Replying Weirdly

If the widget works, but the AI's responses are completely broken or it suddenly stops replying after you edited the Knowledge Base:

• Broken JSON: You likely made a typo in the content.json file. JSON is extremely strict. A single missing quotation mark will break the whole file. Copy your content.json text and paste it into JSONLint.com to find the error instantly.
• Unescaped Quotes: Remember, you cannot use double quotes " inside your prompt unless you escape them \". Use single quotes ' instead.

5. Leads Are Not Saving to CSV

If users are sending messages, but your leads.csv file remains empty (or doesn't get created):

• File Permissions: Your server is preventing the script from writing files. Access your server via FTP or File Manager. Right-click the folder where you installed the script, select File Permissions, and ensure it is set to 755. If the leads.csv file already exists, ensure its permissions are set to 644.