Atira WP Chat - Plugin Documentation

Contact Information

• WhatsApp Number:

  Enter the full WhatsApp phone number, including the country code (e.g., 15551234567 for a US number). Do not include +, spaces, or other special characters. This number will be used for the "Chat on WhatsApp" button.

• Phone Number (for "Call Us"):

  Enter the phone number that users can call. Include the country code if necessary (e.g., +15551234567). This will be used for the "Call us" link in the "Other contact options" section.

• Email Address (for "Email Us"):

  Enter the email address users can send emails to. This will be used for the "Email:" link in the "Other contact options" section.

• Form Submission Email:

  Enter the email address where messages submitted through the "Leave a message" form will be sent. Defaults to your WordPress site's admin email if left blank.

  Important: If you are not receiving emails from the form, check your spam/junk folder. Consider installing an SMTP plugin (like WP Mail SMTP) to improve email deliverability from your WordPress site.

Appearance & Styling

• Widget Main Color:

  Use the color picker to select the primary background color for the main chat toggle button and the submit buttons within the widget. The default color is a shade of blue (#3b82f6).

• Widget Position:

  Choose where the chat widget will be fixed on the screen:

  • Bottom Right (Default)
  • Bottom Left

AI Chat Settings

This section allows you to enable and configure the AI-powered chat assistant.

• AI Provider:

  Select your preferred AI chat provider. The "Chat with AI" option will only appear in the widget if a provider is selected and configured.

  • None (Disable AI Chat)
  • OpenAI (ChatGPT)
  • Google AI (Gemini)
• OpenAI API Key:

  Required if "OpenAI (ChatGPT)" is selected. Enter your secret API key from your OpenAI account (Get API Key).

• OpenAI Model:

  Enter the specific OpenAI model to use (e.g., gpt-3.5-turbo, gpt-4). Defaults to gpt-3.5-turbo if left blank.

• Google AI (Gemini) API Key:

  Required if "Google AI (Gemini)" is selected. Enter your API key from Google AI Studio (Get API Key).

• Gemini Model:

  Enter the specific Gemini model to use (e.g., gemini-1.5-pro-latest). Defaults to gemini-1.5-pro-latest if left blank.

• AI System Prompt/Persona:

  Optional. Define the initial instruction or persona for the AI (e.g., "You are a friendly customer support agent for Atira Grup."). This prompt helps guide the AI's responses. If using website content as a knowledge base, this prompt will be combined with instructions to use that context.

• AI Knowledge Base (Posts/Pages):

  Select the posts and pages from your website whose content should be used as a knowledge base for the AI. The AI will attempt to answer user questions based primarily on this selected content. This option is only active if an AI provider (OpenAI or Gemini) is selected.

• AI Context Max Length (Characters):

  Set the maximum number of characters from the selected "Knowledge Base" content that will be provided to the AI as context for each query. This helps manage API token limits. A good starting point is 3000-5000 characters (roughly 750-1250 tokens). Adjust based on your needs and the AI provider's limits. This option is only active if an AI provider is selected.

Frontend Interface

Once activated and configured, the Atira WP Chat widget will appear in the selected position (bottom-right or bottom-left) on all frontend pages of your website.

• Toggle Button: A circular button (color-configurable) with a chat icon. Clicking this button opens the chat menu. Clicking it again (now showing a close icon) closes the menu.
• Chat Menu:
  • Header: Displays "How can we help?" or a "Back" button if you've navigated into a sub-section.
  • Main Options:
    • Leave a message: Opens an inline contact form.
    • Chat on WhatsApp: Opens a new tab/window to start a WhatsApp chat with the configured number.
    • Chat with AI: (Only appears if an AI provider is configured) Opens the AI chat interface.
    • Other contact options: Opens a sub-section with direct "Call us" and "Email" links.
• Sub-sections (Form, Other Contacts, AI Chat):

  When a sub-section is active, the header changes to show a "Back" button, allowing users to return to the main options.

AI Chat Interaction

If AI Chat is enabled:

1. Click the "Chat with AI" option in the widget.
2. The interface will change to show a message display area and an input field.
3. Type your message into the input field and click "Send" or press Enter.
4. Your message will appear in the chat area, followed by "AI is thinking...".
5. The AI's response will then be displayed. The AI will attempt to use the content from the "AI Knowledge Base" (selected posts/pages) to answer your questions. If the information isn't found there, it may indicate so or provide a general answer based on its training.
6. The conversation history is maintained for the current session to provide context for follow-up questions. Starting a new AI chat session (by clicking the "Chat with AI" option again) will clear the previous history for that new session.

Widget Not Appearing

• Ensure the plugin is activated.
• Clear any caching plugins you might be using on your WordPress site.
• Clear your browser cache.
• Check your browser's developer console (usually F12) for any JavaScript errors that might be preventing the widget from loading.

Contact Form Emails Not Being Received

• Check Spam/Junk Folder: This is the most common reason.
• Verify Recipient Email: Double-check the "Form Submission Email" address in the plugin settings (Settings > Atira Chat Widget).
• Install an SMTP Plugin: WordPress's default wp_mail() function can sometimes be unreliable depending on server configuration. Installing an SMTP plugin (e.g., WP Mail SMTP, FluentSMTP, Easy WP SMTP) and configuring it to send emails via a dedicated email service (like Gmail, SendGrid, Mailgun, etc.) drastically improves email deliverability.

AI Chat Errors

• "API Key is not configured": Ensure you have entered the correct API key for the selected AI provider in the plugin settings and saved the changes.
• "Error contacting [OpenAI/Gemini] - [specific API error]": This indicates an issue with the API key itself (e.g., invalid, expired, billing issues with your AI provider account) or a problem with the AI service.
  • Verify your API key is correct and active with the provider.
  • Check the AI provider's status page for any ongoing outages.
  • Ensure your server can make outbound HTTPS requests (sometimes blocked by firewalls).
• "Could not get a valid response from [OpenAI/Gemini]": The API might have returned an unexpected response format. Check the browser console for more details if possible. The plugin currently uses models like gpt-3.5-turbo for OpenAI and gemini-1.5-pro-latest for Gemini (configurable in settings). Ensure these models are available for your API key.
• AI not using website content effectively:
  • Ensure you have selected relevant posts/pages in the "AI Knowledge Base" setting.
  • Check the "AI Context Max Length." If it's too short, not enough information might be sent to the AI. If it's too long, it might exceed API limits or dilute the focus. Experiment with this value.
  • Refine your "AI System Prompt" to clearly instruct the AI to prioritize the provided website content.

Styling Conflicts

• The plugin uses its own CSS (widget-styles.css) for styling and attempts to be self-contained.
• If you notice major styling issues, it might be due to very aggressive CSS from your theme or another plugin. You can try to identify the conflicting styles using your browser's developer tools and override them in your theme's custom CSS or by modifying widget-styles.css (though direct plugin file modifications are not recommended as they can be overwritten by updates).