AI Customer Service Agent — Complete documentation

Complete installation, configuration, and usage guide for the DataFirefly AI Customer Service Agent plugin — an AI customer support agent for WooCommerce that understands context, calls read-only tools on your store, and smartly escalates complex cases to Slack and email.

1. Prerequisites

• WordPress 6.4 or higher
• WooCommerce 8.0 or higher
• PHP 8.1, 8.2 or 8.3
• An API key from Anthropic (Claude) or OpenAI (recommended: Claude Sonnet 4.5)
• Optional: a Slack webhook for real-time escalation
• Optional: Polylang Pro or WPML if your store is multilingual

2. Installation

ZIP install

1. From your DataFirefly account, download the df-ai-customer-service.zip file
2. In WordPress, go to Plugins → Add New → Upload Plugin
3. Select the ZIP and click Install Now
4. Click Activate once installation is complete

What happens on activation?

The plugin automatically creates 5 database tables prefixed wp_dfaics_: conversations, messages, escalations, faq, analytics. It also declares HPOS and Gutenberg cart/checkout blocks compatibility, then schedules a daily cron task to clean up expired conversations.

3. AI provider configuration

The plugin supports two AI providers. You pick your preferred one in AI Support → Settings → AI. You bring your own API key — DataFirefly does not proxy anything and takes no cut of your usage.

Option A: Claude (recommended)

1. Create an account at console.anthropic.com
2. Generate an API key in Settings → API Keys
3. Copy the key (starts with sk-ant-...)
4. In WordPress, go to AI Support → Settings → AI
5. Select provider Anthropic (Claude)
6. Paste your key in the Anthropic API Key field
7. Default model: claude-sonnet-4-5 (excellent quality / cost balance)
8. Click Test key to validate
9. Save

Option B: OpenAI

1. Create an account at platform.openai.com
2. Generate an API key in API Keys
3. Copy the key (starts with sk-...)
4. In WordPress, select provider OpenAI
5. Default model: gpt-4o-mini (most economical with reliable tool calling)

Indicative cost

A typical 5 to 10-turn conversation with tool calling costs:

• About 0.01 to 0.05 USD with Claude Sonnet 4.5
• About 0.005 to 0.02 USD with GPT-4o mini

The dashboard shows total input/output tokens consumed over the period.

4. Widget configuration

The chat widget appears by default in the bottom-right corner on all frontend pages. Customise it in AI Support → Settings → Widget.

Appearance options

• Main colour — Floating button and header colour (default #0073aa)
• Text colour — Header text colour (default white)
• Position — Bottom right or bottom left
• Widget title — E.g. “Need help?”
• Greeting message — First message shown when opening
• Placeholder — Input field placeholder text
• Show DataFirefly badge — Small mention at the bottom of the widget

Conditional display

In the Widget tab, you can restrict where the widget is shown:

• All pages — Default behaviour
• Product pages only — For targeted support on product listings
• Except cart and checkout — Avoid distraction during purchase
• Hide on these content IDs — List of IDs to exclude

Shortcode

You can also embed the chat in a page or post with the shortcode:

[dfaics_chat]

This renders the widget in embedded mode (not floating), useful for a dedicated “Contact us” page.

5. The 6 agent tools

The agent has 6 tools it chooses whether to call based on the question. All are strictly read-only. You enable or disable each individually in Settings → Behaviour.

lookup_order

Retrieves the status of a WooCommerce order. Requires mandatory email verification before disclosure: the agent asks the customer for their email and matches it against the order email. Returns order number, status, amount, date, shipping method, tracking number if available.

search_products

Searches the catalogue by name, category, tag, availability, price range. Returns up to 5 results by default with title, SKU, price, URL, stock. Useful for answering “do you have this in blue?” or “what’s the price of X?”.

get_shipping_info

Returns shipping zones and methods configured in WooCommerce, with fees and delays. The agent can precisely answer “do you ship to Belgium?” or “how much is express?”.

get_returns_policy

Returns your returns policy content (which you configure in settings). The agent can explain the deadline, procedure and conditions.

search_faq

Searches your custom FAQs (managed in AI Support → FAQ). Results are scoped to the conversation language. Each entry found increments a usage counter to help you identify the most frequent questions.

escalate_to_human

The agent calls this tool when it determines a case requires a human (customer frustration, complex case, repeated tool failures). Triggers configured Slack and/or email notifications. See Escalation section below.

6. FAQ management

Create custom FAQ entries the agent can search during a conversation. Each entry is scoped by language.

Create an entry

1. Go to AI Support → FAQ
2. Click Add entry
3. Choose the language
4. Write the question and answer in natural language
5. Add comma-separated keywords (optional, improves search)
6. Choose a category (e.g. shipping, sizing, warranty)
7. Save

FAQ best practices

• Phrase questions as a customer would, not as an SEO copywriter
• Short and actionable answers (2 to 4 sentences suffice, the agent rephrases)
• Create one entry per major customer language
• Regularly check the usage counter to identify questions to enrich

7. Human escalation

Escalation is configured in Settings → Escalation. Two channels are supported in parallel: Slack and email.

Slack setup

1. In Slack, create a new app at api.slack.com/apps
2. Enable Incoming Webhooks
3. Create a webhook to the desired channel (e.g. #support-escalations)
4. Copy the webhook URL
5. In WordPress, paste it in Slack Webhook
6. Click Test webhook to send a test message

Each escalation sends Slack a rich block message with: excerpt of the last 3 messages, escalation reason, customer metadata (verified email, language, origin page), and an Open in admin button pointing directly to the conversation detail.

Email setup

In Escalation email, enter one or more comma-separated addresses. Each escalation sends an HTML email containing the full transcript, customer data and an admin link.

Escalation triggers

The agent escalates in 3 situations:

1. Sensitive keywords — Configurable list (default: refund, lawyer, broken, complaint, remboursement, avocat, cassé, réclamation)
2. Sentiment threshold — Detection of frustration or dissatisfaction (adjustable from -1 to 0)
3. Repeated tool failure — After 6 turns without resolution, forced escalation

8. Dashboard and analytics

The dashboard at AI Support → Dashboard shows 4 key indicators:

• Volume — Total number of conversations over the last 7, 30 or 90 days
• Auto-resolution rate — % of conversations ending without escalation
• Average satisfaction — Star rating given by customers after escalation
• Tokens consumed — Input + output cumulative for AI cost estimation

The Conversations page lists all sessions with filters (language, status, escalation yes/no). Click a row to see the full transcript with detailed tool calls in JSON.

9. Multilingual

The plugin natively supports 5 languages: French, English, Spanish, German, Italian. Conversation language is resolved automatically in this order:

1. Polylang language of the page where the widget is displayed (if Polylang installed)
2. WPML language of the page (if WPML installed)
3. Visitor browser locale
4. Fallback language configured in settings (default: English)

The agent’s system prompt explicitly tells the model the expected response language. This ensures a French visitor gets a French answer, even if your store is mostly English.

10. Security and privacy

API key encryption

Anthropic, OpenAI keys and the Slack webhook are encrypted in AES-256-CBC upon save, with a key derived from AUTH_KEY + AUTH_SALT. The input field never redisplays the value: by leaving it empty and saving, the previous value is preserved.

Order email verification

The lookup_order tool mandatorily requires verification: the agent asks the customer for their email and matches it against the order’s. Without a match, no data is disclosed. This behaviour cannot be disabled — it protects against order scraping via the agent.

Rate limiting

A server-side anti-spam rate limit of 5 messages per minute per session is enforced. The maximum number of messages per conversation is 25 by default (configurable). Beyond that, the agent offers human escalation.

Retention and GDPR

Conversations are kept 30 days by default, then automatically deleted by a daily cron. You can reduce this duration in Settings → Privacy. The visitor IP and user agent can be logged or not according to your policy.

The plugin also offers an Anonymise PII in logs option that masks emails and phone numbers in technical logs (WooCommerce logger).

11. HPOS and checkout blocks compatibility

The plugin officially declares compatibility with:

• HPOS (High-Performance Order Storage) — All order queries go through official WooCommerce CRUDs (wc_get_order, wc_get_orders), so they work on both legacy tables and HPOS tables
• Gutenberg cart and checkout blocks — No interference with the new payment blocks
• WordPress Multisite — Network activation supported, options scoped per site

12. Hooks and filters for developers

The plugin exposes several hooks to customise behaviour without modifying source code.

Available filters

// Modify the system prompt before sending to the model
apply_filters('dfaics_system_prompt', $prompt, $context);

// Add or remove tools dynamically
apply_filters('dfaics_tools_available', $tools, $conversation);

// Modify max messages threshold before forced escalation
apply_filters('dfaics_max_messages', 25, $conversation);

// Customise the escalation email body
apply_filters('dfaics_escalation_email_body', $html, $conversation);

// Enrich Slack metadata
apply_filters('dfaics_slack_metadata', $metadata, $conversation);

Available actions

// After conversation creation
do_action('dfaics_conversation_created', $conversation_id, $session);

// After agent sends a message
do_action('dfaics_message_sent', $message_id, $conversation_id);

// After an escalation
do_action('dfaics_escalated', $conversation_id, $reason, $channel);

// After cron cleanup of expired conversations
do_action('dfaics_cleanup_done', $deleted_count);

Add a custom tool

Create a class extending ToolBase and register it via the dfaics_tools_available filter. The namespace is DataFirefly/AiCustomerService/Agent/Tools (using forward slashes here for readability; use the standard PHP backslash separator in your code). Each tool declares its JSON schema, description, and implements an execute() method returning a serialisable associative array.

13. Troubleshooting

The widget doesn’t show

• Check the widget is enabled in Settings → Widget → Enable widget
• Check the conditional display rule (allowed pages)
• Open browser console (F12) and look for JS errors
• Clear cache if you use a cache plugin (WP Rocket, W3 Total Cache…)

The agent doesn’t respond

• Check the API key is valid via the Test key button
• Check your credit / quota on Anthropic or OpenAI account
• Check WooCommerce logs at WooCommerce → Status → Logs, source df-ai-customer-service

Slack escalation doesn’t arrive

• Check the webhook via the Test webhook button
• Regenerate the webhook on Slack side if needed
• Check the target channel exists and the bot has access

Fully reset the plugin

In Settings → Privacy, tick Delete all data on uninstall. Then deactivate and uninstall the plugin: the 5 tables and options are removed.

14. Technical FAQ

Can I switch AI provider without losing conversations?

Yes, the Claude ↔ OpenAI switch is instant and doesn’t affect history. New conversations will use the new provider.

Does the plugin work in headless mode?

The plugin’s REST API (/wp-json/dfaics/v1/) can be used from any frontend (Next.js, Vue, mobile). The native widget is vanilla JS and can be replaced by your own implementation calling the same API.

Can we plug the plugin into Zendesk or Freshdesk?

Not natively in 1.0.0: escalation is limited to Slack and email. You can however use the dfaics_escalated hook to trigger your own integration.

Does the agent learn from my conversations?

No. No fine-tuning is performed. The agent only uses the system prompt + tools + current conversation context. Your data is not used to improve Anthropic or OpenAI models (both providers offer an opt-out option which is active by default on their professional APIs).

15. Support

For any question or bug report, write to support at datafirefly.com with your licence number. We reply within 48 business hours.