# AI Forms
Source: https://docs.aipower.org/ai-forms
Create and embed AI-powered forms in WordPress.
## Overview
AI Forms collect visitor input, uploaded files, and uploaded images, insert the submitted values into a prompt, stream the AI response on the page, and can pass results into another AI Form.
Use them for generators, support reply tools, calculators, lead forms, summaries, guided intakes, and multi-form workflows where the visitor provides structured input.
In WordPress admin, go to **AI Puffer > AI Forms**. Use the **Forms** tab to create, search, edit, preview, and publish forms. Use the **Settings** tab for module-wide limits, custom CSS, and frontend model access.
Open example forms built with AI Puffer.
Build fields, layouts, labels, prompt, and AI settings.
Use vector data as context for form responses.
Let supported providers search the web during a response.
Send form submissions and outputs to external apps.
Chain AI Forms together and pass answers between forms.
Edit, duplicate, delete, and organize saved forms.
Embed forms with shortcodes or the WordPress block editor.
Configure the Limits, Custom CSS, and Frontend Models tabs.
Review form requests and generated responses.
## Create a Form
1. Open **AI Puffer > AI Forms > Forms**.
2. Click **Create New Form**.
3. Enter the form title.
4. In the left **Layouts** accordion, drag a layout into the center designer.
5. In the left **Form Elements** accordion, drag fields into the layout columns.
6. Click a field in the designer to edit it in **Element Settings**.
7. In the right **AI** container, select the model.
8. Write the form prompt in the **AI** container.
9. Click **Validate Prompt** to check field placeholders.
10. Click **Save**.
11. Click **Preview** to test the form from the admin screen.
![AI Forms]()
You can also click **Generate with AI** and describe the form you want. AI Puffer drafts the title, fields, layout, and prompt. Review the draft before saving.
![AI Form generator modal]()
Set up at least one AI provider before creating a form. If the model list is empty, configure and sync a provider in [AI Providers](/ai-providers).
### Form Elements
Form elements collect the values used by the prompt.
![AI Form elements panel]()
| Field | Use it for |
| ----------------- | ----------------------------------------------------------------------------------- |
| **Text Input** | Short text values. |
| **Text Area** | Longer text values. |
| **Dropdown** | One selected option from a list. |
| **Checkbox** | One or more selected options. |
| **Radio Buttons** | One selected option from a visible list. |
| **File Upload** | TXT or PDF upload. The extracted text is passed into the prompt. |
| **Image Upload** | JPG, PNG, or WEBP upload. The image is sent to a vision-capable model for analysis. |
When you click a field, **Element Settings** replaces the left palette. Edit **Label Text**, **Field Variable Name**, placeholder text, required state, help text, and options.
![AI Form field settings]()
The field variable name is the value you use in the prompt. It can contain letters, numbers, and underscores. It must be unique inside the form.
For **File Upload**, the visitor uploads a TXT or PDF file. AI Puffer extracts the file text during upload and stores that text as the field value.
Add the file field placeholder to the prompt where you want the extracted text to be used.
AI Puffer does not summarize the file before the form runs. If you want a summary, ask for it in the prompt.
File Upload sends extracted text in the prompt. It works with the AI Forms text providers: OpenAI, Google, Anthropic, OpenRouter, Azure, xAI, Ollama, and DeepSeek. It does not use Knowledge Base or vector provider settings.
File Upload is available on Pro plan. It accepts `.txt` and `.pdf` files. Text-based PDFs work best; scanned PDFs may not provide usable text. Large files still count against the selected model's context limit.
For **Image Upload**, the visitor uploads an image and AI Puffer sends it with the form request as image input. Use the prompt to tell the model what to do with the image, such as describe it, extract details, compare it with submitted answers, or generate recommendations from it.
Image Upload works only with providers and models that support image input in AI Forms: OpenAI, Google, Anthropic, OpenRouter, xAI, and Ollama. If the selected model cannot analyze images, the form returns an error instead of silently ignoring the upload.
Image Upload is available on Pro plan. It accepts JPG, PNG, and WEBP images up to 20 MB. Some providers may apply stricter model or file-type rules, such as xAI image analysis using JPG or PNG.
### Layouts
Layouts control the frontend rows and columns.
![AI Form layouts panel]()
| Layout | Columns |
| --------------------- | ----------------------- |
| **Single Column** | 1 column |
| **2 Columns (50/50)** | 2 equal columns |
| **2 Columns (30/70)** | Narrow left, wide right |
| **2 Columns (70/30)** | Wide left, narrow right |
| **3 Columns** | 3 equal columns |
### Multi-Step
Multi-Step shows one layout row at a time. Use it when the form should feel like a guided flow.
In the left **Multi-Step** accordion:
1. Turn on **Enable Multi-Step**.
2. Choose **Display Progress**.
3. Hover a row in the designer.
4. Click the chat bubble icon to configure that row as a step.
5. Add a step title and description if needed.
6. Add a condition if the step should appear only for specific answers.
7. Save the form.
![AI Form Multi-Step settings]()
![AI Form Multi-Step settings]()
| Progress option | What it shows |
| --------------- | -------------------------------------- |
| **Full** | Step title, description, and progress. |
| **Compact** | Step title and progress. |
| **Minimal** | Step title only. |
| **None** | No step header or progress UI. |
Skipped step inputs are cleared before submission.
Multi-Step can be combined with Workflow. The visitor completes the visible steps in the source form first; after the AI response finishes, the next workflow form appears.
### Workflow
Workflow connects one AI Form to another. Use it when a visitor should complete a source form, review the AI response, and continue with a second form that already contains context from the first result.
Workflow is useful for intake funnels, content pipelines, lead routing, support triage, and any process where one AI output becomes the starting point for another AI task.
![AI Form workflow settings]()
In the left **Workflow** accordion:
1. Create and save the target AI Form first.
2. Edit the source AI Form.
3. Turn on **Enable Workflow**.
4. Choose the default **Next AI Form**.
5. Use **Send AI output to** to prefill a target text field with the source form's AI response.
6. Click **Add Mapping** under **Map submitted answers** to pass source answers into target text fields.
7. Click **Add Route** under **Conditional routes** if different answers should open different target forms.
8. Optional: turn on **Auto-submit next form** if the next form should run as soon as mapped values are filled.
9. Save the source form.
10. Test the source form with **Preview** or its shortcode.
Workflow runs after the source form finishes streaming its AI response. The target form appears below the source result. By default, the visitor can review the prefilled values and submit the target form when ready. If **Auto-submit next form** is enabled and the target form has all required values, AI Puffer submits the target form automatically.
| Control | Use it for |
| ------------------------- | ---------------------------------------------------------------------- |
| **Enable Workflow** | Turns workflow behavior on for the source form. |
| **Next AI Form** | Sets the default target form. |
| **Send AI output to** | Copies the source AI response into one target field. |
| **Map submitted answers** | Copies source field answers into target fields. |
| **Conditional routes** | Opens a different target form when a rule matches. |
| **Auto-submit next form** | Runs the target form automatically after workflow mappings are filled. |
Workflow mappings can target **Text Input** and **Text Area** fields in the next form. File Upload and Image Upload fields are not prefilled into the target form.
Conditional routes can check the AI response or a submitted field value. Route operators are **equals**, **contains**, and **not empty**. Routes are checked from top to bottom; the first matching route wins. If no route matches, AI Puffer uses the default **Next AI Form**.
Workflow does not auto-submit the next form unless **Auto-submit next form** is turned on. Use auto-submit only when the target form can run from mapped text values. If required values are missing, or the target form needs a required upload or multi-step interaction, the target form waits for the visitor.
#### Examples
Use this workflow when the first form suggests domain names and the second form turns the selected direction into a launch blog post draft.
Create the target form first:
1. Create **Blog Post Draft**.
2. Add a **Text Area** field named `domain_suggestions`.
3. Add a **Text Area** field named `business_context`.
4. Add a **Text Input** field named `tone`.
5. Write a prompt that chooses a strong domain from `{domain_suggestions}` and writes a blog post using `{business_context}` and `{tone}`.
6. Save the form.
Then create the source form:
1. Create **Domain Name Generator**.
2. Add a **Text Area** field named `idea_description`.
3. Add a **Dropdown** field named `tone`.
4. Write a prompt that suggests domain names from `{idea_description}` and `{tone}`.
5. Open **Workflow**.
6. Turn on **Enable Workflow**.
7. Set **Next AI Form** to **Blog Post Draft**.
8. Set **Send AI output to** to `domain_suggestions`.
9. Add a mapping from `idea_description` to `business_context`.
10. Add a mapping from `tone` to `tone`.
11. Optional: turn on **Auto-submit next form** if you want the blog post draft to start immediately after domain ideas are generated.
12. Save and test the source form.
When the visitor submits the source form, the generated domain ideas appear in the target form. The original business description and tone are also prefilled.
![AI Form workflow settings]()
Use this workflow when one intake form should route visitors to different next forms based on their request type.
Create the target forms first:
1. Create **Sales Follow-up** with fields named `company_name`, `intake_summary`, and `lead_notes`.
2. Write a prompt that drafts a sales follow-up from those fields.
3. Create **Support Reply** with fields named `company_name`, `intake_summary`, and `customer_message`.
4. Write a prompt that drafts a support reply from those fields.
5. Save both target forms.
Then create the source form:
1. Create **Lead Intake Router**.
2. Add a **Text Input** field named `company_name`.
3. Add a **Dropdown** field named `request_type` with values such as `sales`, `support`, and `partnership`.
4. Add a **Text Area** field named `request_details`.
5. Write a prompt that summarizes the lead from `{company_name}`, `{request_type}`, and `{request_details}`.
6. Open **Workflow**.
7. Turn on **Enable Workflow**.
8. Set **Next AI Form** to **Sales Follow-up** as the default route.
9. Add a route where `request_type` **equals** `support`, then set the target to **Support Reply**.
10. In that route, map AI output to `intake_summary`, `company_name` to `company_name`, and `request_details` to `customer_message`.
11. Add a route where `request_type` **equals** `sales`, then set the target to **Sales Follow-up**.
12. In that route, map AI output to `intake_summary`, `company_name` to `company_name`, and `request_details` to `lead_notes`.
13. Optional: turn on **Auto-submit next form** if each routed target form has everything it needs from the mappings.
14. Save and test the source form with both request types.
Sales requests open the sales follow-up form. Support requests open the support reply form. Other request types fall back to the default next form.
![Lead intake workflow routes]()
![Lead intake workflow routes]()
![Lead intake workflow routes]()
![Lead intake workflow target form]()
### Labels
Use the left **Labels** accordion to change frontend button text and field selector labels.
![AI Form labels panel]()
| Label | Default |
| ------------------ | -------------------------------------------- |
| **Generate** | Generate |
| **Stop** | Stop |
| **Download** | Download |
| **Save** | Save |
| **Copy** | Copy |
| **Engine** | Engine |
| **Model** | Model |
| **Back** | Back |
| **Next** | Next |
| **Step Title** | Step `{number}` |
| **Step Progress** | Step `{current} of {total}` |
| **Validation Msg** | Please complete this step before continuing. |
Multi-step labels are used only when Multi-Step is enabled.
### AI
Each form has its own model selection in the right-side **AI** container.
![AI Form engine and model settings]()
Click the settings icon beside the model list to open **Model settings**.
![AI Form parameters popover]()
| Setting | Use it for |
| --------------------- | ----------------------------------------------------------------------------------- |
| **Temperature** | Response variation. Lower values are more predictable. |
| **Max Tokens** | Maximum response size. |
| **Top P** | Sampling control. Leave at the default unless you know why you are changing it. |
| **Frequency Penalty** | Reduces repeated wording. |
| **Presence Penalty** | Encourages the model to introduce new wording or topics. |
| **Reasoning Effort** | Reasoning level for supported models. Keep it set to **None** for faster responses. |
### Prompt
AI Forms use field placeholders inside the prompt. Add a field value by wrapping its variable name in braces.
![AI Form prompt editor]()
Example:
```text theme={null}
Write a customer support reply.
Customer message:
{customer_message}
Tone:
{tone}
Next step:
{next_step}
```
For dropdown and radio fields, AI Puffer inserts the selected option label. For checkbox fields, it inserts selected option labels separated by commas. If a field is empty, the placeholder is replaced with an empty value.
Use the expand icon inside **Prompt** when you want a larger prompt editor.
AI Forms do not keep chat history. Each submission uses the current form values and the saved form configuration.
### Knowledge Base
Knowledge base lets a form use trained content from **AI Puffer > Knowledge Base > Data** before generating the response.
Use the right-side **Context** container to enable Knowledge Base and configure its retrieval options.
1. Turn on **Knowledge Base**.
2. Click the settings icon beside **Knowledge Base**.
3. Select **Vector provider**.
4. Choose the vector store, index, or collection.
5. For Pinecone, Qdrant, or Chroma, select the same **Embedding** model used when the content was indexed.
6. Set **Limit** and **Score threshold**.
7. Save the form.
![AI Form context settings]()
| Vector provider | Required setup |
| --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **OpenAI** | Select up to two **Vector stores**. |
| **Pinecone** | Select **Index** and **Embedding**. Configure the Pinecone connection in **AI Puffer > Settings > Integrations** first. |
| **Qdrant** | Select **Collection** and **Embedding**. Configure the Qdrant connection in **AI Puffer > Settings > Integrations** first. |
| **Chroma** | Select **Collection** and **Embedding**. Configure the Chroma connection in **AI Puffer > Settings > Integrations** first. |
For Chroma, configure the connection and collection in **AI Puffer > Settings > Integrations** and **AI Puffer > Knowledge Base > Stores** first.
![Chroma API key]()
![Chroma Create collection]()
For Pinecone, Qdrant, and Chroma, the embedding model must match the model used when the content was added to the index or collection.
**Limit** controls how many matching chunks AI Puffer can include. **Score threshold** controls how strict the match must be. A lower threshold allows more matches; a higher threshold only uses stronger matches.
### Web Search
Web search lets supported providers use current web results while generating the form response.
Use the right-side **Context** container to enable Web Search. The available options depend on the selected model provider.
1. Select an OpenAI, Google, Anthropic, OpenRouter, or xAI model.
2. Turn on **Web Search**.
3. Click the settings icon beside **Web Search**.
4. Configure the provider options.
5. Save the form.
![AI Form web search settings]()
| Option | Use it for |
| ----------------------- | --------------------------------------------------------- |
| **Search Context Size** | How much web context OpenAI can use. |
| **User Location** | Optional approximate country, city, region, and timezone. |
| Option | Use it for |
| ------------------------------- | -------------------------------------------------- |
| **Grounding Mode** | How Google Search grounding is used. |
| **Dynamic Retrieval Threshold** | Threshold used when Dynamic Retrieval is selected. |
| Option | Use it for |
| ------------------- | --------------------------------------------------------- |
| **Max Uses** | Maximum number of web search calls for one response. |
| **User Location** | Optional approximate country, city, region, and timezone. |
| **Allowed Domains** | Limit search to specific domains. |
| **Blocked Domains** | Prevent search from using specific domains. |
| **Cache TTL** | Optional cache window for Anthropic web search. |
| Option | Use it for |
| ----------------- | ---------------------------------- |
| **Engine** | Auto, Native, or Exa. |
| **Max Results** | Maximum search results to include. |
| **Search Prompt** | Optional search intent hint. |
xAI web search uses the shared form setting and does not expose additional xAI-specific web options.
Web search is not shown for Azure, DeepSeek, or Ollama forms.
### Connected Apps
Connected Apps send completed form submissions to external apps through recipes. The `form.submitted` event is emitted after the AI response is complete, so mappings can use both submitted inputs and the generated response. Image Upload fields include image metadata in the event payload, not the base64 image data.
Supported destinations are Slack, HubSpot, Notion, Pipedrive, Zapier, Make, and n8n.
Connected Apps can be used with Workflow. Each submitted form in the chain emits its own `form.submitted` event, so a source form and a target form can trigger separate recipes. When **Auto-submit next form** is enabled, the target form can emit its own event without another visitor click.
1. Go to **AI Puffer > Settings > Apps**.
2. Connect the app account or webhook destination.
3. Create or enable a recipe that uses the **AI Form Submitted** event.
4. Choose the scope: **All AI Forms**, **This AI Form**, or **Selected AI Forms**.
5. Return to **AI Puffer > AI Forms**.
6. Edit the form and check the right-side **Connected Apps** container.
7. Submit the form on the frontend to test the recipe.
Common mapping sources:
| Source | Value |
| ------------------------ | --------------------------------- |
| `data.form.id` | Form ID. |
| `data.form.name` | Form title. |
| `data.submission.id` | Submission ID. |
| `data.submission.count` | Submission count for the form. |
| `data.actor.type` | `guest` or `user`. |
| `data.ai.provider` | Provider used for the submission. |
| `data.ai.model` | Model used for the submission. |
| `data.response.text` | Generated AI response. |
| `data.inputs` | Submitted field values. |
| `data.inputs.{field_id}` | A specific submitted field value. |
## Manage Forms
The **Forms** tab lists saved forms with their title, model, shortcode, updated date, and actions.
Each row has direct **Edit** and **Preview** actions. Select one or more forms with the row checkboxes to use bulk actions such as duplicate, export, or delete.
| Action | What it does |
| -------------- | ----------------------------------------- |
| **Edit** | Opens the form builder. |
| **Preview** | Opens an admin preview. |
| **Duplicate** | Creates copies of selected forms. |
| **Export** | Downloads selected forms as JSON. |
| **Delete** | Deletes selected forms. |
| **Export All** | Downloads all forms as JSON. |
| **Import** | Imports forms from an exported JSON file. |
| **Delete All** | Deletes all AI Forms. |
Imported forms are added as new forms. Existing forms are not overwritten.
## Publish
### Shortcode
Each saved form has a shortcode in the form list.
```text theme={null}
[aipkit_ai_form id=123]
```
Replace `123` with the form ID.
Click the shortcode snippet to copy it. Click **Options** beside the snippet to enable display options; the snippet updates as you change those options.
![AI Form shortcode settings]()
| Option | Shortcode attribute |
| ------------------------ | ---------------------------------------------------- |
| **Show Provider Select** | `show_provider="true"` |
| **Show Model Select** | `show_model="true"` |
| **Copy Button** | `copy_button="true"` |
| **Save as Post** | `save_button="true"` |
| **Save as PDF** | `pdf_download="true"` |
| **Theme** | `theme="light"`, `theme="dark"`, or `theme="custom"` |
Examples:
```text theme={null}
[aipkit_ai_form id=123 theme="dark"]
[aipkit_ai_form id=123 show_provider="true" show_model="true"]
[aipkit_ai_form id=123 save_button="true" copy_button="true"]
[aipkit_ai_form id=123 pdf_download="true"]
```
### Block
Use the AI Form block if you prefer the block editor.
1. Edit the page or post.
2. Add the **AI Form** block.
3. Select the form.
4. Choose the theme and display options.
5. Save the page.
![AI Form block in the WordPress block editor]()
The block renders the same form as the shortcode.
Workflow settings are saved with the source form. They work when the source form is rendered by shortcode, the AI Form block, or admin preview.
### Result Actions
Result actions appear after the form generates an output.
| Action | What it does |
| ---------------- | ------------------------------------------------------------------------------------------------------------- |
| **Copy** | Copies the generated response. |
| **Save as Post** | Saves the generated response as a draft WordPress post. The user must be logged in and allowed to edit posts. |
| **Save as PDF** | Downloads the generated response as a PDF when `pdf_download="true"` is enabled. |
Save as Post uses the form title as the post title and saves the output as draft content.
## Settings
Open **AI Puffer > AI Forms > Settings**.
The Settings screen is split into tabs.
| Tab | What it contains |
| ------------------- | ----------------------------------------------------- |
| **Limits** | Guest, user, role, reset, and quota message settings. |
| **Custom CSS** | CSS for forms using the custom theme. |
| **Frontend Models** | Models visitors can select on the frontend. |
### Limits
Limits control how much AI Forms usage is allowed for guests and logged-in users.
Open **Limits**.
1. Set **Guest quota**.
2. Choose **Quota mode** for logged-in users.
3. Set **User quota** or **Role-based quotas**.
4. Choose **Reset period**.
5. Edit **Quota reached message**.
6. Configure optional primary and secondary buttons.
| Value | Meaning |
| --------------- | ------------------------------------------- |
| Empty | Unlimited. |
| `0` | Disabled. |
| Positive number | Maximum allowed usage for the reset period. |
Reset periods are **Never**, **Daily**, **Weekly**, and **Monthly**.
Action buttons can link users to the usage dashboard, credits dashboard, purchases dashboard, buy credits page, or a custom URL.
For credit-based form access, define pricing rules in [Usage](/usage#pricing-rules). To sell prepaid credits, create WooCommerce credit packages in [Usage](/usage#woocommerce-credit-packages).
### Custom CSS
Custom CSS applies to forms embedded with `theme="custom"`.
Open **Custom CSS**.
```css theme={null}
.aipkit-ai-form-wrapper.aipkit-theme-custom {
/* custom form styles */
}
```
### Frontend Models
Frontend Models controls which models visitors can select when the shortcode or block shows the frontend provider or model selector.
Open **Frontend Models** and select the models visitors can use. If no models are selected, all configured frontend models are allowed.
## Logs
Each form submission creates logs for the submitted request and the AI response.
Logs include the form ID, submitted inputs, uploaded image metadata, constructed prompt, provider, model, token usage, vector search scores when knowledge base is used, and the generated response.
AI Forms usage is recorded with:
| Field | Value |
| ---------- | ------------- |
| Module | `ai_forms` |
| Operation | `form_submit` |
| Scope type | `ai_form` |
| Scope ID | Form ID |
This lets usage rules target all AI Forms or a specific form.
## Troubleshooting
Check the form ID in the shortcode or block. The form must exist and be published. Admin users see shortcode errors; visitors see empty output.
Configure and sync the provider in [AI Providers](/ai-providers). If the frontend selector is enabled, also check **AI Puffer > AI Forms > Settings > Frontend Models**.
Check the field's **Field Variable Name** in **Element Settings** and make sure the prompt uses the same placeholder, for example `{customer_message}`.
Make sure the checkbox field has options and that the visitor selects at least one option before submitting.
Use a TXT or text-based PDF file. If the server rejects uploads, check WordPress upload limits and security plugin rules.
Use a JPG, PNG, or WEBP image under 20 MB, and make sure the selected provider and model support image input. xAI image analysis accepts JPG and PNG images.
The visitor must be logged in and must have permission to create or edit posts.
Enable **Save as PDF** in the shortcode settings, or add `pdf_download="true"` to the shortcode.
Check that the recipe is enabled, the app connection is valid, the scope includes this form, and the recipe uses the **AI Form Submitted** event.
Check that the source form is saved, **Enable Workflow** is on, the target form still exists, and the source and target are not the same form. Workflow appears only after the source AI response completes.
Check the target field names and the workflow mappings. Mappings can prefill text input and textarea fields in the target form. File upload and image upload fields are not prefilled.
Check that **Auto-submit next form** is enabled on the source form and that the target form has all required values after mappings are applied. Required uploads and multi-step target forms wait for the visitor.
# AI Providers
Source: https://docs.aipower.org/ai-providers
Connect the model providers and service integrations used by AI Puffer.
## Overview
AI Puffer uses a bring-your-own-key model. Add your provider credentials, sync models, then choose the provider and model inside each module.
When you purchase AI Puffer Pro, you get access to additional plugin features. API usage is separate. You still need your own provider account and billing setup for OpenAI, Google, Anthropic, xAI, or any other provider you connect. AI Puffer does not include API credits.
Text, images, embeddings, speech, web, and realtime.
Gemini, images, video, embeddings, TTS, and grounding.
Text, web search, and supported image analysis.
Access many text, image, embedding, and web-capable models.
Azure OpenAI deployments for text, images, embeddings, and speech.
Text generation for chat, writing, forms, and automations.
Grok text models, web search, supported image analysis, and image generation.
Local or self-hosted text and embedding models.
AI providers power text, image, audio, embedding, and retrieval features.
| Provider | Text | Images | Embeddings | Audio | Video | Web | Realtime |
| ---------- | ---- | ------ | ---------- | --------- | ----- | --- | -------- |
| OpenAI | ✓ | ✓ | ✓ | TTS + STT | - | ✓ | ✓ |
| Google | ✓ | ✓ | ✓ | TTS | ✓ | ✓ | - |
| Anthropic | ✓ | - | - | - | - | ✓ | - |
| OpenRouter | ✓ | ✓ | ✓ | - | - | ✓ | - |
| Azure | ✓ | ✓ | ✓ | STT | - | - | - |
| DeepSeek | ✓ | - | - | - | - | - | - |
| xAI | ✓ | ✓ | - | - | - | ✓ | - |
| Ollama | ✓ | - | ✓ | - | - | - | - |
`✓` means supported. `-` means not supported in the current provider strategy.
**AI Puffer > Settings** is the central area for managing your connections to different AI providers.
![Settings]()
## OpenAI
OpenAI supports the widest set of AI Puffer features.
1. Open **AI Puffer > Settings > AI**.
2. Select **OpenAI**.
3. Paste your OpenAI API key.
4. Keep the default base URL unless you use a compatible custom endpoint.
5. Open **Advanced** and click **Sync Models**.
6. Select the model you want to use by default.
For knowledge features, OpenAI embedding models are available in embedding model selectors. OpenAI Vector Stores are created and managed in **Knowledge Base > Stores**.
OpenAI moderation is also available under **Advanced**. Set **Moderation** to **Yes** to check OpenAI chatbot input with OpenAI moderation, then set **Moderation Message** if you want to customize the message shown when input is blocked.
![OpenAI API key settings]()
## Google
Google provides Gemini, embeddings, image/video models, text to speech, and grounding.
1. Open **AI Puffer > Settings > AI**.
2. Select **Google**.
3. Paste your Google API key.
4. Open **Advanced** and click **Sync Models**.
5. Select the default model.
6. Review Google safety settings if you need to change blocking thresholds.
Google image and video model settings are configured in Images.
Google safety settings can block some responses. Change them only when the default behavior is too restrictive for your site.
![Google API key settings]()
## Anthropic
Anthropic is available for text workflows, web search, and supported Claude image analysis models.
1. Open **AI Puffer > Settings > AI**.
2. Select **Anthropic**.
3. Paste your Anthropic API key.
4. Open **Advanced** and click **Sync Models**.
5. Select the default model.
Anthropic does not provide embeddings through the current AI Puffer provider strategy.
![Anthropic API key settings]()
## OpenRouter
OpenRouter gives access to models available in your OpenRouter account.
1. Open **AI Puffer > Settings > AI**.
2. Select **OpenRouter**.
3. Paste your OpenRouter API key.
4. Open **Advanced** and click **Sync Models**.
5. Select the default model.
Some capabilities depend on the selected model.
OpenRouter support depends on the model you select. Check the model capabilities before using image, embedding, or web features.
![OpenRouter API key settings]()
## Azure
Azure uses your Azure OpenAI deployments.
1. Open **AI Puffer > Settings > AI**.
2. Select **Azure**.
3. Paste your Azure API key.
4. Enter the Azure endpoint URL for your resource.
5. Open **Advanced**.
6. Check the API versions if your Azure resource requires different versions.
7. Click **Sync Models** to load deployments.
8. Select the deployment to use as the default model.
Azure uses deployment names. If a deployment does not appear, confirm it exists in Azure and that the endpoint and API key belong to the same resource.
![Azure API key settings]()
## DeepSeek
DeepSeek is available for text workflows.
1. Open **AI Puffer > Settings > AI**.
2. Select **DeepSeek**.
3. Paste your DeepSeek API key.
4. Open **Advanced** and click **Sync Models**.
5. Select the default model.
DeepSeek embeddings are not supported by the current provider strategy. Use OpenAI, Google, Azure, OpenRouter, or Ollama for embedding workflows.
![DeepSeek API key settings]()
## xAI
xAI is available for text workflows, Grok models, web search, supported image analysis models, and image generation.
1. Open **AI Puffer > Settings > AI**.
2. Select **xAI**.
3. Paste your xAI API key.
4. Keep the default base URL unless you use a compatible xAI endpoint.
5. Keep the API version as `v1`.
6. Open **Advanced** and click **Sync Models**.
7. Select the default text model.
AI Puffer uses xAI's Responses API for text generation and streaming. Legacy completions and chat completions are not used by this provider integration.
xAI image generation and image editing use xAI image models such as `grok-imagine-image`. xAI image understanding uses Grok language models that support image input.
xAI is not available as an embedding provider, vector store provider, video provider, speech provider, or realtime voice provider in the current integration.
![xAI API key settings]()
## Ollama
Ollama connects local or self-hosted models.
1. Install Ollama from [ollama.com/download](https://ollama.com/download).
2. Run Ollama on the computer or server you want to use as the AI server.
3. Pull a model:
```bash theme={null}
ollama pull llama3
```
4. Open **AI Puffer > Settings > AI**.
5. Select **Ollama**.
6. Enter the Ollama base URL. The default is `http://localhost:11434`.
7. Click **Sync Models**.
8. Select the default model.
Install notes:
| System | Notes |
| ------- | ------------------------------------------------------------------------------------------------ |
| macOS | Download the macOS ZIP, move Ollama to Applications, then run the app. |
| Windows | Run the Windows installer. Ollama runs in the background after installation. |
| Linux | Run `curl -fsSL https://ollama.com/install.sh \| sh`. The installer sets up Ollama as a service. |
You can pull more than one model. AI Puffer shows synced Ollama models after **Sync Models** runs.
If WordPress and Ollama are on different servers, do not use `localhost` unless Ollama is running on the same server as WordPress. Use the reachable server URL instead.
Do not expose Ollama publicly without access controls. Anyone who can reach the Ollama server can send model requests to it.
![Ollama API key settings]()
## WordPress AI Connectors
WordPress 7.0 includes a built-in AI Client and a **Settings > Connectors** screen. AI Puffer can manage those WordPress AI connectors so WordPress AI features, themes, and plugins that call `wp_ai_client_prompt()` use your AI Puffer provider setup.
This does not replace the provider setup above. Add your provider keys in **AI Puffer > Settings > AI** first, then enable connector management when you want WordPress AI Client requests to route through AI Puffer.
AI Puffer exposes OpenAI, Google, Anthropic, OpenRouter, Azure OpenAI, DeepSeek, xAI, and Ollama to the WordPress AI Client. Replicate remains available in AI Puffer's Images module, but it is not exposed as a WordPress AI connector.
See [WordPress AI Connectors](/wordpress-ai-connectors).
## Troubleshooting
The provider account is out of credits, has reached a spend limit, or is blocked by billing settings.
Check these items:
1. Open the provider billing page.
2. Check credits, usage limits, and monthly spend limits.
3. Add credits or update billing if needed.
4. If you just changed billing, wait a few minutes and try again.
For OpenAI, see [error codes](https://developers.openai.com/api/docs/guides/error-codes).
The saved key is wrong, old, revoked, copied with extra spaces, or belongs to a different account or organization.
Check these items:
1. Create or copy a fresh API key from the provider dashboard.
2. Paste it again in **AI Puffer > Settings > AI**.
3. Save the setting.
4. Sync models again.
For OpenAI, see [Incorrect API key provided](https://help.openai.com/en/articles/6882433-incorrect-api-key-provided).
AI Puffer syncs models when you switch providers, but the list can be out of date.
Check these items:
1. Open **AI Puffer > Settings > AI**.
2. Select the provider.
3. Open **Advanced**.
4. Click **Sync Models**.
5. Open **Settings > Others**.
6. Click **Clear Model Cache**.
7. Click **Clear Transients**.
8. Click **Sync All**.
9. Return to **Settings > AI** and check the model list again.
![Settings Others model cache buttons]()
If the model still does not appear, confirm the provider account has access to that model.
Some OpenAI models require a verified API organization.
Check these items:
1. Open OpenAI Platform settings.
2. Go to **Organization > General**.
3. Complete organization verification.
4. Wait up to 30 minutes.
5. Generate a new API key if the error continues.
6. Make sure AI Puffer is using a key from the verified organization.
For OpenAI, see [API Organization Verification](https://help.openai.com/en/articles/10910291-api-organisation-verifiering).
A WordPress security plugin or firewall may be blocking AI Puffer settings requests.
Check these items:
1. Check your security plugin or firewall logs.
2. Whitelist AI Puffer admin requests if your tool supports allow rules.
3. If using Wordfence or a similar firewall, switch to learning mode.
4. Save AI Puffer settings and use the affected module a few times.
5. Switch the firewall back to normal mode after it learns the requests.
# API Reference
Source: https://docs.aipower.org/api-reference
Use AI Puffer REST endpoints from external applications.
AI Puffer exposes REST endpoints under the WordPress REST API.
Use the API when an external application needs to generate text, generate images, create embeddings, send a message to a chatbot, read chat logs, or add content to a vector store.
Base URL:
```text theme={null}
https://your-site.com/wp-json/aipkit/v1
```
## Authentication
Most endpoints require the AI Puffer REST API key.
1. Open **WordPress Admin > AI Puffer > Settings**.
2. Open **Developers**.
3. Enter a value in **REST API Key**.
4. Wait for the setting to save.
![Developer Settings with the REST API Key field]()
Leaving the field blank disables REST API access.
Treat the key like a password. Anyone with the key can call the enabled REST endpoints from outside WordPress.
### Send the key in a header
Use an `Authorization` header when possible.
```bash theme={null}
curl https://your-site.com/wp-json/aipkit/v1/logs \
-H "Authorization: Bearer YOUR_API_KEY"
```
### Send the key as a request parameter
You can also send the key as `aipkit_api_key`.
```bash theme={null}
curl https://your-site.com/wp-json/aipkit/v1/logs?aipkit_api_key=YOUR_API_KEY
```
## Endpoints
| Endpoint | Method | Use |
| --------------------------------- | ------ | -------------------------------------------------------------- |
| `/generate` | `POST` | Generate text with a configured AI provider. |
| `/images/generate` | `POST` | Generate images. |
| `/embeddings` | `POST` | Create embeddings from text. |
| `/chat/{bot_id}/message` | `POST` | Send a message to a chatbot. |
| `/logs` | `GET` | Read saved chat logs. |
| `/vector-stores/upsert` | `POST` | Embed text and upsert it into Pinecone, Qdrant, or Chroma. |
| `/chatbots/{bot_id}/embed-config` | `GET` | Read the embed config and HTML for an external chatbot widget. |
## Text generation
Generate a text response with one of the configured text providers.
```text theme={null}
POST /wp-json/aipkit/v1/generate
```
### Parameters
| Parameter | Type | Required | Notes |
| -------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------- |
| `provider` | string | Yes | `openai`, `azure`, `google`, `openrouter`, `claude` for Anthropic, `deepseek`, `xai`, or `ollama`. |
| `model` | string | Yes | Model ID or Azure deployment ID. |
| `messages` | array | Yes | Chat-style messages with `role` and `content`. Roles: `system`, `user`, `assistant`. |
| `system_instruction` | string | No | Extra instruction text. Supports `[date]` and `[username]`. |
| `ai_params` | object | No | Overrides for AI parameters such as `temperature` or `max_completion_tokens`. |
| `stream` | boolean | No | This endpoint does not support streaming. Leave it as `false`. |
### Request
```bash theme={null}
curl -X POST https://your-site.com/wp-json/aipkit/v1/generate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"provider": "openai",
"model": "gpt-4o-mini",
"messages": [
{
"role": "user",
"content": "Write a two sentence product description for a handmade ceramic mug."
}
],
"ai_params": {
"temperature": 0.7
}
}'
```
### Response
```json theme={null}
{
"content": "A handmade ceramic mug with a simple shape and a smooth glazed finish. Suitable for coffee, tea, or daily desk use.",
"usage": {
"input_tokens": 18,
"output_tokens": 25,
"total_tokens": 43
},
"provider": "OpenAI",
"model": "gpt-4o-mini"
}
```
## Image generation
Generate images from a text prompt.
```text theme={null}
POST /wp-json/aipkit/v1/images/generate
```
### Parameters
| Parameter | Type | Required | Notes |
| ----------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `prompt` | string | Yes | Text prompt for the image. |
| `provider` | string | No | `openai`, `azure`, or `google`. Default: `openai`. |
| `model` | string | No | Image model ID. Uses plugin settings if omitted. |
| `n` | integer | No | Number of images. Minimum `1`, maximum `10`. Default: `1`. |
| `size` | string | No | Supported values include `1024x1024`, `1792x1024`, `1024x1792`, `1536x1024`, `1024x1536`, `1024x768`, and `768x1024`. |
| `quality` | string | No | `standard` or `hd`, when supported by the selected model. |
| `style` | string | No | `vivid` or `natural`, when supported by the selected model. |
| `response_format` | string | No | `url` or `b64_json`. Default: `url`. |
### Request
```bash theme={null}
curl -X POST https://your-site.com/wp-json/aipkit/v1/images/generate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"provider": "openai",
"model": "gpt-image-1",
"prompt": "A clean product photo of a handmade ceramic mug on a white table",
"n": 1,
"size": "1024x1024",
"response_format": "url"
}'
```
### Response
```json theme={null}
{
"images": [
{
"url": "https://example.com/generated-image.png",
"b64_json": null,
"revised_prompt": null
}
],
"usage": null,
"message": "1 image generated successfully."
}
```
## Embeddings
Create embeddings from one string or an array of strings.
```text theme={null}
POST /wp-json/aipkit/v1/embeddings
```
### Parameters
| Parameter | Type | Required | Notes |
| ----------------------- | --------------- | -------- | ------------------------------------------------------------------- |
| `provider` | string | Yes | `openai`, `google`, `azure`, or `openrouter`. |
| `model` | string | Yes | Embedding model ID or Azure deployment ID. |
| `input` | string or array | Yes | Text to embed. |
| `dimensions` | integer | No | OpenAI, OpenRouter, or Azure output dimensions when supported. |
| `encoding_format` | string | No | OpenAI or OpenRouter format: `float` or `base64`. Default: `float`. |
| `task_type` | string | No | Google embedding task type. |
| `output_dimensionality` | integer | No | Google embedding output dimension size. |
| `user` | string | No | End-user identifier for OpenAI or Azure monitoring. |
Google `task_type` values:
```text theme={null}
SEMANTIC_SIMILARITY
CLASSIFICATION
CLUSTERING
RETRIEVAL_DOCUMENT
RETRIEVAL_QUERY
QUESTION_ANSWERING
FACT_VERIFICATION
CODE_RETRIEVAL_QUERY
```
### Request
```bash theme={null}
curl -X POST https://your-site.com/wp-json/aipkit/v1/embeddings \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"provider": "openai",
"model": "text-embedding-3-small",
"input": "AI Puffer is a WordPress plugin."
}'
```
### Response
```json theme={null}
{
"embeddings": [
[-0.0069, -0.0053, 0.0124]
],
"usage": {
"input_tokens": 8,
"total_tokens": 8
},
"provider": "OpenAI",
"model": "text-embedding-3-small"
}
```
## Chat message
Send a message to one chatbot.
The chatbot must exist in WordPress. The request uses the chatbot settings saved in AI Puffer.
```text theme={null}
POST /wp-json/aipkit/v1/chat/{bot_id}/message
```
### Parameters
| Parameter | Type | Required | Notes |
| ---------- | ------- | -------- | ------------------------------------------------------------------------------------------ |
| `bot_id` | integer | Yes | Chatbot ID in the URL. |
| `messages` | array | Yes | Conversation history. Roles: `user` and `assistant`. The last message must be from `user`. |
### Request
```bash theme={null}
curl -X POST https://your-site.com/wp-json/aipkit/v1/chat/123/message \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"messages": [
{
"role": "user",
"content": "What can you help with?"
}
]
}'
```
### Response
```json theme={null}
{
"reply": "I can answer questions using the chatbot settings configured in WordPress.",
"usage": {
"input_tokens": 15,
"output_tokens": 13,
"total_tokens": 28
},
"bot_id": 123,
"model": "gpt-4o-mini"
}
```
## Chat logs
Read saved chatbot conversation logs.
```text theme={null}
GET /wp-json/aipkit/v1/logs
```
### Parameters
| Parameter | Type | Required | Notes |
| ---------------- | ------- | -------- | --------------------------------------------- |
| `page` | integer | No | Page number. Default: `1`. |
| `per_page` | integer | No | Logs per page. Default: `20`, maximum: `100`. |
| `bot_id` | integer | No | Filter by chatbot ID. |
| `user_search` | string | No | Search display name, username, or email. |
| `message_search` | string | No | Search conversation content. |
The response includes pagination headers:
| Header | Meaning |
| ----------------- | -------------------- |
| `X-WP-Total` | Total matching logs. |
| `X-WP-TotalPages` | Total pages. |
### Request
```bash theme={null}
curl "https://your-site.com/wp-json/aipkit/v1/logs?per_page=10&bot_id=123" \
-H "Authorization: Bearer YOUR_API_KEY"
```
### Response
```json theme={null}
[
{
"id": "1",
"bot_id": "123",
"user_id": "1",
"session_id": null,
"conversation_uuid": "e8a3c-b3a1-4f9e",
"messages": "[...]",
"message_count": "4",
"last_message_ts": "1724081015",
"created_at": "2026-04-25 10:00:00",
"bot_name": "Support Bot",
"user_display_name": "admin"
}
]
```
## Vector store upsert
Embed text and add the vectors to Pinecone, Qdrant, or Chroma.
The target index or collection must already exist. AI Puffer creates embeddings, then sends vectors to the selected vector database.
```text theme={null}
POST /wp-json/aipkit/v1/vector-stores/upsert
```
### Parameters
| Parameter | Type | Required | Notes |
| -------------------- | ------ | -------- | ----------------------------------------------------------------------- |
| `provider` | string | Yes | `pinecone`, `qdrant`, or `chroma`. |
| `target_id` | string | Yes | Pinecone index name, Qdrant collection name, or Chroma collection name. |
| `vectors` | array | Yes | Objects with `content`. Optional `id` and `metadata`. |
| `embedding_provider` | string | Yes | `openai`, `google`, `azure`, or `openrouter`. |
| `embedding_model` | string | Yes | Embedding model ID or Azure deployment ID. |
| `namespace` | string | No | Pinecone namespace. Ignored by Qdrant and Chroma. |
Each `vectors` item must include:
| Field | Type | Required | Notes |
| ---------- | ------ | -------- | ----------------------------------------------------------------------- |
| `content` | string | Yes | Text to embed and store. |
| `id` | string | No | Vector ID. AI Puffer generates one if omitted. |
| `metadata` | object | No | Extra metadata. AI Puffer also stores the original content in metadata. |
### Request
```bash theme={null}
curl -X POST https://your-site.com/wp-json/aipkit/v1/vector-stores/upsert \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"provider": "pinecone",
"target_id": "site-knowledge",
"embedding_provider": "openai",
"embedding_model": "text-embedding-3-small",
"namespace": "docs",
"vectors": [
{
"id": "intro",
"content": "AI Puffer adds AI tools to WordPress.",
"metadata": {
"source": "manual"
}
}
]
}'
```
### Response
```json theme={null}
{
"upserted_count": 1,
"status": "success"
}
```
## Chatbot embed config
Read the config and rendered HTML for an externally embedded chatbot.
This endpoint is not authenticated with the REST API key. Access is controlled by the chatbot's embed settings and allowed domains.
```text theme={null}
GET /wp-json/aipkit/v1/chatbots/{bot_id}/embed-config
```
### Parameters
| Parameter | Type | Required | Notes |
| --------- | ------- | -------- | ---------------------- |
| `bot_id` | integer | Yes | Chatbot ID in the URL. |
### Response
```json theme={null}
{
"config": {
"botId": 123,
"assetUrls": {
"css": "https://your-site.com/wp-content/plugins/.../public-main.bundle.css",
"mainJs": "https://your-site.com/wp-content/plugins/.../public-main.bundle.js"
}
},
"html": "...
"
}
```
If the request origin is not allowed, the endpoint returns `403`.
## Error format
Errors use the standard WordPress REST error format.
```json theme={null}
{
"code": "rest_aipkit_invalid_api_key",
"message": "Invalid or missing API Key.",
"data": {
"status": 401
}
}
```
# Automations
Source: https://docs.aipower.org/automations
Create, schedule, and monitor AI Puffer automations.
## Overview
Use Automations to create content, rewrite published WordPress content, keep a knowledge base current, or reply to new comments in the background.
In WordPress admin, go to **AI Puffer > Automations**.
![Quick create automation]()
Before you begin, configure the AI provider, image provider, vector store, or source connection required by the automation. If the Automations menu is not visible, check **AI Puffer > Settings > Modules** and confirm that your WordPress role has access to it.
Create posts from topics, CSV files, RSS feeds, URLs, or Google Sheets.
Rewrite selected fields in published WordPress content.
Add WordPress content to a vector store and keep it current.
Generate replies for matching approved comments.
Configure AI, prompts, SEO, publishing, images, and knowledge.
Review pending, completed, and failed work.
To create an automation:
1. Click **Create automation** on the welcome screen, or **New automation** above the task list.
2. Select what you want to automate.
3. Complete **Setup** for that automation type.
4. Click **Untitled** at the top if you want to name the task.
5. Continue through the settings shown for the selected automation.
6. Review **Finish** and click **Save task**.
![Create a new automation]()
The progress bar shows your position. Use **Previous** to return to an earlier setting. Completed settings show a summary of their values.
After the required setup fields are complete, click **Quick create** to save with recommended defaults for everything else. If required information is missing, AI Puffer shows it near the setting that needs attention. You can edit the task later to customize any saved default.
![Quick create automation]()
The **Tasks** table shows each automation's name, type, frequency, status, last run, next run, and actions.
| Action | What it does |
| ----------- | --------------------------------------------------------- |
| **Edit** | Opens the task with its saved settings. |
| **Pause** | Stops future scheduled runs. Existing queue items remain. |
| **Resume** | Schedules a paused task again. |
| **Run now** | Checks an active, configured task immediately. |
| **Delete** | Permanently deletes the task after confirmation. |
To edit a task, click its edit icon, open any setting you want to change, then open **Finish** and click **Save changes**.
## How Automations Run
Automations use WordPress cron.
1. The saved task runs at its selected frequency.
2. It finds eligible work and adds queue items.
3. The queue processor handles pending items in batches.
4. Each item becomes **Completed** or **Failed**.
The queue processor handles up to 5 pending items per run. If more items remain, AI Puffer schedules another queue run about 30 seconds later.
WordPress cron depends on site traffic unless you run a real server cron. If traffic is low, tasks can run late. If `DISABLE_WP_CRON` is enabled, configure a server cron for WordPress.
## Create Content
Select **Create new content** in **Setup** to create posts, pages, products, or other supported post types.
The available settings are **Setup**, **AI**, **Content**, **Images**, **SEO**, **Knowledge**, and **Finish**. Use **Quick create** after entering a valid source when you want to keep the recommended defaults.
Choose one source under **Content source**:
| Source control | Use it for | Availability |
| ---------------- | ---------------------------------------- | ------------ |
| **Batch editor** | Enter and fine-tune topics in rows. | Free |
| **Quick paste** | Paste several topics at once. | Free |
| **Import CSV** | Upload a structured topic list. | Free |
| **RSS feed** | Watch feeds for new items. | Pro |
| **URL** | Create content from extracted web pages. | Pro |
| **Spreadsheet** | Read rows from Google Sheets. | Pro |
Each saved automation uses the source selected when you save it. **Batch editor** and **Quick paste** are synchronized views of the same Manual Entry topic list.
### Manual Entry
Use **Batch editor** or **Quick paste** for manual entry.
Use **Batch editor** when you want to review each item as a row:
1. Select **Create new content**.
2. Select **Batch editor** under **Content source**.
3. Enter a topic and, if needed, keywords.
4. Click **Details** to set a category, author, post type, or schedule for that row.
5. Click **Add another topic** for more rows.
6. Continue to **AI**, or click **Quick create**.
![Batch editor for Manual Entry]()
Use **Quick paste** when you want to paste several items at once. Enter one item per line, then switch to **Batch editor** if you want to review or edit the parsed rows.
Basic format:
```text theme={null}
Topic
```
Extended format:
```text theme={null}
Topic | Keywords | Category ID | Author Login | Post Type | Schedule
```
Example:
```text theme={null}
How to clean leather boots | leather care, boots | 12 | editor | post | 2026-05-01 09:00
```
![Quick paste for Manual Entry]()
### CSV
Use **Import CSV** to upload a structured topic list.
[Download the sample CSV](https://docs.google.com/spreadsheets/d/1WOnO_UKkbRCoyjRxQnDDTy0i-RsnrY_MDKD3Ks09JJk/export?format=csv\&gid=0)
1. Select **Import CSV**.
2. Drop a `.csv` file into the upload area, or click to browse.
3. Wait for AI Puffer to show how many topics were found.
4. Continue to **AI**, or click **Quick create**.
| Column | Field | Required |
| ------ | ------------ | -------- |
| 1 | Topic | Yes |
| 2 | Keywords | No |
| 3 | Category ID | No |
| 4 | Author Login | No |
| 5 | Post Type | No |
| 6 | Schedule | No |
Do not include a header row unless you want it treated as a topic.
![Import CSV source]()
### RSS Feed
RSS Feed is a Pro feature. Select **RSS feed** under **Content source**.
1. Enter one feed URL per line.
2. Add **Only titles containing** keywords if only matching titles should be used.
3. Add **Skip titles containing** keywords if matching titles should be ignored.
4. Click **Fetch Feeds** to check the sources.
5. Continue through the remaining settings.
6. In **Finish**, choose how often the task should check the feeds.
The task records processed feed items to avoid using the same item again. **Run now** checks recent items but still skips items already in the task history.
![RSS Feed source]()
### Web Page
Web Page is a Pro feature. Select **URL** under **Content source**.
1. Enter one page URL per line.
2. Click **Test First URL** to preview the first page's extracted content.
3. Continue through the remaining settings.
4. In **Finish**, choose how often the task should check the URLs.
AI Puffer extracts readable page text and makes it available to the content instructions.
| Placeholder | Value |
| --------------- | -------------------- |
| `{url_content}` | Extracted page text. |
| `{source_url}` | Source URL. |
![Web Page URL source]()
### Google Sheets
Google Sheets is a Pro feature. Select **Spreadsheet** under **Content source**.
[Open the sample Google Sheet](https://docs.google.com/spreadsheets/d/18QIWggMmbTVTb-nztTo7SFdGJTUC6kwRxgc841xq4x0/edit?gid=0#gid=0), make a copy, and keep the same column order.
| Column | Field | Notes |
| ------ | ------------ | ---------------------------------------------- |
| A | Topic | Required. |
| B | Keywords | Optional. |
| C | Category ID | Optional. |
| D | Author Login | Optional. |
| E | Post Type | Optional. |
| F | Schedule | Optional. |
| G | Status | Leave empty for rows that should be processed. |
AI Puffer processes a row only when column A has a topic and column G is empty. After creating the post, it writes `Processed on ...` to column G.
If you use a header row, put a value such as `Status` in column G for that row so AI Puffer skips it.
To connect the sheet:
1. Paste the **Sheet ID**. It is the value between `/d/` and `/edit` in the sheet URL.
2. Upload the Google service-account JSON file under **Credentials**.
3. Share the sheet with the JSON file's `client_email` as an **Editor**.
4. Confirm that the sheet and credentials are detected.
5. Use **Lock** when you want to keep the saved values visible but read-only.
6. Continue through the remaining settings.
Keep the service-account JSON file private. Anyone with this file can use the permissions granted to that service account.
For the complete Google Cloud setup, see [Google Sheets in Content Writer](/content-writer#google-sheets).
![Google Sheets source]()
## Optimize
Select **Rewrite existing content** in **Setup** to update selected fields in published WordPress content. This is a Pro feature.
Rewrite automations update WordPress content directly. Start with a narrow selection and a small test before enabling a broad rewrite.
### Rewrite Posts and Pages
The available settings are **Setup**, **AI**, **Content**, optional **Knowledge**, and **Finish**.
1. Select one or more **Content types**.
2. Optionally limit the task with **Categories** or **Authors**. Use search when an expanded list is long.
3. Turn on **Include existing content** if current matches should be queued when the task is saved.
4. In **AI**, select the model, writing style, maximum rewrite length, and supported reasoning level.
5. In **Content**, enable at least one field and review its **Instructions**.
6. Optionally configure **Knowledge**.
7. In **Finish**, set the task frequency and save the task.
Rewrite automations process published content only. When **Include existing content** is off, scheduled runs process content that becomes eligible later.
![Rewrite Posts and Pages setup]()
| Field | What AI Puffer updates |
| -------------------- | ---------------------------------------------- |
| **Title** | WordPress post title. |
| **Content** | WordPress post content. |
| **Excerpt** | WordPress post excerpt. |
| **Meta Description** | SEO meta description in supported SEO plugins. |
Click **Instructions** and the pencil icon beside an enabled field to edit its rewrite instructions.
Common rewrite placeholders:
| Placeholder | Value |
| ----------------------------- | -------------------------------------------------- |
| `{original_title}` | Existing post title. |
| `{original_content}` | Existing post content without shortcodes and HTML. |
| `{original_excerpt}` | Existing excerpt. |
| `{original_meta_description}` | Existing meta description or excerpt fallback. |
| `{original_focus_keyword}` | Existing focus keyword when available. |
| `{original_tags}` | Existing tags. |
| `{categories}` | Existing categories. |
### WooCommerce Products
Select `product` under **Content types** to rewrite WooCommerce product titles, main descriptions, short descriptions, or SEO meta descriptions.
![WooCommerce product rewrite automation]()
Product prompts can use the normal rewrite placeholders and these WooCommerce values:
| Placeholder | Value |
| ---------------------- | ------------------- |
| `{price}` | Product price. |
| `{regular_price}` | Regular price. |
| `{sku}` | SKU. |
| `{attributes}` | Product attributes. |
| `{stock_quantity}` | Stock quantity. |
| `{stock_status}` | Stock status. |
| `{weight}` | Product weight. |
| `{length}` | Product length. |
| `{width}` | Product width. |
| `{height}` | Product height. |
| `{purchase_note}` | Purchase note. |
| `{product_categories}` | Product categories. |
AI Puffer uses those values as source data. The rewrite task does not change price, SKU, stock, dimensions, purchase note, categories, or attributes.
## Content Indexing
Select **Build a knowledge base** in **Setup** to add published WordPress content to OpenAI, Pinecone, Qdrant, or Chroma and keep it current.
1. Select a **Provider**.
2. Select the destination **Store / Index**.
3. Select the **Embedding Model**. The picker includes the embedding provider and model.
4. Select one or more **Content types**.
5. Leave **Queue all existing content now** on to build the initial knowledge base.
6. Leave **Auto-index new and updated content** on to keep it current.
7. Continue to **Finish**, choose how often the task should run, and click **Save task**.
![Content Indexing automation]()
| Setting | What it does |
| -------------------------------------- | -------------------------------------------------------- |
| **Queue all existing content now** | Queues current published content, then turns itself off. |
| **Auto-index new and updated content** | Checks for selected content changed after the last run. |
AI Puffer queues existing content in batches. **Run now** queues matching published content again.
For Pinecone, Qdrant, and Chroma, the destination vector dimension must match the selected embedding model.
## Comment Replies
Select **Reply to comments** in **Setup** to generate replies for matching approved WordPress comments.
1. Under **Content types**, select the post types to monitor.
2. Under **Action on reply**, choose **Approve** or **Hold for moderation**.
3. Select **Top-level comments only** if AI Puffer should not reply to other replies.
4. Optionally complete **Only reply if comment contains** and **Do not reply if comment contains**.
5. Click **Instructions** beside **Reply Prompt** to review or change the prompt.
6. Continue to **AI** and select the text model.
7. In **Finish**, choose the task frequency and save the task.
![Comment Replies automation]()
| Placeholder | Value |
| ------------------- | ---------------------------- |
| `{comment_content}` | Original comment text. |
| `{comment_author}` | Original comment author. |
| `{post_title}` | Title of the commented post. |
Scheduled runs avoid queueing a comment that the same task already queued or replied to. Replies are inserted as child comments. AI Puffer uses the post author when possible and falls back to the site administrator.
## Settings
The available settings depend on the selected automation type.
### Task Schedule
Open **Finish** to configure the task schedule.
| Setting | What it does |
| ---------------------------- | --------------------------------------------- |
| **Schedule** | Starts the automation after it is saved. |
| **How often should it run?** | Sets how often a recurring source is checked. |
**Batch editor** and **Import CSV** are one-time sources, so their frequency row is hidden. Recurring sources and task types can use One-time, Every 5 Minutes, Every 15 Minutes, Every 30 Minutes, Hourly, Twice Daily, Daily, or Weekly.
![Task Schedule settings]()
### AI
Use **AI** to configure tasks that generate or rewrite text.
| Setting | What it does |
| -------------------------- | ----------------------------------------------------- |
| **Model** | Selects the provider and model in one list. |
| **Content length** | Uses a Short, Medium, or Long target for new content. |
| **Writing style** | Moves between focused, balanced, and creative output. |
| **Maximum rewrite length** | Sets the maximum output tokens for rewrite tasks. |
| **Reasoning level** | Sets reasoning effort for supported models. |
The model picker prefers a configured provider when one is available. If the selected provider needs setup, AI Puffer shows a warning and a link to settings.
**Reasoning level** appears only when the selected provider and model support it.
![AI settings]()
### Prompts
Use **Content** to control which fields AI Puffer writes and how each one is generated.
For new content, **Title** and **Article content** are always included. **Meta description**, **Focus keyword**, **Excerpt**, and **Tags** are optional.
To customize a field:
1. Turn on an optional field if needed.
2. Click **Instructions** and the pencil icon beside the field.
3. Select a saved prompt or edit the instructions.
4. Use the placeholders shown in the editor.
5. Click **Save**.
The label changes to **Custom instructions** when the built-in instructions have been changed.
![Automation prompts]()
| Source | Common placeholders |
| -------------------------------------- | ---------------------------------- |
| Manual Entry, CSV, Google Sheets | `{topic}` and `{keywords}` |
| RSS Feed | `{description}` and `{source_url}` |
| Web Page | `{url_content}` and `{source_url}` |
| Outputs based on the generated article | `{content_summary}` |
Rewrite prompts are also edited through **Instructions** in **Content**. The Comment Replies prompt is edited through **Instructions** beside **Reply Prompt** in **Setup**.
AI Puffer validates required placeholders before generation. Fix a missing required placeholder before running the task again.
### SEO
Use **SEO** in a Create Content automation to configure search optimization.
| Setting | What it does |
| ------------------------------- | --------------------------------------------------- |
| **Optimize each post for SEO?** | Enables Smart SEO for generated posts. Pro feature. |
| **How should we optimize it?** | Opens the SEO approach dialog. |
| **Optimize URL** | Creates a concise, search-friendly post slug. |
| **Table of contents** | Adds navigation links to the post. |
If a supported SEO plugin is active, AI Puffer shows its name in the first row.
![Automation SEO settings]()
#### Smart SEO
Smart SEO is a Pro feature. It checks each generated post against the active SEO plugin profile and can revise the draft before the queue item completes.
Choose an approach:
| Approach | Use it when |
| ----------------- | ------------------------------------------------------------------- |
| **Strict score** | Matching every available SEO check matters most. |
| **Balanced** | You want the recommended balance of SEO checks and natural writing. |
| **Content first** | Natural writing matters more than maximizing a plugin score. |
Click **Manage checks** to enable or disable individual rules. If Smart SEO cannot reach the target score, AI Puffer keeps the best revision.
![Smart SEO automation settings]()
For the complete rule reference, see [Smart SEO in Content Writer](/content-writer#smart-seo).
#### Yoast SEO
AI Puffer saves the generated meta description to the Yoast description field and the generated focus keyword to the Yoast focus keyphrase field. Smart SEO uses Yoast analysis and readability checks.
#### Rank Math
AI Puffer saves the generated meta description and focus keyword to Rank Math. Smart SEO uses Rank Math's Basic SEO, Additional SEO, Title Readability, and Content Readability checks.
#### All in One SEO
AI Puffer saves the generated meta description and focus keyphrase data to All in One SEO. Smart SEO uses TruSEO, keyphrase, readability, and headline checks.
#### The SEO Framework
AI Puffer saves the generated meta description to The SEO Framework. The SEO Framework does not provide a native focus keyword field, so AI Puffer does not save one for this profile.
If no supported SEO plugin is active, AI Puffer still saves fallback meta description data. WordPress tags and optimized URL slugs continue to work.
### Publishing
Use **Finish** to configure how generated WordPress posts are saved.
| Setting | What it does |
| -------------- | ---------------------------------------------------------------------------- |
| **Status** | Saves as draft, publishes immediately, holds for review, or saves privately. |
| **Post Type** | Selects the destination public WordPress post type. |
| **Author** | Selects the WordPress author. |
| **Categories** | Assigns supported categories. |
![Publishing settings]()
#### Schedule
When **Status** is **Publish immediately**, choose a publishing mode:
| Publishing mode | What it does |
| ------------------ | -------------------------------------------------------------------------------------- |
| **Immediately** | Publishes each completed post as soon as it is ready. |
| **Smart schedule** | Starts at a selected date and publishes one post every chosen number of hours or days. |
| **Input dates** | Uses the schedule supplied by Manual Entry, CSV, or Google Sheets. |
![Publishing Schedule settings]()
Supported input date examples:
```text theme={null}
2026-05-01 09:00
2026-05-01 09:00:30
2026/05/01 09:00
05/01/2026 09:00
01/05/2026 09:00
2026-05-01T09:00:00Z
2026-05-01T09:00:00+02:00
```
Dates without a timezone are interpreted using the WordPress site timezone.
### Images
Use **Images** in a Create Content automation to configure content images, a featured image, or both. Each image type has its own **Instructions** control.
When either image type is enabled, choose **AI generated** or **Stock photos**.
| Source | Options |
| ---------------- | ----------------------------------------------------------------------------------- |
| **AI generated** | Select an image model. Available aspect ratios change with the model. |
| **Stock photos** | Select **Pexels** or **Pixabay**. Orientation and filters change with the provider. |
Content-image-only settings include **Images per article**, **Placement**, **Display size**, and **Align**. When an interval placement such as **Every X H2s** is selected, use the minus and plus controls beside **Placement** to set the interval.
Open **Advanced settings** for provider-specific controls.
![Automation image settings]()
#### OpenAI
Add the OpenAI API key in **AI Puffer > Settings > AI** and sync image models. In **Images**, enable an image type, select **AI generated**, and choose an OpenAI image model.
#### Google
Add the Google API key in **AI Puffer > Settings > AI** and sync image models. In **Images**, enable an image type, select **AI generated**, and choose a Google image model.
#### OpenRouter
Add the OpenRouter API key in **AI Puffer > Settings > AI** and sync image-capable models. If a selected model does not return images, choose another image-capable model.
#### Azure
Add the Azure endpoint, API key, API version, and image deployment in **AI Puffer > Settings > AI**. Select that deployment after choosing **AI generated**.
#### xAI
Add the xAI API key in **AI Puffer > Settings > AI** and sync image models. xAI image generation uses supported models such as `grok-imagine-image`.
#### Replicate
Add the Replicate API key in **AI Puffer > Settings > Integrations** and sync text-to-image models. Select the required model after choosing **AI generated**.
#### Pexels
Add the Pexels API key in **AI Puffer > Settings > Integrations**. In **Images**, select **Stock photos**, then select the **Pexels** provider chip. Pexels supports orientation, size, and color filters.
#### Pixabay
Add the Pixabay API key in **AI Puffer > Settings > Integrations**. In **Images**, select **Stock photos**, then select the **Pixabay** provider chip. Pixabay supports orientation, type, and category filters.
#### Provider Options
Only options supported by the selected source, provider, and model appear.
| Provider | Available options |
| -------------- | --------------------------------------------------------------------------- |
| **OpenAI** | Canvas size, quality, output format, compression, background, moderation. |
| **Azure** | Canvas size, quality, output format, compression, background. |
| **Google** | Aspect ratio, image resolution, and person generation for supported models. |
| **OpenRouter** | Aspect ratio and image resolution when supported. |
| **xAI** | Aspect ratio and image resolution. |
| **Replicate** | Model-specific options from synced model schemas. |
| **Pexels** | Orientation, size, and color. |
| **Pixabay** | Orientation, type, and category. |
AI-generated aspect-ratio choices change with the selected model. Stock-photo orientation choices change with the selected provider.
#### Image Prompts
Click **Instructions** and the pencil icon beside **Content images** or **Featured image** to customize what AI Puffer should create. The two image types keep separate instructions.
Common placeholders include `{topic}`, `{keywords}`, `{post_title}`, and `{excerpt}`.
![Image instructions]()
### Knowledge Base
Use optional **Knowledge** settings when generated or rewritten text should include information from a vector database.
1. Select a **Knowledge source**.
2. Select the provider's vector stores, index, or collection.
3. For Pinecone, Qdrant, or Chroma, select the **Embedding model** used to index the data.
4. Set **Results limit**.
5. Adjust **Confidence threshold** only when needed.
![Knowledge Base settings]()
#### OpenAI
OpenAI uses OpenAI Vector Stores. Add data in **AI Puffer > Knowledge Base > Data**, select **OpenAI** under **Knowledge source**, then select one or more **Vector stores**.
#### Pinecone
Add Pinecone credentials in **AI Puffer > Settings > Integrations**. Select the Pinecone index and the same embedding model used when the data was added.
The index dimension must match the embedding model.
#### Qdrant
Add the Qdrant URL and API key in **AI Puffer > Settings > Integrations**. Select the Qdrant collection and the same embedding model used when the data was added.
The collection vector size must match the embedding model.
#### Chroma
Add the Chroma endpoint, tenant, database, and API key in **AI Puffer > Settings > Integrations**. Select the Chroma collection and the same embedding model used when the data was added.
#### Limit and Threshold
| Setting | How it works |
| ------------------------ | ----------------------------------------------------------------------- |
| **Results limit** | Sets the maximum number of matching knowledge pieces AI Puffer can use. |
| **Confidence threshold** | Sets the minimum confidence required before a match is included. |
Use the default threshold until you have tested retrieval quality. A very high value can return few or no results. A very low value can include weak matches. AI Puffer warns when you move away from the recommended value.
For complete provider setup, see [Knowledge Base](/knowledge-base).
## Queue
The queue shows work created by saved tasks and **Run now** actions.
![Automation queue]()
| Status | Meaning |
| -------------- | ------------------------ |
| **Pending** | Waiting to be processed. |
| **Processing** | Currently being handled. |
| **Completed** | Finished successfully. |
| **Failed** | Stopped with an error. |
Click the queue menu to open **Queue tools**. Search item or task names, filter by status, or delete the currently filtered items. A failed item also has a retry action.
The **Cron** badge opens the cron status panel. Use it to check whether WordPress cron is healthy, disabled, or delayed. Click the refresh icon to reload the queue.
Deleting a task, queue item, or filtered queue set opens a destructive confirmation dialog that names what will be removed. Review it before clicking **Delete**. The action cannot be undone.
Completed content-creation items can link to the generated post when a WordPress post ID is available.
## Connected Apps
Automations can send results to Connected Apps and webhooks.
| Event | When it fires |
| --------------------- | ------------------------------------------- |
| `content.generated` | After a Create Content task creates a post. |
| `task.item_completed` | After a queue item finishes successfully. |
Use these events when another system needs the generated post, task result, or queue item details. See [Event Webhooks](/event-webhooks) for event payloads and delivery setup.
## Logs
Automation activity can appear in AI Puffer logs.
| Task area | Log module |
| --------------- | --------------------------- |
| Create Content | `content_writer_automation` |
| Comment Replies | `community_reply_comments` |
Queue status and error messages also remain visible in the Automations queue.
## Troubleshooting
1. Confirm the task status is **Active**.
2. Check **Last** and **Next** in the Tasks table.
3. Open the **Cron** status panel and confirm WordPress cron is healthy.
4. If `DISABLE_WP_CRON` is enabled, configure a server cron job.
5. Check whether the task already has pending or processing queue items.
6. Edit the task and confirm that its provider, model, source, and destination are still configured.
Create Content tasks do not queue another scheduled batch while the same task already has pending or processing items.
| Automation | Check |
| ----------------------- | ----------------------------------------------------------------------------- |
| Manual Entry | At least one Batch editor or Quick paste row must have a topic. |
| CSV | The parsed CSV must contain at least one topic. |
| RSS Feed | The feed must contain a new item that passes the filters. |
| Web Page | The URL must be reachable and contain extractable text. |
| Google Sheets | Column A must contain a topic and column G must be empty. |
| Rewrite Posts and Pages | Selected content types, categories, and authors must match published content. |
| Content Indexing | Selected content types must contain published content. |
| Comment Replies | The task must find an approved comment that passes its filters. |
1. Read the error shown for the queue item.
2. Fix the provider, model, source, prompt, or destination setting.
3. Use the retry icon on the failed item.
1. Confirm the **Sheet ID** is correct.
2. Confirm the service-account JSON file is valid.
3. Share the sheet with the service-account email as an **Editor**.
4. Put the topic in column A.
5. Leave column G empty until AI Puffer processes the row.
1. Confirm the selected store, index, or collection still exists.
2. For Pinecone, Qdrant, and Chroma, select an embedding model.
3. Confirm the destination dimension matches the embedding model.
4. Confirm the selected content types contain published content.
5. Check the provider connection in [AI Providers](/ai-providers).
1. Confirm the original comment is approved.
2. Check the selected content types.
3. Review the include and exclude keyword filters.
4. Confirm the comment was not already queued or replied to by the task.
5. Check the selected AI provider and model.
# Chatbots
Source: https://docs.aipower.org/chatbots
Create, configure, and deploy AI Puffer chatbots.
## Overview
Use Chatbots to add AI chatbots to WordPress. Each chatbot has its own model, instructions, knowledge sources, capabilities, display settings, popup settings, limits, connected apps, and rules.
If the Chatbots menu is not visible, enable **Chatbots** under **AI Puffer > Settings > Modules** and confirm that your WordPress role has access to it.
Open the frontend chatbot example.
Use popup, on-page, or external embed.
Choose the provider, model, instructions, and memory.
Use vectors, page context, and knowledge sources.
Enable file upload, web search, images, and voice.
Customize colors, popup, suggested questions, consent, and labels.
Set usage limits and credit behavior.
Send chatbot events to Slack, HubSpot, Notion, and more.
Trigger actions from chatbot events and conditions.
## Create a Chatbot
1. Go to **AI Puffer > Chatbots**.
2. Click the **+** button next to the chatbot selector.
![Create chatbot]()
3. A new bot is created immediately with the default name New Chatbot.
4. Select the chatbot from the dropdown.
5. Open **Chatbot settings > Display > Chat text** to rename it.
![Rename chatbot]()
6. Use the live preview to test the chatbot before publishing it.
Use the chatbot actions menu for saved chatbots:
| Action | What it does |
| ------------- | ----------------------------------------------------------- |
| **Duplicate** | Creates a copy of the current chatbot. |
| **Reset** | Resets the current chatbot settings. |
| **Delete** | Deletes the chatbot. The default chatbot cannot be deleted. |
![Chatbot Actions]()
## Deploy a Chatbot
Each chatbot has a shortcode. For example:
```text theme={null}
[aipkit_chatbot id=123]
```
### On-page Chatbot
1. Select the chatbot.
2. Turn **Popup** off in the preview bar.
3. Copy the shortcode from the preview bar, or open **Chatbot settings > Publish > WordPress shortcode**.
![Chatbot Onpage shortcode]()
![Chatbot Onpage shortcode]()
4. Paste it into a page, post, block, or shortcode area.
5. Publish or update the page.
![Chatbot shortcode classic editor]()
![Chatbot shortcode block]()
### Popup Chatbot
1. Select the chatbot.
2. Turn **Popup** on in the preview bar.
3. Turn **Site-wide** on if the launcher should appear across the site.
![Chatbot Popup shortcode]()
4. Configure the popup design on the main screen, or open **Chatbot settings > Display** for more popup options.
5. Save and test the site frontend.
Site-wide popup mode is global. Enabling it for one chatbot turns it off for the previous site-wide popup chatbot.
### External Embed
External Embed lets you place a chatbot on a non-WordPress site while managing it from WordPress.
1. Select the chatbot.
2. Open **Chatbot settings**.
3. Open **Publish > External embed**.
![Chatbot external snippet]()
4. Copy the embed code.
5. Add allowed websites, one URL per line.
6. Paste the embed code into the external site.
Set allowed domains before using external embed on a production site. Do not leave external embeds open to domains you do not control.
## Model and Instructions
Use the main chatbot builder to choose the chatbot model and write instructions. Open **Chatbot settings > AI behavior > Model** for response tuning.
| Setting | Use it for |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Model** | Model used by this chatbot. |
| **Instructions** | System instructions for the chatbot. Use `[date]` when the bot needs today's date in its instructions. |
| **Chatbot name** | Internal chatbot name shown in the Chatbots screen. Open **Chatbot settings > Display > Chat text** to edit it. |
| **Temperature** | Response variation. Lower values are more predictable. |
| **Context** | Maximum completion tokens for the model response. |
| **Messages** | Number of previous conversation messages included as history. |
| **Session memory** | Only applies when the chatbot uses OpenAI. AI Puffer stores the OpenAI response ID and sends it with the next message so OpenAI can continue the same conversation state. |
| **Reasoning** | Reasoning effort for supported models. Keep it set to None for faster responses; higher values can make replies slower. |
Session memory applies only to OpenAI chatbots. When enabled, conversation continuity depends on OpenAI response IDs, so review this setting before using it for privacy-sensitive chatbots.
![Chatbot model settings]()
![Chatbot model settings]()
## Knowledge
Knowledge controls the information a chatbot can use before it answers.
It can read the current page content, search trained vector data, or use both depending on the chatbot setup.
Use the main **Knowledge** card to add website content, text, Q\&A, or files for the selected chatbot. Open **Chatbot settings > Conversation > Knowledge** when you need to choose the retrieval source, vector storage, stores or collections, embedding model, **Results**, or **Minimum match**.
![Chatbot Knowledge Settings]()
### Vector
Vector is the better option when you want to train the chatbot with your own content.
AI Puffer converts your content into searchable chunks.
When a visitor asks a question, the chatbot retrieves the closest matching chunks and uses them as context for the answer.
#### OpenAI
OpenAI Vector Stores are the simplest option when the chatbot uses OpenAI.
To create a store:
1. Go to **AI Puffer > Knowledge Base > Stores**.
2. Select **OpenAI** as the provider.
3. Click **Create Store**.
![OpenAI Create Vector]()
4. Enter a store name and create it.
5. Go to **AI Puffer > Knowledge Base > Data** and add data to the store.
![OpenAI Add Data]()
To use it in a chatbot:
1. Go to **AI Puffer > Chatbots** and select the chatbot.
2. Open **Chatbot settings > Conversation > Knowledge**.
3. Turn on **Use vector search**.
4. Open the vector search settings.
5. Set **Knowledge storage** to **OpenAI**.
![Chatbot Vector OpenAI]()
6. Select one or two vector stores.
7. Save the chatbot.
#### Pinecone
Pinecone stores vectors in an index. AI Puffer creates those vectors with the embedding model you choose.
The Pinecone index dimension must match the embedding model.
For example, if your index is **3072 dimensions**, use a **3072-dimension** embedding model.
Use the same embedding model when adding data and when enabling Pinecone in the chatbot.
If the Pinecone index dimension does not match the embedding model, search can fail or return poor context.
To create an index:
1. Add your Pinecone credentials in **AI Puffer > Settings > Integrations**.
![Pinecone API key]()
2. Go to **AI Puffer > Knowledge Base > Stores**.
3. Select **Pinecone** as the provider.
4. Select the embedding model you want to use.
5. Click **Create Store**.
![Pinecone Create Index]()
6. Enter an index name and use the dimension for the selected embedding model.
7. Create the index, then add data with the same embedding model.
![Pinecone Create Index]()
To use it in a chatbot:
1. Go to **AI Puffer > Chatbots** and select the chatbot.
2. Open **Chatbot settings > Conversation > Knowledge**.
3. Turn on **Use vector search**.
4. Open the vector search settings.
5. Set **Knowledge storage** to **Pinecone**.
6. Select the Pinecone index.
7. Select the same embedding provider and model used when you added the data.
8. Save the chatbot.
![Pinecone Chatbot]()
#### Qdrant
Qdrant stores vectors in collections. AI Puffer creates those vectors with the embedding model you choose.
The Qdrant collection size must match the embedding model. For example, if your collection is **3072 dimensions**, use a **3072-dimension** embedding model.
Use the same embedding model when adding data and when enabling Qdrant in the chatbot.
If the Qdrant collection size does not match the embedding model, search can fail or return poor context.
To create a collection:
1. Add your Qdrant URL and API key in **AI Puffer > Settings > Integrations**.
![Qdrant API key]()
2. Go to **AI Puffer > Knowledge Base > Stores**.
3. Select **Qdrant** as the provider.
4. Select the embedding model you want to use.
5. Click **Create Store**.
![Qdrant Create collection]()
6. Enter a collection name and use the dimension for the selected embedding model.
7. Create the collection, then add data with the same embedding model.
![Qdrant Create collection]()
To use it in a chatbot:
1. Go to **AI Puffer > Chatbots** and select the chatbot.
2. Open **Chatbot settings > Conversation > Knowledge**.
3. Turn on **Use vector search**.
4. Open the vector search settings.
5. Set **Knowledge storage** to **Qdrant**.
6. Select one or more collections.
7. Select the same embedding provider and model used when you added the data.
8. Save the chatbot.
![Qdrant Chatbot]()
#### Chroma
Chroma stores vectors in collections. AI Puffer creates those vectors with the embedding model you choose.
Chroma collections do not require a dimension when they are created in AI Puffer, but stored vectors still need a consistent dimension.
Use the same embedding model when adding data and when enabling Chroma in the chatbot.
If the Chroma collection contains vectors from a different embedding model, search can fail or return poor context.
To create a collection:
1. Add your Chroma endpoint, tenant, database, and API key in **AI Puffer > Settings > Integrations**.
![Chroma API key]()
2. Go to **AI Puffer > Knowledge Base > Stores**.
3. Select **Chroma** as the provider.
4. Click **Create Store**.
![Chroma Create collection]()
5. Enter a collection name.
6. Create the collection, then add data with the same embedding model.
To use it in a chatbot:
1. Go to **AI Puffer > Chatbots** and select the chatbot.
2. Open **Chatbot settings > Conversation > Knowledge**.
3. Turn on **Use vector search**.
4. Open the vector search settings.
5. Set **Knowledge storage** to **Chroma**.
6. Select one or more collections.
7. Select the same embedding provider and model used when you added the data.
8. Save the chatbot.
![Chroma Chatbot]()
#### Results and Minimum Match
For OpenAI, Pinecone, Qdrant, and Chroma, use these settings to control how much vector context is added to the answer.
| Setting | How it works | Example |
| ----------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Results** | How many pieces of your content the chatbot is allowed to use for one answer. | `3` means the chatbot can use up to 3 matching pieces from your content. |
| **Minimum match** | How closely a piece of content must match the visitor’s question before the chatbot can use it. | Lower values allow looser matches. Higher values allow only stronger matches. |
![Results and Minimum Match]()
If answers miss useful context, increase **Results** or lower **Minimum match**. If answers include unrelated context, lower **Results** or raise **Minimum match**.
After testing, open **Usage > Logs** and check the Score badge in the conversation details.
Start with a small result count and a moderate minimum match. Then use the Score badge in logs to tune the chatbot with real questions.
![Score]()
Scores show which vector results matched the visitor question and help you tune the minimum match.
#### Embedding Models
Pinecone, Qdrant, and Chroma need an embedding model because AI Puffer must turn your content and the visitor question into vectors before it can search.
OpenAI Vector Stores do not need this setting in AI Puffer. OpenAI handles the vector store search on its side.
For Pinecone, Qdrant, and Chroma, use the same embedding model when adding data and when enabling the chatbot knowledge storage.
| Model | Dimension |
| ------------------------ | --------- |
| `text-embedding-3-small` | 1536 |
| `text-embedding-3-large` | 3072 |
| `text-embedding-ada-002` | 1536 |
| Model | Dimension |
| ---------------------------- | --------- |
| `gemini-embedding-2-preview` | 3072 |
| `gemini-embedding-001` | 3072 |
| `models/text-embedding-004` | 768 |
| Model | Dimension |
| -------------------------------------------------- | ----------------------------------- |
| `baai/bge-base-en-v1.5` | 768 |
| `baai/bge-large-en-v1.5` | 1024 |
| `baai/bge-m3` | 1024 |
| `google/gemini-embedding-001` | 3072 |
| `google/gemini-embedding-2-preview` | 3072 by default. Supports 128-3072. |
| `intfloat/e5-base-v2` | 768 |
| `intfloat/e5-large-v2` | 1024 |
| `intfloat/multilingual-e5-large` | 1024 |
| `mistralai/mistral-embed-2312` | 1024 |
| `nvidia/llama-nemotron-embed-vl-1b-v2:free` | 2048 |
| `openai/text-embedding-3-large` | 3072 |
| `openai/text-embedding-3-small` | 1536 |
| `openai/text-embedding-ada-002` | 1536 |
| `perplexity/pplx-embed-v1-0.6b` | 1024 |
| `perplexity/pplx-embed-v1-4b` | 2560 |
| `qwen/qwen3-embedding-4b` | 2560 |
| `qwen/qwen3-embedding-8b` | 4096 |
| `sentence-transformers/all-minilm-l12-v2` | 384 |
| `sentence-transformers/all-minilm-l6-v2` | 384 |
| `sentence-transformers/all-mpnet-base-v2` | 768 |
| `sentence-transformers/multi-qa-mpnet-base-dot-v1` | 768 |
| `sentence-transformers/paraphrase-minilm-l6-v2` | 384 |
| `thenlper/gte-base` | 768 |
| `thenlper/gte-large` | 1024 |
| Model | Dimension |
| ----------------------------------------------------- | --------- |
| `nomic-embed-text-v2-moe` | 768 |
| `qwen3-embedding` / `qwen3-embedding:8b` | 4096 |
| `qwen3-embedding:4b` | 2560 |
| `qwen3-embedding:0.6b` | 1024 |
| `embeddinggemma` | 768 |
| `nomic-embed-text` | 768 |
| `mxbai-embed-large` | 1024 |
| `bge-m3` | 1024 |
| `snowflake-arctic-embed` / `snowflake-arctic-embed:l` | 1024 |
| `snowflake-arctic-embed:m` | 768 |
| `snowflake-arctic-embed:m-long` | 768 |
| `snowflake-arctic-embed:s` | 384 |
| `snowflake-arctic-embed:xs` | 384 |
| `all-minilm` / `all-minilm:l6` | 384 |
| `all-minilm:l12` | 384 |
| `paraphrase-multilingual` | 768 |
| `snowflake-arctic-embed2` | 1024 |
| `granite-embedding:30m` | 384 |
| `granite-embedding` / `granite-embedding:278m` | 768 |
| `bge-large` | 1024 |
Azure OpenAI embedding deployments are synced from your Azure resource. Use the dimension of the model behind the deployment.
#### Add Knowledge
Use the **Knowledge** card on the chatbot screen to choose what the selected chatbot should know.
The card has two source choices:
| Source | Use it for | How it works |
| ----------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **My website** | Add published WordPress content. | **Pages** and **Posts** are selected by default. Click **Add knowledge** to add those pages and posts to the chatbot. |
| **Other sources** | Add text, Q\&A, or files. | Click the **+** button to open the source panel, then choose the content type you want to add. |
![Chatbot knowledge]()
To add website content:
1. Go to **AI Puffer > Chatbots** and select the chatbot.
2. Find the **Knowledge** card.
3. Leave **My website** selected.
4. Click **Add knowledge** to add the default **Pages** and **Posts**.
5. To change which WordPress content types are included, click the **+** button on **My website**.
6. Select or unselect content types such as pages, posts, products, or other public post types available on your site.
7. Click **Add knowledge**.
![Chatbot knowledge]()
After website knowledge exists, the status changes to **Knowledge ready** and the button changes to **Update knowledge**. Click **Update knowledge** when you want to refresh the chatbot with the latest selected website content.
To add other sources:
1. Click the **+** button on **Other sources**.
2. Choose **Text**, **Q\&A**, or **Files** from **Content type**.
3. For **Text**, paste the content the chatbot should know.
4. For **Q\&A**, enter a **Title / Question** and **Answer**. You can also add from common questions.
5. For **Files**, click **Choose files** and upload `.pdf`, `.docx`, `.txt`, `.md`, `.csv`, or `.json` files.
6. Click **Add knowledge**. For files, click **Upload** after choosing files.
![Chatbot knowledge]()
The knowledge status shows **No knowledge yet**, **Adding knowledge...**, **Knowledge ready**, or **Failed**. Click the **?** on the status pill to see knowledge details, including entries, queued items, processing items, failed items, **View knowledge**, and **Stop training** when a website update is running.
Use **Knowledge entries** on the chatbot screen, or **AI Puffer > Knowledge Base > Data**, to review and manage existing sources.
![Chatbot knowledge]()
![Chatbot knowledge]()
### Page Context
Adds the current page or post content to the chatbot context.
When this feature is enabled, the chatbot will use the current page's content as part of its contextual understanding.
If the page has an excerpt, that excerpt will be used directly as the bot’s context.
![Chatbot Knowledge Settings]()
If no excerpt is available, the plugin will automatically generate a short summary of the page content and feed that to the bot instead.
This is ideal for creating page-specific chatbots.
## Capabilities
Capabilities are optional features the chatbot can use during a conversation. They let visitors upload files, search the web, attach images, generate images, or use voice features when those options are enabled.
Enable only the capabilities you want your chatbot to offer.
![Chatbot capabilities]()
### File Upload
File upload lets visitors attach a document to the current chat. AI Puffer reads the file, prepares it for the selected vector provider, and uses the matching file content as context for the visitor's next messages.
File upload uses the chatbot's **Knowledge storage** setting: OpenAI, Pinecone, Qdrant, Chroma, or Anthropic Files when the chatbot provider is Anthropic.
Visitors can upload `.txt` and `.pdf` files. The frontend limit is **20 MB**, but your WordPress or server upload limit can be lower.
Text-based PDFs work best. Scanned PDFs may not provide usable text unless they contain OCR text.
To enable file upload:
1. Go to **AI Puffer > Chatbots** and select the chatbot.
2. Open **Chatbot settings > Conversation > Knowledge**.
3. Turn on **Use vector search**.
4. Configure the **Knowledge storage** settings.
![Chatbot Vector OpenAI]()
5. Open **Chatbot settings > Conversation > Capabilities**.
6. Turn on **File upload**.
7. Save the chatbot.
![Chatbot File Upload]()
8. Test the chatbot on the frontend and upload a `.txt` or `.pdf` file.
![Chatbot File Upload Demo]()
### Web Search
Web Search lets a chatbot use online sources while answering. When enabled, the chatbot input shows a web/search toggle on the frontend.
If the frontend toggle is off, the chatbot answers without web search even when the capability is enabled in the admin.
Web Search is available for OpenAI, Google, Anthropic, OpenRouter, and xAI models that support web search.
Web search has two controls: the admin capability setting enables the feature, and the frontend toggle decides whether a specific visitor message uses it.
To enable web search:
1. Go to **AI Puffer > Chatbots** and select the chatbot.
2. Choose an **OpenAI**, **Google**, **Anthropic**, **OpenRouter**, or **xAI** model.
3. Open **Chatbot settings > Conversation > Capabilities**.
4. Turn on **Web search**.
5. Open the web search settings.
![Chatbot Web]()
6. Configure the provider settings.
7. Save the chatbot.
8. Test the chatbot on the frontend.
![Chatbot We Demo]()
These options appear for every web search provider:
| Option | What it does |
| ------------------------- | ---------------------------------------------------------------------- |
| **Web toggle default on** | Starts the frontend web/search toggle enabled. |
| **Show sources** | Shows source links under replies when the provider returns them. |
| **Sources label** | Changes the label shown above source links. |
| **Searching web text** | Changes the temporary status text shown while a web search is running. |
Provider-specific options are shown based on the chatbot engine.
xAI uses the shared web search options above and does not add provider-specific web settings.
| Option | What it does |
| ----------------------- | ---------------------------------------------------------- |
| **Search context size** | Controls how much web-search context OpenAI can use. |
| **User location** | Sends approximate location only when local results matter. |
| Option | What it does |
| ----------------------- | ------------------------------------------------------------- |
| **Mode** | Controls Gemini grounding mode. |
| **Retrieval threshold** | Applies only to Dynamic mode. Lower values search more often. |
| Option | What it does |
| ------------------- | --------------------------------------------------------------- |
| **Max uses** | Limits web searches per answer. |
| **User location** | Sends approximate country, city, region, or timezone. |
| **Allowed domains** | Restricts web search to specific domains. |
| **Blocked domains** | Excludes specific domains. |
| **Cache TTL** | Sets optional Anthropic cache time: None, 5 minutes, or 1 hour. |
| Option | What it does |
| ----------------- | --------------------------------------------------- |
| **Engine** | Chooses Auto, Native, or Exa search when supported. |
| **Max results** | Limits search results from 1 to 10. |
| **Search prompt** | Adds search-specific instructions. |
### Images and Vision
Image capabilities cover two separate features:
* **Image analysis** sends an uploaded image to the chatbot model so it can answer questions about the image.
* **Image generation** creates a new image when the visitor types a configured image command.
#### Image Analysis
Image analysis lets visitors attach an image to a chat message. The image is sent with the next message to the chatbot's selected model.
Image analysis uses the chatbot's selected provider and model.
Image analysis is model-dependent. If the option is missing or replies fail, choose a vision-capable model and sync models again.
| Provider | Support | Notes |
| -------------- | --------------- | --------------------------------------------------------------------------------------- |
| **OpenAI** | Yes | Uses the selected OpenAI chat model. |
| **Anthropic** | Yes | Uses the selected Claude chat model. |
| **xAI** | Yes | Uses a selected Grok model that supports image input. |
| **OpenRouter** | Model-dependent | The selected model must support image input. Sync models if the option does not appear. |
| **Ollama** | Model-dependent | The selected local model must be vision-capable. Sync Ollama models first. |
| **Google** | No | Chatbot image analysis is not exposed for Google. |
| **Azure** | No | Chatbot image analysis is not exposed for Azure. |
| **DeepSeek** | No | Chatbot image analysis is not exposed for DeepSeek. |
Visitors can upload one image per message, with a **20 MB** frontend limit. xAI image analysis accepts JPG/JPEG and PNG files. Other supported providers can also accept WEBP when their model supports it.
To enable image analysis:
1. Go to **AI Puffer > Chatbots** and select the chatbot.
2. Select a supported provider and model.
3. Open **Chatbot settings > Conversation > Capabilities**.
4. Turn on **Image analysis**.
![Chatbot Image Analysis]()
5. Save the chatbot.
6. Test the chatbot on the frontend.
![Chatbot Image Analysis Demo]()
On the frontend, visitors use the image upload button, select an image, type a question, and send the message.
If File Upload and Image Analysis are both enabled, the attachment button opens a small menu.
#### Image Generation
Image generation lets visitors create a new image from a chat command. The visitor types a trigger followed by a prompt, for example:
```text theme={null}
/image a clean product photo on a white background
```
Each command returns one image.
Image generation uses a separate image model. It does not use the chatbot's answer model.
Image generation uses the image model selected in **Capabilities**, not the chatbot answer model.
| Provider | Support | Model source |
| -------------- | --------------- | -------------------------------------------------------------------------------- |
| **OpenAI** | Yes | Built-in GPT Image models. |
| **Google** | Yes | Synced Google image models. |
| **Azure** | Yes | Synced Azure image deployments. |
| **OpenRouter** | Model-dependent | Synced OpenRouter models with image output. |
| **xAI** | Yes | Synced xAI image models such as `grok-imagine-image`. |
| **Replicate** | Yes | Add the API key under **Settings > Integrations > Replicate**, then sync models. |
The chatbot image generation model list includes those image providers only.
If a model is missing, configure the provider and sync models in [AI Providers](/ai-providers).
To enable image generation:
1. Go to **AI Puffer > Chatbots** and select the chatbot.
2. Open **Chatbot settings > Conversation > Capabilities**.
3. Turn on **Image generation**.
4. Open the image generation settings.
5. Select the image model.
6. Set the image triggers.
7. Save the chatbot.
8. Test the command on the frontend.
Triggers are comma-separated and must start with `/`. Examples:
```text theme={null}
/image, /generate, /draw
```
![Chatbot Image Generation]()
When a visitor uses an image trigger, AI Puffer extracts the prompt after the trigger and sends it to the selected image model. The original command is saved in the conversation log, and the generated image reply is shown in the chat.
![Chatbot Image Generation Demo]()
### Audio and Speech
Audio and speech capabilities are configured per chatbot under **Chatbot settings > Conversation > Capabilities**.
| Capability | What it does |
| ------------------ | ---------------------------------------------------------------------------------- |
| **Speech to Text** | Records visitor speech, transcribes it, and sends the text as the chat message. |
| **Text to Speech** | Adds a play button to assistant replies. Auto play can read replies automatically. |
| **Realtime Voice** | Starts a live voice session with OpenAI Realtime. |
#### Speech to Text
Speech to Text adds a microphone button to the chatbot input.
When a visitor clicks the microphone, AI Puffer records the audio in the browser, uploads it to WordPress, sends it to the speech-to-text provider, then submits the transcript as the user message.
Speech to Text is currently available for OpenAI.
| Provider | Speech to Text model |
| ---------- | -------------------- |
| **OpenAI** | `whisper-1` |
To enable speech to text:
1. Configure OpenAI in [AI Providers](/ai-providers).
2. Go to **AI Puffer > Chatbots** and select the chatbot.
3. Open **Chatbot settings > Conversation > Capabilities**.
4. Turn on **Speech to text**.
![Chatbot Speech to Text]()
5. Select the model if the model selector is shown.
6. Save the chatbot and test the microphone on the frontend.
Speech to Text needs browser microphone permission and HTTPS. Localhost can be used for testing without HTTPS. Recorded audio uploads are limited to **4 MB** by default.
![Chatbot Speech to Text Demo]()
#### Text to Speech
Text to Speech adds playback controls for assistant replies.
When a visitor clicks the play button, AI Puffer sends the assistant reply text to the selected text-to-speech provider and plays the returned audio in the browser.
Text to Speech is available for Google, OpenAI, and ElevenLabs.
| Provider | Text to Speech models |
| -------------- | ----------------------------------------------------------------------------- |
| **OpenAI** | `tts-1`, `tts-1-hd` |
| **ElevenLabs** | `eleven_v3`, `eleven_multilingual_v2`, `eleven_flash_v2_5`, `eleven_flash_v2` |
| **Google** | Uses synced Google voices. |
To enable text to speech:
1. Go to **AI Puffer > Chatbots** and select the chatbot.
2. Open **Chatbot settings > Conversation > Capabilities**.
3. Turn on **Text to speech**.
4. Open the text-to-speech settings.
5. Select the provider.
6. Select the voice and model fields shown for that provider.
7. Enable **Auto play** only if replies should play automatically.
8. Save the chatbot and test the play button on an assistant reply.
![Chatbot Text to Speech]()
ElevenLabs voices and models appear only after the ElevenLabs API key is saved under **Settings > Integrations**.
![ElevenLabs API key]()
#### Realtime Voice Agents
Realtime Voice is separate from Speech to Text and Text to Speech. It creates a live WebRTC session with OpenAI Realtime, streams microphone audio, receives spoken replies, and logs completed turns.
Realtime Voice is currently available for OpenAI.
| Provider | Realtime models |
| ---------- | ------------------------------------------------- |
| **OpenAI** | `gpt-4o-realtime-preview`, `gpt-4o-mini-realtime` |
To enable realtime voice:
1. Configure OpenAI in [AI Providers](/ai-providers).
2. Go to **AI Puffer > Chatbots** and select the chatbot.
3. Open **Chatbot settings > Conversation > Capabilities**.
4. Turn on **Realtime voice**.
5. Open the realtime voice settings.
6. Select the realtime model.
7. Select the voice.
8. Choose turn detection.
9. Save the chatbot and test voice mode on the frontend.
![Realtime Voice]()
Realtime options:
| Setting | What it does |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Model** | OpenAI Realtime model used for the voice session. |
| **Voice** | Voice used for spoken replies. |
| **Direct voice mode** | Popup-only. The popup launcher starts and stops the voice session directly, and the in-chat realtime button is hidden. |
| **Noise reduction** | Applies input audio noise reduction before the model receives the microphone stream. |
| **Audio format** | Sets the input and output audio format. Available values are `pcm16`, `g711_ulaw`, and `g711_alaw`. |
| **Response speed** | Controls spoken reply speed from `0.25` to `1.5`. |
Turn detection options:
| Mode | Behavior |
| ------------- | ---------------------------------------------------------------------------------------------------------- |
| **None** | No server voice activity detection. Use this for push-to-talk style sessions. |
| **Automatic** | Uses server voice activity detection. This is the default. |
| **Smart** | Uses semantic voice activity detection, so the model can wait for a more complete thought before replying. |
Realtime sessions create chat log entries for the user transcript and assistant transcript when a turn completes. If OpenAI returns usage data, AI Puffer records the token usage against the chatbot.
Realtime Voice uses microphone access and an OpenAI Realtime model. Test it on HTTPS and review costs in your OpenAI account.
## Display
Use the main chatbot screen for quick visual changes such as chat photo, welcome message, widget colors, and launcher icon. Open **Chatbot settings > Display** for chat text, launcher behavior, welcome-message timing, and publish options.
![Chatbot display settings]()
### Widget Colors
Choose a color preset from **Widget colors** on the main chatbot screen.
To build your own theme, choose the custom option and open the custom editor. The editor lets you change the main colors, bubble radius, font, inline width, popup width, chat height, and advanced colors for messages, header, footer, input area, buttons, and sidebar. Use **Reset** to return the custom theme fields to their defaults.
![Chatbot Theme]()
### Popup
Popup mode adds a launcher button to the page. When the visitor clicks it, the chatbot opens in a floating chat window.
To configure a popup:
1. Go to **AI Puffer > Chatbots** and select the chatbot.
2. Turn on **Popup** in the preview bar.
3. Turn on **Site-wide** if the launcher should appear across the site.
4. Use the main screen to set the chat photo, welcome message, widget colors, and launcher icon.
5. Open **Chatbot settings > Display**.
6. Configure **Launcher** and **Welcome message** options.
7. Save the chatbot and test it on the frontend.
![Chatbot popup settings]()
| Setting | Use it for |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Position** | Place the launcher in a page corner. Options are bottom right, bottom left, top right, and top left. |
| **Icon style** | Set the launcher icon style to circle, square, or original. |
| **Size** | Set the launcher size to small, medium, large, or x-large. |
| **Auto-open** | Open the popup automatically after a delay, or keep it off. |
| **Welcome message** | Show a short message near the launcher. Set the text on the main screen and timing, size, frequency, desktop/mobile visibility, and dismiss behavior in **Chatbot settings > Display > Welcome message**. |
| **Online text** | Set the status text shown in the chatbot header. |
| **Launcher icon** | Choose a built-in launcher icon or upload a custom icon. |
| **Chat photo** | Choose a built-in header avatar or upload a custom image. |
![Chatbot popup settings]()
![Chatbot popup settings]()
### Chat Options
Open **Chatbot settings > Conversation > Chat options** to choose which controls appear in the chatbot.
| Setting | Use it for |
| ----------------------- | ---------------------------------------------------------------------------------- |
| **Download** | Let visitors download chatbot transcripts as TXT or PDF. |
| **Consent** | Require visitors to accept a notice before they can start chatting. |
| **Fullscreen** | Show the fullscreen button. |
| **Sidebar** | Show conversation history for on-page chatbots. Sidebar is disabled in popup mode. |
| **Suggested questions** | Show first questions visitors can tap before sending their own message. |
![Chatbot UI features]()
#### Suggested Questions
Suggested questions are quick prompts shown inside the chatbot before the first message. Use them to help visitors begin with common questions.
To enable and customize suggested questions:
1. Go to **AI Puffer > Chatbots** and select the chatbot.
2. Open **Chatbot settings > Conversation > Chat options**.
3. Enable **Suggested questions**.
4. Click the **+** settings button for **Suggested questions**.
5. In **Conversation starters (max 6)**, add one question per line.
6. Keep the list to 6 questions or fewer.
7. Save the chatbot.
![Chatbot suggested questions]()
#### Consent Notice
Consent shows a notice before the conversation starts. The chatbot input stays disabled until the visitor clicks the consent button.
To enable and customize the consent notice:
1. Go to **AI Puffer > Chatbots** and select the chatbot.
2. Open **Chatbot settings > Conversation > Chat options**.
3. Enable **Consent**.
4. Open the consent editor.
5. Set the **Title**.
6. Set the **Button label**.
7. Write the **Message**.
8. Save the chatbot.
![Chatbot Consent]()
### Text Labels
Open **Chatbot settings > Display > Chat text** to change the words visitors see in the chatbot.
| Setting | Use it for |
| --------------- | ------------------------------------------------------ |
| **Greeting** | Main greeting text. |
| **Subgreeting** | Secondary greeting text. |
| **Placeholder** | Input field placeholder. |
| **Footer** | Footer text below the chatbot input. |
| **Typing text** | Text shown while the chatbot is generating. |
| **Status text** | Text shown while knowledge context is being retrieved. |
## Security and Privacy
Chatbots use both global security settings and chatbot-level controls.
Open **AI Puffer > Settings > Security**.
| Setting | What it does |
| -------------------- | --------------------------------------------------------- |
| **IP Anonymization** | Stores anonymized IP addresses in logs. |
| **Banned Words** | Blocks messages that contain configured words or phrases. |
| **Banned IPs** | Blocks messages from configured IP addresses. |
Set custom block messages for banned words and banned IPs if you want visitors to see specific text.
Chatbot logs include conversation messages, usage data, feedback, and metadata needed for history and reporting. Enable IP anonymization if you do not want full IP addresses stored in logs.
Use IP anonymization when you need usage logs without storing full visitor IP addresses.
OpenAI moderation is configured from the OpenAI provider settings.
1. Open **AI Puffer > Settings > AI**.
2. Select **OpenAI**.
3. Open **Advanced**.
4. Set **Moderation** to **Yes**.
5. Set **Moderation Message** if you want a custom message when input is blocked.
Moderation applies to chatbot requests that use OpenAI. If the chatbot uses another provider, this setting is skipped.
## Limits
Limits control how much a visitor can use this chatbot before AI Puffer stops new messages.
AI Puffer checks the visitor's quota before a chat request starts and records usage after the response. Guests are tracked by session. Logged-in users are tracked on their WordPress account. Leave a quota empty for unlimited usage, or set it to `0` to block that group.
Open **Chatbot settings > AI behavior > Limits** to configure chatbot quota controls.
| Setting | Use it for |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Quota mode** | Use the same quota for all logged-in users or define role-based quotas. |
| **Guest quota** | Usage quota for visitors who are not logged in. Empty means unlimited. `0` blocks guests. |
| **User quota** | Usage quota for logged-in users when using general quota mode. Empty means unlimited. `0` blocks logged-in users. |
| **Role-based quotas** | Usage quota per WordPress role. Empty means unlimited for that role. |
| **Reset period** | Never, daily, weekly, or monthly. |
| **Quota reached message** | Message shown when the visitor reaches the quota. |
| **Primary button** | Optional button shown after the quota message. |
| **Secondary button** | Optional second button shown after the quota message. |
Quota buttons can link to customer dashboard usage, credits, purchases, the buy credits page, a custom URL, or no button.
For credit-based chatbot access, define pricing rules in [Usage](/usage#pricing-rules). To sell prepaid credits, create WooCommerce credit packages in [Usage](/usage#woocommerce-credit-packages).
![Chatbot Limits]()
## Connected Apps
Use Connected Apps to send chatbot events to external apps.
Connected Apps has two parts: a **connection** stores the app credentials, and a **recipe** decides which chatbot event is sent to that app.
Connected app recipes can send chatbot data to external services. Map only the fields that the destination app needs.
Chatbot recipes can run on these events:
| Event | When it runs |
| ------------------------------- | ----------------------------------------------------- |
| **Chat Session Started** | The first user message starts a new chat session. |
| **Chat User Message Submitted** | A visitor sends a message. |
| **Chat Response Generated** | The chatbot finishes an answer. |
| **Chat Feedback Submitted** | A visitor submits feedback. |
| **Chatbot Form Submitted** | A visitor submits a form displayed by a chatbot rule. |
Use **Chatbot Form Submitted** for forms created with a chatbot rule's **Display form** action. Use **AI Form Submitted** only for standalone AI Forms from the AI Forms module.
Open **AI Puffer > Settings > Apps** to create connections and recipes.
![Chatbot Connected Apps]()
Open **Chatbot settings > Automations > Apps** to review the recipes attached to the current chatbot.
![Chatbot Connected Apps]()
Failed deliveries appear under **Settings > Apps > Delivery Issues**, where you can retry or clear them.
### Slack
Use Slack to send chatbot messages, responses, feedback, or session alerts to a channel.
1. Go to [https://api.slack.com/apps](https://api.slack.com/apps).
2. Click **Create New App**.
3. Choose **From scratch**.
4. Enter an app name and select the workspace.
5. Click **Create App**.
6. Choose one connection method:
* **Bot token**: open **OAuth & Permissions**, scroll to **Bot Token Scopes**, click **Add an OAuth Scope**, add `chat:write`, click **Install to Workspace**, then copy the **Bot User OAuth Token** that starts with `xoxb-`.
* **Incoming webhook**: open **Incoming Webhooks**, turn on **Activate Incoming Webhooks**, click **Add New Webhook to Workspace**, select a channel, then copy the webhook URL.
7. If you use a bot token, invite the Slack app to the target channel.
8. In WordPress, open **AI Puffer > Settings > Apps**.
9. Create a **Slack** connection.
10. Select **Token** or **Webhook**.
11. For **Token**, enter the **Bot Token** and **Default Channel**.
12. For **Webhook**, enter the **Webhook URL**.
13. Save the connection.
14. For token connections, click **Test Connection**. AI Puffer posts a temporary Slack message and removes it after the channel is verified.
15. Create a recipe, choose a chatbot event, choose **Slack Message**, map the fields, and enable it.
16. Scope the recipe to all chatbots or one chatbot.
17. Test from the frontend chatbot.
Webhook connections are tested at delivery time. If a token test fails, check that the bot is in the default channel.
![Chatbot Slack]()
![Chatbot Slack Recipe]()
### HubSpot
Use HubSpot to create or update contacts from chatbot events when your recipe maps an email address.
1. Go to [https://app.hubspot.com](https://app.hubspot.com) and select your HubSpot account.
2. Open **Development > Legacy apps**.
3. Click **Create private app**.
4. Enter an app name.
5. Open **Scopes**.
6. Add `crm.objects.contacts.read` and `crm.objects.contacts.write`.
7. Create the app.
8. Open the app's **Auth** tab and copy the private app access token.
9. In WordPress, open **AI Puffer > Settings > Apps**.
10. Create a **HubSpot** connection.
11. Enter the **Private App Token**.
12. Add the **Portal ID** if you want it stored with the connection.
13. Save the connection.
14. Click **Test Connection**.
15. Create a recipe, choose a chatbot event, choose **HubSpot Contact**, map **Email**, and map any other contact fields you need.
16. Enable the recipe and test from the frontend chatbot.
HubSpot contact recipes require an email mapping.
For lead forms shown inside the chatbot by a rule, choose the **Chatbot Form Submitted** event. Common mappings are:
| HubSpot field | Source path |
| ------------- | ------------------------ |
| Email | `data.inputs.email` |
| First name | `data.inputs.first_name` |
| Last name | `data.inputs.last_name` |
| Phone | `data.inputs.phone` |
| Company | `data.inputs.company` |
| Note | `data.summary` |
![Chatbot HubSpot]()
### Notion
Use Notion to create pages or database items from chatbot events.
1. Go to [https://www.notion.com/my-integrations](https://www.notion.com/my-integrations).
2. Click **New integration** or **Create a new integration**.
3. Select the workspace and enter an integration name.
4. Open the integration's **Configuration** tab.
5. Copy the **Internal Integration Secret**.
6. In Notion, open the page or database AI Puffer should write to.
7. Click the **...** menu in the top-right corner.
8. Select **Connections**.
9. Click **+ Add connection**.
10. Search for your integration and select it.
11. Confirm access.
12. Copy the parent page ID or database ID from the Notion URL.
13. In WordPress, open **AI Puffer > Settings > Apps**.
14. Create a **Notion** connection.
15. Enter the **Integration Token**.
16. Enter **Parent Page ID** for page recipes, or **Database ID** for database item recipes.
17. Save the connection.
18. Click **Test Connection**.
19. Create a recipe, choose a chatbot event, choose **Notion Page** or **Notion Database Item**, map the fields, and enable it.
20. Test from the frontend chatbot.
The connection test checks the token. If delivery fails, confirm the target page or database is shared with the Notion integration.
![Chatbot Notion]()
### Pipedrive
Use Pipedrive to create or update people from chatbot events when your recipe maps a name.
1. Go to [https://app.pipedrive.com](https://app.pipedrive.com).
2. Open your account menu in the top-right corner.
3. Open **Personal preferences**.
4. Open the **API** tab.
5. Copy your personal API token.
6. Copy your company domain from the browser address. For `https://example.pipedrive.com`, the company domain is `example`.
7. In WordPress, open **AI Puffer > Settings > Apps**.
8. Create a **Pipedrive** connection.
9. Enter the **API Token** and **Company Domain**.
10. Add **Default Owner ID** or **Pipeline ID** if your workflow needs them.
11. Save the connection.
12. Click **Test Connection**.
13. Create a recipe, choose a chatbot event, choose **Pipedrive Person**, map **Name**, and map any other fields you need.
14. Enable the recipe and test from the frontend chatbot.
Pipedrive person recipes require a name mapping. If an email is mapped, AI Puffer looks for an existing person before creating a new one.
![Chatbot Pipedrive]()
### Zapier
Use Zapier when you want to send chatbot event data into a Zap.
1. Go to [https://zapier.com/app/editor](https://zapier.com/app/editor).
2. Click the **Trigger** step.
3. Search for **Webhooks by Zapier**.
4. Select **Webhooks by Zapier**.
5. Set **Event** to **Catch Hook**.
6. Click **Continue**.
7. In the **Test** tab, click **Copy** to copy the webhook URL.
8. In WordPress, open **AI Puffer > Settings > Apps**.
9. Create a **Zapier** connection.
10. Enter the **Webhook URL**.
11. Add a **Zap Name** if you want a label for the connection.
12. Save the connection.
13. Create a recipe, choose a chatbot event, choose **Zapier Webhook**, map the fields, and enable it.
14. In Zapier, keep the Zap ready to receive a test request.
15. Test from the frontend chatbot and confirm the request appears in Zapier.
Zapier connections are verified when AI Puffer sends the first event.
![Chatbot Zapier]()
### Make
Use Make when you want chatbot events to start a Make scenario.
1. Go to [https://www.make.com/en/login](https://www.make.com/en/login) and open Make.
2. Create a new scenario.
3. Click the large **+** button.
4. Search for **Webhooks**.
5. Select **Webhooks > Custom webhook**.
6. Click **Create a webhook**.
7. Name the webhook and save it.
8. Copy the generated webhook URL.
9. In WordPress, open **AI Puffer > Settings > Apps**.
10. Create a **Make** connection.
11. Enter the **Webhook URL**.
12. Add a **Scenario Name** if you want a label for the connection.
13. Save the connection.
14. Create a recipe, choose a chatbot event, choose **Make Webhook**, map the fields, and enable it.
15. In Make, click **Run once** so the scenario can receive a test request.
16. Test from the frontend chatbot and check the Make scenario history.
Make connections are verified when AI Puffer sends the first event.
![Chatbot Make]()
### n8n
Use n8n when you want chatbot events to start an n8n workflow.
1. Go to [https://app.n8n.cloud](https://app.n8n.cloud) or open your self-hosted n8n URL.
2. Create a new workflow.
3. Add a **Webhook** node.
4. Set **HTTP Method** to **POST**.
5. Copy the **Test URL** if you are testing, or the **Production URL** if the workflow is active.
6. In WordPress, open **AI Puffer > Settings > Apps**.
7. Create an **n8n** connection.
8. Enter the **Webhook URL**.
9. Add a **Workflow Name** if you want a label for the connection.
10. Save the connection.
11. Create a recipe, choose a chatbot event, choose **n8n Webhook**, map the fields, and enable it.
12. In n8n, click **Listen for test event** if you used the Test URL, or activate the workflow if you used the Production URL.
13. Test from the frontend chatbot and check the n8n execution log.
n8n connections are verified when AI Puffer sends the first event.
![Chatbot n8n]()
## Rules
Rules run inside a chatbot and can react to chatbot events. A rule runs when its event fires, all of its conditions pass, and its action executes. Lower priority numbers run first.
Open **Chatbot settings > Automations > Rules**, then click **Manage rules** to create or edit chatbot rules.
### Rule Events
| Event | When it runs |
| ------------------------- | --------------------------------------------------------- |
| **Session started** | A new chatbot session starts with the first user message. |
| **User message received** | A visitor sends a message before AI processing. |
| **System error occurred** | An internal processing error occurs. |
| **Form submitted** | A form displayed by a rule is submitted. |
### Conditions
Rules can check fields from:
| Condition group | Example fields |
| ---------------------- | --------------------------------------------------------------------------------------------- |
| **User context** | Logged-in status, user role, user message text. |
| **Text content** | User message text. |
| **Conversation state** | Message count. |
| **AI model context** | Current provider and model. |
| **HTTP context** | Referrer and user agent. |
| **Post context** | Post ID, title, and tags. |
| **Error context** | Error code, error message, failed provider, failed model, status code, operation, and module. |
Available operators include equals, contains, starts with, ends with, regex match, empty checks, one-of checks, and numeric comparisons.
Conditions inside one rule use **AND** logic. To run the same action when either of two different conditions is true, create two rules with the same action.
### Actions
| Action | What it does |
| ------------------------- | --------------------------------------------------------------- |
| **Bot reply** | Sends a predefined bot message. |
| **Inject context** | Adds content to the system instruction or conversation history. |
| **Block message** | Stops the user message from reaching the AI. |
| **Call webhook** | Sends an HTTP request to an external URL. |
| **Set variable** | Stores a variable in user meta or bot context. |
| **Display form** | Shows a form inside the chatbot. |
| **Store form submission** | Saves submitted form data to the chatbot log. |
Webhook and message fields support placeholders. Form placeholders include submitted data, display values, labels, and individual submitted fields.
Webhook actions send data outside WordPress. Use trusted webhook URLs and avoid sending sensitive conversation data unless the destination is meant to receive it.
![Chatbot Rules]()
### Example
#### Lead Collection
Use **Display form** when the chatbot should ask for contact details inside the conversation. The form is rendered in the chat, and AI processing pauses for that message while the visitor completes it.
If the form was displayed from a **User Message Received** rule, AI Puffer automatically continues the AI response after a successful form submission. It uses the captured user message, adds the submitted form data as context, and avoids resuming when a form-submission rule already returned a direct bot reply.
Show the form when the visitor uses a lead keyword:
1. Add a rule named **Lead form**.
![Chatbot Rules]()
2. Set **Event** to **User Message Received**.
![Chatbot Rules]()
3. Add this condition:
| Type | Field | Operator | Value |
| ---------------- | --------------------- | ------------ | --------- |
| **Text Content** | **User Message Text** | **Contains** | `pricing` |
![Chatbot Rules]()
4. Set **Action Type** to **Display Form**.
5. Add the form title, such as `Request a quote`.
![Chatbot Rules]()
6. Add these form elements:
| Element | Field ID | Setup |
| -------------- | --------- | --------------------------------------------------------------- |
| **Text Input** | `name` | Label: `Name`; required. |
| **Text Input** | `email` | Label: `Email`; required. |
| **Dropdown** | `budget` | Options such as `Under $1,000`, `$1,000-$5,000`, and `$5,000+`. |
| **Textarea** | `message` | Label: `What do you need help with?` |
![Chatbot Rules]()
7. Set **Submit Button Text** to `Send request`.
To save the submitted lead in the chatbot log, add a second rule:
1. Add a rule named **Store lead form submission**.
2. Set **Event** to **Form Submitted**.
3. Leave conditions empty if this chatbot only displays one rule form.
4. Set **Action Type** to **Store Form Submission**.
5. Use this **Log Message Format**:
```text theme={null}
Lead form submitted by {{user_name}}. Summary: {{form_submission_summary}}
```
![Chatbot Rules]()
Make sure the **Active** checkbox is checked on both rules.
![Chatbot Rules]()
Now ask your bot something about pricing and you will see the form. After the form is submitted, the chatbot continues answering the original pricing question and you can view the submitted details under **Usage > Logs**.
To send the same rule form submission to HubSpot, create a Connected Apps recipe that uses **Chatbot Form Submitted** and maps fields such as `data.inputs.email`, `data.inputs.first_name`, `data.inputs.last_name`, `data.inputs.phone`, and `data.inputs.company`.
![Chatbot Rules]()
![Chatbot Rules]()
# Content Writer
Source: https://docs.aipower.org/content-writer
Generate, update, and schedule WordPress content with AI Puffer.
## Overview
Content Writer creates WordPress content from topics, CSV files, RSS feeds, web pages, and Google Sheets. It can also update existing posts, image metadata, and WooCommerce product copy.
To start using Content Writer, open WordPress Admin and go to **AI Puffer > Content Writer**.
Generate posts from topics, CSV, RSS, URLs, and Sheets.
Rewrite posts, update image metadata, and edit products.
Save reusable writer settings.
Choose the provider, model, and generation settings.
Customize instructions for each generated output.
Generate metadata and improve SEO scores.
Set post type, status, author, taxonomy, and schedule.
Generate or search images for content.
Use vector data while generating content.
Review generated content activity.
## Create Content
To create new content, first choose where the input comes from.
You can type topics manually, upload a CSV, use RSS feed items, extract text from web pages, or read rows from Google Sheets.
Manual Entry is for topics you type directly into Content Writer.
Choose **Single**, **Batch Editor**, or **Quick Paste**, then use the right panel to select the model, edit prompts, set publishing options, add images, and enable SEO.
Set up at least one AI provider before using Content Writer. If the model list is empty, configure and sync a provider in [AI Providers](/ai-providers).
### Single Entry
Single Entry is for one content item.
1. Select **Manual Entry**.
2. Select **Single**.
3. Enter the topic.
4. Add keywords if needed.
5. Choose the provider, model, and content length.
6. In the right-side **General** card, click **Customize** next to **Prompts** if you want to edit the instructions.
7. Set the post type, status, author, categories, table of contents, and URL option.
8. Click **Generate**.
9. Review the output.
10. Save it as a WordPress post when ready.
![Content Writer Single Entry]()
### Batch Editor
Batch Editor is a row-based queue. Each row creates one content item.
The main row fields are **Topic** and **Keywords**. Click the row settings icon to set **Category**, **Author**, **Post Type**, and **Schedule** for that row.
1. Select **Manual Entry**.
2. Select **Batch Editor**.
3. Add one topic per row.
4. Add keywords or row settings where needed.
5. Choose the shared model, prompts, publishing, image, and SEO settings.
6. If row schedules should be used, set publishing to **Publish** and select **Use Dates from Input**.
7. Click **Generate** or **Create Task**.
![Content Writer Batch Editor]()
### Quick Paste
Quick Paste is for adding many rows at once. Each line becomes one Batch Editor row.
Only the topic is required. Optional fields can be added with a pipe character.
Quick Paste format:
```text theme={null}
Topic | Keywords | Category ID | Author Login | Post Type | YYYY-MM-DD HH:MM
```
Example:
```text theme={null}
How to clean leather boots | leather care, boots | 12 | editor | post | 2026-05-01 09:00
```
You can also enter only a topic:
```text theme={null}
How to clean leather boots
```
To use Quick Paste:
1. Select **Manual Entry**.
2. Select **Quick Paste**.
3. Paste one topic per line.
4. Switch to **Batch Editor** if you want to review or edit the rows.
5. Choose the shared model, prompts, publishing, image, and SEO settings.
6. If lines include schedule dates, set publishing to **Publish** and select **Use Dates from Input**.
7. Click **Generate** or **Create Task**.
![Content Writer Quick Paste]()
### CSV
CSV import reads every non-empty row and converts it into a generation task.
[Download sample CSV](https://docs.google.com/spreadsheets/d/1WOnO_UKkbRCoyjRxQnDDTy0i-RsnrY_MDKD3Ks09JJk/export?format=csv\&gid=0)
1. Select **Import CSV**.
2. Upload a `.csv` file.
3. Confirm the number of tasks found.
4. Set model, prompts, publishing, and other options.
5. Click **Generate** or **Create Task**.
CSV columns are read in this order:
| Column | Field | Required |
| ------ | ------------ | -------- |
| 1 | Topic | Yes |
| 2 | Keywords | No |
| 3 | Category ID | No |
| 4 | Author Login | No |
| 5 | Post Type | No |
| 6 | Schedule | No |
Do not add a header row unless you want the header row to be treated as a topic.
![Content Writer CSV]()
### RSS Feed
Use RSS Feed to generate content from feed items.
1. Select **RSS Feed**.
2. Add one feed URL per line.
3. Add **Include** keywords if only matching titles should be used.
4. Add **Exclude** keywords if matching titles should be skipped.
5. Click **Fetch Feeds** to preview available items.
6. Click **Generate** or **Create Task**.
![Content Writer RSS]()
Our plugin checks up to 15 items per feed. Automated RSS tasks keep a history of processed feed items so the same item is not queued again.
### Web Page
Use Web Page to generate content from a list of URLs.
1. Select **Web Page**.
2. Add one URL per line.
3. Click **Test First URL** to preview extracted text.
4. Set prompts and publishing options.
5. Click **Generate** or **Create Task**.
![Content Writer URL]()
When using Web Page mode, prompts can use:
| Placeholder | Value |
| --------------- | -------------------- |
| `{url_content}` | Extracted page text. |
| `{source_url}` | Source URL. |
Some pages block extraction or return very little readable text. Use **Test First URL** before creating a large task.
### Google Sheets
Use Google Sheets when your content inputs are managed in a spreadsheet.
[Open the sample Google Sheet](https://docs.google.com/spreadsheets/d/18QIWggMmbTVTb-nztTo7SFdGJTUC6kwRxgc841xq4x0/edit?gid=0#gid=0), make a copy, and keep the same column order.
![Copy the sample Google Sheet]()
AI Puffer reads columns `A:G`.
| Column | Field | Notes |
| ------ | ------------- | ---------------------------------------------- |
| A | Topic | Required. |
| B | Keywords | Optional. |
| C | Category ID | Optional. |
| D | Author Login | Optional. |
| E | Post Type | Optional. |
| F | Schedule Date | Optional. Use `YYYY-MM-DD HH:MM`. |
| G | Status | Leave empty for rows that should be processed. |
Column G controls whether a row is processed. If column G has any value, AI Puffer skips that row.
Rows are processed only when column A has a topic and column G is empty. After a post is created, AI Puffer writes `Processed on ...` to column G so the row is not used again.
If you use a header row, put a value in column G for that row, such as `Status`, so it is skipped.
AI Puffer uses a Google Cloud service account to read the sheet and update the status column.
Create the service account:
1. Open [Google Cloud Console](https://console.cloud.google.com/).
2. Create a new project, or select an existing project.
![Create a Google Cloud project]()
![Name the Google Cloud project]()
![Select the Google Cloud project]()
3. Open the project dashboard.
4. Go to **APIs & Services**.
5. Click **Enable APIs and Services**.
![Google Cloud dashboard]()
![Google Cloud APIs overview]()
![Enable Google Cloud APIs]()
6. Search for **Google Sheets API**.
7. Select **Google Sheets API**.
8. Click **Enable**.
![Search for Google Sheets API]()
![Select Google Sheets API]()
![Enable Google Sheets API]()
9. Go to **Credentials**.
10. Click **Create credentials**.
11. Select **Service account**.
12. Enter a service account name and click **Done**.
![Open Google Cloud credentials]()
![Create service account credentials]()
![Finish service account creation]()
13. Open the service account.
14. Go to **Keys**.
15. Click **Add key**.
16. Select **Create new key**.
17. Select **JSON** and click **Create**.
![Open the service account]()
![Open service account keys]()
![Create a service account key]()
![Select JSON key type]()
Keep the service account JSON file private. Anyone with this file can use the permissions granted to that service account.
Google downloads a `.json` file. You will upload it in AI Puffer.
![Downloaded service account JSON]()
![Service account JSON in Downloads]()
The service account needs Editor access because AI Puffer writes the processed status back to column G.
Share the sheet:
1. Open your Google Sheet.
2. Click **Share**.
3. Copy the service account email from Google Cloud or from the JSON file field named `client_email`.
4. Share the sheet with that email as **Editor**.
![Google Sheets share button]()
![Copy the service account email]()
![Share the sheet with the service account]()
Connect it in Content Writer:
1. Select **Google Sheets** in Content Writer.
2. Paste the Google Sheet ID.
3. Upload the service account JSON file.
4. Wait for the connection check to pass.
5. Set the model, prompts, publishing, image, and SEO options.
6. Click **Generate** or **Create Task**.
The Google Sheet ID is the value between `/d/` and `/edit` in the sheet URL.
```text theme={null}
https://docs.google.com/spreadsheets/d/GOOGLE_SHEET_ID/edit
```
![Content Writer Google Sheets]()
## Optimize
Use optimize modes when you want to update content that already exists in WordPress.
To update content from WordPress post lists or editor screens, use [WordPress Utilities](/wordpress-utilities).
### Rewrite Posts and Pages
Use **Rewrite Content** to update selected posts or pages.
Rewrite Content updates selected WordPress content directly. Test with one item first when changing prompts or enabled fields.
1. Select **Rewrite Content**.
2. Filter by type, status, or search term.
3. Select one or more rows.
4. In the right-side **General** card, click **Customize** next to **Prompts** and choose the fields to update.
5. Click **Update**.
![Content Writer Rewrite]()
Available update targets:
| Target | Result |
| ---------------- | -------------------------------------------------- |
| Title | Updates the post title. |
| Content | Updates the post content. |
| Meta Description | Updates the search meta description. |
| Focus Keyword | Updates the focus keyword when supported. |
| Excerpt | Updates the excerpt. |
| Tags | Updates tags. |
| URL | Updates the slug when **Optimize URL** is enabled. |
For existing content prompts, include at least one source placeholder:
```text theme={null}
{original_title}
{original_content}
{original_excerpt}
{original_meta_description}
{original_focus_keyword}
{original_tags}
{categories}
```
Available update fields depend on the selected content type and active plugins.
### Image Metadata
Use **Image Metadata** to update media library attachment data.
Image Metadata writes to media attachment fields directly. Enable only the fields you want to replace.
1. Select **Image Metadata**.
2. Filter images by media type, unattached items, owner, or search term.
3. Select the image.
4. In the right-side **General** card, click **Customize** next to **Prompts**.
5. Enable the metadata fields you want to update.
6. Click **Update**.
![Content Writer Image Metadata]()
Fields:
| Field | WordPress attachment field |
| ----------- | -------------------------- |
| Image title | Attachment title. |
| Alt text | Alternate text. |
| Caption | Attachment excerpt. |
| Description | Attachment content. |
Image metadata prompts can use:
```text theme={null}
{file_name}
{original_title}
{original_alt}
{original_caption}
{original_description}
{image_context}
```
You can update one selected image or use bulk updates when available in your installed plugin version.
### WooCommerce Products
Optimize Products appears when WooCommerce is active.
Optimize Products requires AI Puffer Pro. If WooCommerce is not active, this mode is not shown. On the free version, product updates are blocked and the action button opens the upgrade flow.
Use it to update existing WooCommerce product titles, descriptions, short descriptions, SEO data, tags, and URLs.
To update products:
1. Open **AI Puffer > Content Writer**.
2. Select **Optimize Products** under **Optimize**.
3. Use **Status** and **Search** to find products.
4. Select one or more products.
5. In the right-side **General** card, click **Customize** next to **Prompts**.
6. Enable the product fields you want to update.
7. Edit the prompts if needed.
8. Choose the AI provider, model, and length.
9. In the right-side **Advanced** card, set **Context** if product copy should use stored business or product information.
10. Click **Update**.
![Content Writer WooCommerce]()
Fields:
| Field | What it updates |
| ------------------- | ---------------------------------------------- |
| Product Title | Product name. |
| Product Description | Main product description. |
| Short Description | Product short description. |
| Meta Description | SEO meta description in supported SEO plugins. |
| Focus Keyword | SEO focus keyword in supported SEO plugins. |
| Tags | WooCommerce product tags. |
| URL | Product slug when URL optimization is enabled. |
Price, SKU, stock, dimensions, purchase note, categories, and attributes are available for prompts. AI Puffer uses them as source data; it does not change those WooCommerce product fields.
Product prompts can use:
```text theme={null}
{original_title}
{original_content}
{original_excerpt}
{original_meta_description}
{original_focus_keyword}
{original_tags}
{categories}
{price}
{regular_price}
{sale_price}
{sku}
{stock_quantity}
{stock_status}
{weight}
{length}
{width}
{height}
{short_description}
{purchase_note}
{product_categories}
{attributes}
```
## Settings
### Templates
Templates save reusable Content Writer settings. Use them when you often write with the same model, prompts, publishing rules, image settings, or knowledge settings.
The **Template** control is in the **General** panel on the right side of Content Writer.
Use the template menu to load, create, edit, rename, delete, and reset templates. Starter templates and default templates cannot be renamed or deleted.
![Templates]()
### AI
Content Writer uses the AI providers configured in AI Puffer, including hosted providers, xAI, and local Ollama models.
To set the model:
1. In the right panel, open **AI**.
2. Select the model.
3. Select the content **Length**.
4. Click the settings icon next to the model.
5. Adjust **Temperature** if you want more or less variation.
6. Set **Reasoning** only for models that support it. Keep it on **None** for faster generation.
Model settings include:
| Setting | What it does |
| --------------- | ------------------------------------------------------------- |
| **Model** | Model used for generation. |
| **Temperature** | Controls response variation. |
| **Reasoning** | Sets reasoning effort for supported OpenAI and Ollama models. |
| **Length** | Sets the token budget used for the generated content. |
![Models]()
Length values map to these token budgets:
| Length | Token budget |
| ------ | ------------ |
| Short | 2000 |
| Medium | 4000 |
| Long | 6000 |
![Model Settings]()
### Prompts
Prompts are the instructions Content Writer sends to the selected model. Each output has its own prompt, so the title, article body, SEO fields, excerpt, and tags can follow different rules.
To customize prompts:
1. In the right-side **General** card, click **Customize** next to **Prompts**.
2. Enable the outputs you want Content Writer to generate.
3. Click the edit icon next to an output.
4. Select **Default** or a saved prompt from the dropdown, or edit the prompt text directly.
5. Use the variables shown under the editor. Click a variable to copy it.
6. Click **Apply changes** if the button appears.
7. Generate one item and review the result before running a batch.
![Prompts Settings]()
| Output | What it updates |
| -------------------- | --------------------------------------- |
| **Title** | WordPress post title. |
| **Content** | WordPress post content. |
| **Meta Description** | SEO meta description. |
| **Focus Keyword** | Focus keyword in supported SEO plugins. |
| **Excerpt** | WordPress excerpt. |
| **Tags** | Post tags or product tags. |
Available variables change based on the selected source or optimize mode.
| Workflow | Variables to use |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Manual Entry, CSV, Google Sheets | Use `{topic}` in enabled prompts. Use `{keywords}` when keyword input should guide the result. |
| RSS Feed | Use `{description}` in the title and content prompts. Use `{source_url}` if the source URL should be included. |
| Web Page | Use `{url_content}` in the title and content prompts. Use `{source_url}` if the source URL should be included. |
| SEO, excerpt, tags | Use `{content_summary}` when the output should be based on the generated article. |
| Rewrite, image metadata, products | Use the variables shown under the prompt editor. They change for each optimize mode. |
AI Puffer checks required variables before generation. If a required variable is missing, it stops and asks you to update the prompt.
### SEO
Use SEO settings when the generated post should leave Content Writer with search metadata already filled in. AI Puffer can create a meta description, focus keyword, tags, and a cleaner WordPress URL slug.
Pro users can also use **Smart SEO** to audit and improve the generated draft against the active SEO plugin.
To use SEO output:
1. In the right-side **General** card, click **Customize** next to **Prompts**.
2. Enable **Meta Description**, **Focus Keyword**, or **Tags**.
3. Edit the prompt for each enabled output if the default instruction does not match your site.
4. In the right-side **General** card, click the settings icon next to **Status** to open **Post settings**.
5. Enable **Optimize URL** if you want AI Puffer to update the post slug.
6. Generate the content.
7. Review the SEO fields in the output panel before saving the post.
![SEO]()
![SEO]()
The focus keyword is generated first. Meta description, excerpt, and tag prompts can then use that keyword. If you enter keywords manually, the first keyword is used as the focus keyword.
| Output | How it is saved |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Meta description** | Saved to the active SEO plugin. If no supported SEO plugin is active, AI Puffer saves it as fallback post meta. |
| **Focus keyword** | Saved to Yoast SEO, Rank Math, or All in One SEO. |
| **Tags** | Saved as WordPress tags for new posts. Existing-post and product update workflows use the matching tag taxonomy when available. |
| **URL** | Updates the WordPress post slug when **Optimize URL** is enabled. |
#### Smart SEO
Smart SEO is a Pro feature.
* It works in Content Writer Create mode.
* It supports Single generation, Batch generation, Quick Paste, CSV, RSS, URL, and Google Sheets batches.
* It automatically detects the active SEO plugin.
* It checks the generated draft against that SEO profile.
* It improves the draft before you save it.
* For SEO revisions, Smart SEO may use a quality-focused model from the same AI provider selected for generation, never switches providers, and uses the selected deployment or local model for Azure and Ollama.
* It tries to improve the generated draft up to `100/100`.
* It can run up to three SEO revisions.
* If the draft cannot reach `100/100`, AI Puffer keeps the best-scoring revision.
* In **Single** mode, users can review the SEO score and switch between revisions before saving.
* In batch modes, users see the SEO score and status in the batch monitor.
* Free users can still generate meta descriptions, focus keywords, tags, excerpts, and optimized slugs.
* Only Smart SEO score improvement is paid.
To use Smart SEO:
1. Open **AI Puffer > Content Writer**.
2. Choose a Create source such as **Manual Entry**, **CSV**, **RSS**, **URL**, or **Google Sheets**.
3. In the right-side **General** card, enable **Smart SEO**.
4. Generate the content.
5. Review the SEO score and generated post before saving.
![SEO]()
Advanced users can open **Smart SEO rules** from the settings icon next to the Smart SEO toggle. This panel lets you choose a preset or enable and disable individual rules for the active SEO plugin profile.
| Preset | Default | What it does |
| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Strict score** | No | Enables every listed rule to chase the highest possible SEO plugin score. Use it when matching the plugin score is more important than minimizing editorial constraints. |
| **Balanced** | Yes | Keeps the main SEO checks enabled, including Rank Math title-start, table of contents, rich media, and keyword density checks. It still skips optional title gimmicks such as numbers, power words, sentiment wording, and selected image-alt/headline pressure. |
| **Content first** | No | Keeps essential metadata and placement checks while reducing content-length, density, readability, media, and plugin-specific pressure. Use it when natural writing matters more than maximum plugin score. |
After choosing a preset, you can still toggle individual rules. If the selected rules no longer match a preset, the panel shows the selection as custom.
Depending on the active SEO plugin profile, Smart SEO can check:
| Area | Examples |
| --------------------- | --------------------------------------------------------------------------------------------------- |
| **Focus keyword** | Title, introduction, headings, meta description, slug, and duplicate-keyword usage. |
| **Metadata** | Meta description presence and length. |
| **Content structure** | Content length, heading balance, table of contents, paragraph length, and sentence length. |
| **Links** | Internal links, outbound links, and dofollow outbound links when the active SEO plugin scores them. |
| **Media** | Image presence and focus-keyword image alt text. |
| **Readability** | Transition words, repeated sentence openings, passive voice, and reading ease where supported. |
The exact checks depend on the active SEO plugin profile. Some checks are shared across profiles, while others mirror plugin-specific scoring behavior.
| Check | Applies to | What Smart SEO checks |
| --------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Focus keyword in title | Yoast SEO, Rank Math, All in One SEO | The SEO title should include the focus keyword. Yoast prefers the exact keyphrase at the beginning, while Rank Math and AIOSEO add their own title-position checks. |
| Focus keyword in URL slug | Yoast SEO, Rank Math, All in One SEO | The optimized slug should include the focus keyword when **Optimize URL** is enabled or a slug is available. |
| Paragraph length | Yoast SEO, Rank Math, All in One SEO | Long paragraphs should be split so the article is easier to scan. |
| Meta description exists | Yoast SEO, Rank Math, The SEO Framework | A meta description should be present. AIOSEO uses its own profile-specific meta description check. |
| Content length | Yoast SEO, Rank Math | Yoast uses the selected minimum word count. Rank Math uses its own scoring ladder and gives full content-length credit at `2500+` words. |
| Focus keyword in introduction | Yoast SEO, Rank Math | Yoast checks the first paragraph. Rank Math checks the first 10% of the content. |
| Focus keyword in meta description | Yoast SEO, Rank Math | The meta description should include the focus keyword. |
| Focus keyword in heading | Yoast SEO, Rank Math | Yoast checks H2/H3 balance. Rank Math accepts H2-H6 and needs at least one matching heading. |
| Internal link | Yoast SEO, Rank Math | The article should include a verified internal link. Rank Math requires a link to another published post or page. |
| External link | Yoast SEO, Rank Math | The article should include a safe outbound link when the profile scores outbound links. |
| Image alt keyphrase | Yoast SEO, Rank Math | At least one image alt text should contain the focus keyphrase or enough keyphrase words. |
| Previously used keyphrase | Yoast SEO, Rank Math | The focus keyphrase should not already be used by another post. |
| Keyword density | Yoast SEO, Rank Math | Exact focus-keyphrase usage should stay in the plugin's target range without stuffing. |
| Check | What Smart SEO checks |
| ---------------------------------- | ---------------------------------------------------------------------------------------- |
| SEO title width | Title should be in a strong display range, roughly 35-65 characters. |
| Focus keyphrase length | Focus keyphrase should usually be 1-4 words. |
| Meta description length | Strong range is 120-156 characters. Longer descriptions are reduced. |
| Focus keyphrase in first paragraph | The first introduction paragraph should include the focus keyphrase when natural. |
| Focus keyphrase in subheadings | Enough H2/H3 subheadings should include the keyphrase, but over-optimization is avoided. |
| Heading distribution | Longer articles should use H2/H3 headings to break up sections. |
| Image exists | The draft should include at least one image. |
| Single H1 | The article body should not contain multiple H1 headings. |
| Competing links | Link anchor text should not be the exact focus keyphrase. |
| Consecutive sentence starts | Avoid three or more consecutive sentences starting with the same word. |
| Transition words | At least about 30% of eligible sentences should use transition words. |
| Sentence length | Long sentences over 20 words should stay within Yoast's readability threshold. |
| Passive voice | Passive voice should generally stay at or below 10% of sentences. |
| Check | What Smart SEO checks |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Content length | Full content-length credit is `2500+` words. Rank Math gives partial credit at lower ranges and fails very short content. |
| Focus keyword at title beginning | The SEO title should start with the exact focus keyword. |
| Number in title | The SEO title should include a relevant number. |
| Power word in title | The SEO title should include a natural power word such as "best", "complete", "easy", "powerful", or "ultimate". |
| Sentiment in title | The SEO title should include natural positive or negative sentiment wording. |
| Permalink length | The full permalink should be 75 characters or fewer. |
| Table of contents | A Rank Math-compatible table of contents should be present, or a ToC plugin should be detected. |
| Keyword density | Exact focus-keyphrase usage should stay in Rank Math's target range. Low density is improved and overuse is reduced. |
| Images or videos | Rank Math gives media credit for images or videos. Smart SEO preserves media and alt text but does not invent image or video URLs. |
| Check | What Smart SEO checks |
| ---------------------------------- | ------------------------------------------------------------------------------------ |
| Focus keyword in content | The content should contain the focus keyword. |
| Focus keyword in introduction | The first paragraph should contain the focus keyword when natural. |
| Focus keyword in meta description | The meta description should contain the focus keyword. |
| Focus keyword in image alt | Existing image alt text should contain the exact focus keyword. |
| Focus keyword in subheadings | The exact focus keyword should appear in about 30%-75% of H2/H3 subheadings. |
| Focus keyword length | 1-4 words passes; longer keyphrases may warn or fail. |
| Meta description length | The target range is roughly 121-160 characters. Empty descriptions fail. |
| Content length | More than 300 words passes. Shorter content may warn or fail. |
| Internal links | The content should link to another resource on the same site. |
| External links | The content should link to a relevant external resource. |
| Focus keyword near title beginning | The focus keyword should appear near the beginning of the SEO title. |
| SEO title length | The title should generally be 41-60 characters after AIOSEO-style title scoring. |
| Headline score | If AIOSEO's headline analyzer is available, Smart SEO aims for a 70+ headline score. |
| Images or videos | The content should include rich media when AIOSEO scores it. |
| Sentence length | Too many sentences over 20 words can reduce the readability score. |
| Passive voice | Passive voice should generally stay at or below 10% of sentences. |
| Transition words | At least about 30% of eligible sentences should use transition words. |
| Consecutive sentences | Avoid four or more consecutive sentences starting with the same word. |
| Subheading distribution | Long sections should be separated by subheadings. |
| Flesch reading ease | Copy should be easy to read, with a target score of about 63 or higher. |
| Check | What Smart SEO checks |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Meta description exists | A meta description should be present. |
| Meta description length | The strongest range is roughly 80-160 characters. |
| SEO title length and width | Smart SEO estimates the title shown by The SEO Framework, including the site title unless that setting removes it, and keeps it within the target display range. |
| Focus keyword behavior | The SEO Framework does not provide a native focus keyword field, so Smart SEO does not apply focus-keyword placement rules for this profile. |
![SEO]()
Smart SEO follows the active SEO plugin profile automatically. If more than one supported SEO plugin is active, AI Puffer chooses one profile and shows a warning. For predictable scores, use one SEO plugin at a time.
Some SEO plugin checks are owned by the SEO plugin itself and cannot always be fixed by AI Puffer. For example, plugin-specific premium AI checks or settings-based checks may still appear in the SEO plugin after generation.
#### Yoast SEO
AI Puffer saves the generated meta description to the Yoast meta description field and the generated focus keyword to the Yoast focus keyphrase field.
If **Optimize URL** is enabled, the slug is built from the focus keyphrase when available. If there is no focus keyphrase, the post title is used.
Smart SEO's Yoast profile is tuned for Yoast SEO analysis and readability checks, including keyphrase placement, meta description length, links, image alt text, and readability signals.
#### Rank Math
AI Puffer saves the generated meta description to the Rank Math description field and the generated focus keyword to the Rank Math focus keyword field.
Smart SEO's Rank Math profile is tuned for Rank Math's Basic SEO, Additional SEO, Title Readability, and Content Readability checks.
#### All in One SEO
AI Puffer saves the generated meta description to All in One SEO and updates the focus keyphrase data used by AIOSEO.
Smart SEO's All in One SEO profile is tuned for TruSEO checks, focus keyphrase analysis, readability checks, and headline score improvements.
#### The SEO Framework
AI Puffer saves the generated meta description to The SEO Framework description field.
The SEO Framework does not provide a native focus keyword field, so AI Puffer does not save a focus keyword for it.
Smart SEO's The SEO Framework profile focuses on title and description behavior because The SEO Framework does not provide a native focus keyword field.
If none of the supported SEO plugins are active, AI Puffer still saves the meta description as fallback post meta. Focus keyword output remains visible in Content Writer, but there is no SEO plugin field to save it into.
WordPress tags and the optimized URL slug still work without an SEO plugin.
### Publishing
Publishing controls the WordPress post that gets created after generation.
To set the post target:
1. In the right-side **General** card, select the post **Status**.
2. Click the settings icon next to **Status** to open **Post settings**.
3. Select the **Post Type**.
4. Select the **Author**.
5. Select categories if the post type supports them.
6. Enable **Table of Contents** if you want a generated table of contents added to the top of the post.
7. Enable **Optimize URL** if you want AI Puffer to generate a cleaner WordPress slug.
![Publishing]()
| Setting | Use it for |
| --------------------- | ----------------------------------------------------- |
| **Status** | Draft, Publish, Pending Review, or Private. |
| **Post Type** | Public WordPress post type. |
| **Author** | WordPress author. |
| **Categories** | WordPress categories assigned to the post. |
| **Table of Contents** | Adds a table of contents from the generated headings. |
| **Optimize URL** | Updates the WordPress slug after the post is saved. |
![Publishing Options]()
#### Schedule
Schedule options appear when **Status** is set to **Publish** and you are generating multiple items. Single Entry publishes immediately when the status is **Publish**.
To schedule posts:
1. Set **Status** to **Publish**.
2. Choose one of the available schedule modes.
3. Use **Smart Schedule** when AI Puffer should space posts automatically.
4. Use **Use Dates from Input** when each row, CSV line, or Google Sheets row already has its own date.
5. Generate the batch or create the task.
![Schedule]()
| Option | Behavior |
| ------------------------ | ------------------------------------------------------------------------------ |
| **Publish Immediately** | Publishes without spacing posts out. |
| **Smart Schedule** | Starts at a date/time and spaces posts by hours or days. |
| **Use Dates from Input** | Uses the schedule field from Batch Editor, Quick Paste, CSV, or Google Sheets. |
Use this date format:
```text theme={null}
YYYY-MM-DD HH:MM
```
Quick Paste can include the schedule as the last field:
```text theme={null}
Topic | Keywords | Category ID | Author Login | Post Type | YYYY-MM-DD HH:MM
```
Use Dates from Input is available for Batch Editor, Quick Paste, CSV, and Google Sheets. RSS Feed and Web Page sources can use Publish Immediately or Smart Schedule.
### Images
Images can be inserted into the article content, set as the featured image, or both.
To use images, first choose what AI Puffer should create:
1. In the right-side **Media** card, set **Images** to **Content**, **Featured**, or **Content + Featured**.
2. Select the image provider or model from **Image source**.
3. Click the settings icon beside **Image source** to open **Image settings**.
4. Set the image count, placement, WordPress display size, alignment, and provider options.
5. Generate one item and review the image previews before saving the post.
![Images]()
| Mode | Result |
| ---------------------- | ---------------------------------------------- |
| **Off** | No images are generated or fetched. |
| **Content** | Adds images inside the post content. |
| **Featured** | Sets a featured image. |
| **Content + Featured** | Adds content images and sets a featured image. |
AI image sources use the image prompt. Stock photo sources use the generated keywords first. If there are no keywords, AI Puffer uses the topic or title as the search query.
Image prompts are used for OpenAI, Google, OpenRouter, Azure, xAI, and Replicate. Pexels and Pixabay do not use image prompts because they search existing stock photos.
Image placement controls where content images are inserted after the post is saved.
| Setting | Use it for |
| ---------------- | ----------------------------------------- |
| **Count** | Number of content images to insert. |
| **Placement** | Where content images should be inserted. |
| **X** | Used only with every-X placement options. |
| **Display size** | WordPress image size used in the post. |
| **Align** | WordPress image alignment. |
Placement options:
| Placement | Result |
| ---------------------- | ---------------------------------------------------------- |
| **After 1st H2** | Inserts the first image after the first H2 heading. |
| **After 1st H3** | Inserts the first image after the first H3 heading. |
| **Every X H2s** | Inserts images after every selected number of H2 headings. |
| **Every X H3s** | Inserts images after every selected number of H3 headings. |
| **Every X paragraphs** | Inserts images after every selected number of paragraphs. |
| **End of content** | Adds images at the end of the article. |
![Image Options]()
#### OpenAI
OpenAI uses your OpenAI API key and one of the image models available in your synced model list.
To set it up:
1. Go to **AI Puffer > Settings > AI**.
2. Select **OpenAI**.
3. Add your OpenAI API key.
4. Sync models.
5. In the right-side **Media** card, set **Images** to **Content**, **Featured**, or **Content + Featured**.
6. Select an OpenAI image model from **Image source**.
7. In the right-side **General** card, click **Customize** next to **Prompts** if you want to change the image prompt or featured image prompt.
![Image Prompts]()
#### Google
Google uses your Google API key and the Google image models available in your synced model list.
To set it up:
1. Go to **AI Puffer > Settings > AI**.
2. Select **Google**.
3. Add your Google API key.
4. Sync models.
5. In the right-side **Media** card, set **Images** to **Content**, **Featured**, or **Content + Featured**.
6. Select a Google image model from **Image source**.
7. In the right-side **General** card, click **Customize** next to **Prompts** if you want to change the image prompt or featured image prompt.
#### OpenRouter
OpenRouter uses image-capable models from your OpenRouter account.
To set it up:
1. Go to **AI Puffer > Settings > AI**.
2. Select **OpenRouter**.
3. Add your OpenRouter API key.
4. Sync models.
5. In the right-side **Media** card, set **Images** to **Content**, **Featured**, or **Content + Featured**.
6. Select an OpenRouter image model from **Image source**.
If a selected OpenRouter model does not return images, choose another image-capable model from the synced list.
#### Azure
Azure uses your Azure OpenAI endpoint, API key, API version, and image deployment.
To set it up:
1. Go to **AI Puffer > Settings > AI**.
2. Select **Azure**.
3. Add the Azure endpoint and API key.
4. Add or sync the image deployment you want to use.
5. In the right-side **Media** card, set **Images** to **Content**, **Featured**, or **Content + Featured**.
6. Select the Azure image deployment from **Image source**.
#### xAI
xAI uses your xAI API key and synced xAI image models such as `grok-imagine-image`.
To set it up:
1. Go to **AI Puffer > Settings > AI**.
2. Select **xAI**.
3. Add your xAI API key.
4. Sync models.
5. In the right-side **Media** card, set **Images** to **Content**, **Featured**, or **Content + Featured**.
6. Select an xAI image model from **Image source**.
#### Replicate
Replicate uses your Replicate API key and synced text-to-image models.
To set it up:
1. Go to **AI Puffer > Settings > Integrations**.
2. Select **Replicate**.
3. Add your Replicate API key.
4. Sync Replicate models.
5. In the right-side **Media** card, set **Images** to **Content**, **Featured**, or **Content + Featured**.
6. Select a Replicate model from **Image source**.
#### Pexels
Pexels searches stock photos instead of generating a new image.
To set it up:
1. Go to **AI Puffer > Settings > Integrations**.
2. Select **Pexels**.
3. Add your Pexels API key, or use the **Get Key** link to create one.
4. In the right-side **Media** card, set **Images** to **Content**, **Featured**, or **Content + Featured**.
5. Select **Pexels** from **Image source**.
6. Click the settings icon beside **Image source** to open **Image settings**.
7. Set **Orientation**, **Size**, and **Color** if you want to filter results.
8. Generate one item and review the selected photo.
#### Pixabay
Pixabay searches stock photos, illustrations, or vectors.
To set it up:
1. Go to **AI Puffer > Settings > Integrations**.
2. Select **Pixabay**.
3. Add your Pixabay API key, or use the **Get Key** link to create one.
4. In the right-side **Media** card, set **Images** to **Content**, **Featured**, or **Content + Featured**.
5. Select **Pixabay** from **Image source**.
6. Click the settings icon beside **Image source** to open **Image settings**.
7. Set **Orientation**, **Type**, and **Category** if you want to narrow results.
8. Generate one item and review the selected image.
#### Provider Options
Provider options control the generation request sent to the selected AI provider. They are separate from WordPress display settings such as **Display size** and **Align**.
Only options supported by the selected provider and model are shown.
| Provider | Available options |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **OpenAI** | Canvas size, quality, output format, compression, background, moderation. |
| **Azure** | Canvas size, quality, output format, compression, background. |
| **Google** | Aspect ratio, image resolution, and person generation for supported Imagen models. Nano Banana models are included in the Google image model list. |
| **OpenRouter** | Aspect ratio and image resolution for models that support image configuration. |
| **xAI** | Aspect ratio and image resolution. |
| **Replicate** | Model-specific options from synced model schemas. |
Pexels and Pixabay are stock image sources. Their filters narrow search results instead of changing an AI generation request.
#### Image Prompts
For AI image providers, the image prompt controls content images and the featured image prompt controls the featured image.
You can use these placeholders:
| Placeholder | Replaced with |
| -------------- | --------------------- |
| `{topic}` | Generated title. |
| `{keywords}` | Generated keywords. |
| `{post_title}` | WordPress post title. |
| `{excerpt}` | Generated excerpt. |
![Featured Image Prompt]()
#### Image Metadata
To generate image metadata:
1. In the right-side **General** card, click **Customize** next to **Prompts**.
2. Enable the image metadata fields you want: **Title**, **Alt Text**, **Caption**, or **Description**.
3. Edit the metadata prompts if needed.
4. Generate the content and images.
AI Puffer saves generated metadata to the WordPress media attachment fields. Alt text is saved as the attachment alternate text.
![Image Metadata]()
### Knowledge Base
Knowledge Base lets Content Writer use vector data you already added in **AI Puffer > Knowledge Base > Data**.
When Knowledge Base is enabled, AI Puffer searches the selected vector source with the current generation prompt and adds the closest matches to the request.
To enable it:
1. Add data in **AI Puffer > Knowledge Base > Data** first.
2. In the right-side **Advanced** card, set **Context** to **OpenAI**, **Pinecone**, **Qdrant**, or **Chroma**.
3. Select the vector store, index, or collection in **Source**.
4. Click the settings icon beside **Source** to open **Context settings**.
5. For Pinecone, Qdrant, or Chroma, select the embedding provider and model in **Context settings**.
6. Set **Results Limit** and **Confidence Threshold**.
7. Generate one item and check the output.
![knowledgebase]()
![knowledgebase]()
#### OpenAI
OpenAI uses OpenAI Vector Stores.
To create a store:
1. Go to **AI Puffer > Knowledge Base > Stores**.
2. Select **OpenAI** as the provider.
3. Click **Create Store**.
![OpenAI Create Vector]()
4. Enter a store name and create it.
5. Go to **AI Puffer > Knowledge Base > Data** and add data to the store.
![OpenAI Add Data]()
To use it in Content Writer:
1. In the right-side **Advanced** card, set **Context** to **OpenAI**.
2. Select one or more vector stores in **Source**.
3. Click the settings icon beside **Source** if you need to adjust **Results Limit** or **Confidence Threshold**.
When Content Writer uses an OpenAI model, AI Puffer can pass the selected vector stores to OpenAI file search. With other content models, AI Puffer searches the stores first and adds matching text to the prompt.
#### Pinecone
Pinecone stores vectors in an index. AI Puffer creates and searches those vectors with the embedding model you choose.
The Pinecone index dimension must match the embedding model. For example, if your index is **3072 dimensions**, use a **3072-dimension** embedding model.
Use the same embedding model when adding data to Pinecone and when enabling Pinecone in Content Writer.
To create an index:
1. Add your Pinecone credentials in **AI Puffer > Settings > Integrations**.
![Pinecone API key]()
2. Go to **AI Puffer > Knowledge Base > Stores**.
3. Select **Pinecone** as the provider.
4. Select the embedding model you want to use.
5. Click **Create Store**.
![Pinecone Create Index]()
6. Enter an index name and use the dimension for the selected embedding model.
7. Create the index, then add data with the same embedding model.
![Pinecone Create Index]()
To use it in Content Writer:
1. In the right-side **Advanced** card, set **Context** to **Pinecone**.
2. Select the Pinecone index in **Source**.
3. Click the settings icon beside **Source** to open **Context settings**.
4. Select the same embedding provider and model used when you added the data.
5. Adjust **Results Limit** or **Confidence Threshold** if needed.
#### Qdrant
Qdrant stores vectors in a collection. AI Puffer creates and searches those vectors with the embedding model you choose.
The Qdrant collection size must match the embedding model. For example, if your collection is **3072 dimensions**, use a **3072-dimension** embedding model.
Use the same embedding model when adding data to Qdrant and when enabling Qdrant in Content Writer.
To create a collection:
1. Add your Qdrant URL and API key in **AI Puffer > Settings > Integrations**.
![Qdrant API key]()
2. Go to **AI Puffer > Knowledge Base > Stores**.
3. Select **Qdrant** as the provider.
4. Select the embedding model you want to use.
5. Click **Create Store**.
![Qdrant Create collection]()
6. Enter a collection name and use the dimension for the selected embedding model.
7. Create the collection, then add data with the same embedding model.
![Qdrant Create collection]()
To use it in Content Writer:
1. In the right-side **Advanced** card, set **Context** to **Qdrant**.
2. Select the Qdrant collection in **Source**.
3. Click the settings icon beside **Source** to open **Context settings**.
4. Select the same embedding provider and model used when you added the data.
5. Adjust **Results Limit** or **Confidence Threshold** if needed.
#### Chroma
Chroma stores vectors in a collection. AI Puffer creates and searches those vectors with the embedding model you choose.
Chroma collections do not require a dimension when they are created in AI Puffer, but stored vectors still need a consistent dimension. Use the same embedding model when adding data to Chroma and when enabling Chroma in Content Writer.
To create a collection:
1. Add your Chroma endpoint, tenant, database, and API key in **AI Puffer > Settings > Integrations**.
![Chroma API key]()
2. Go to **AI Puffer > Knowledge Base > Stores**.
3. Select **Chroma** as the provider.
4. Click **Create Store**.
![Chroma Create collection]()
5. Enter a collection name.
6. Create the collection, then add data with the same embedding model.
To use it in Content Writer:
1. In the right-side **Advanced** card, set **Context** to **Chroma**.
2. Select the Chroma collection in **Source**.
3. Click the settings icon beside **Source** to open **Context settings**.
4. Select the same embedding provider and model used when you added the data.
5. Adjust **Results Limit** or **Confidence Threshold** if needed.
#### Limit and Threshold
Use these settings to control how much vector context is added to the generated content.
| Setting | How it works | Example |
| ------------------------ | ------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Results Limit** | How many matching pieces of knowledge AI Puffer can use. | `3` means AI Puffer can use up to 3 matching pieces. |
| **Confidence Threshold** | How closely a result must match before AI Puffer includes it. | Lower values allow looser matches. Higher values allow only stronger matches. |
Use a lower threshold if useful context is being missed. Use a higher threshold if unrelated context is being included.
After testing, open **Usage > Logs** and check the Score badge when vector results are recorded.
Start with a small limit and tune the threshold after testing real topics.
## Logs
Content Writer activity is logged under AI Puffer logs.
| Source | Log module |
| -------------------------------- | --------------------------- |
| Direct Content Writer generation | `content_writer` |
| Automated Content Writer tasks | `content_writer_automation` |
Use the `content.generated` event when another system needs to receive generated content after Content Writer finishes. See [Event Webhooks](/event-webhooks) for payload and delivery details.
# Event Webhooks
Source: https://docs.aipower.org/event-webhooks
Send AI Puffer events to external URLs.
Event webhooks send an HTTP `POST` request when selected AI Puffer events happen.
Use them when another system needs to receive form submissions, chatbot activity, generated content, image outputs, automation results, or knowledge base indexing results.
Enable webhooks, add endpoints, and choose events.
See the event names and when they fire.
Read the request headers and JSON body format.
Verify requests with the signing secret.
Understand success responses, retries, and failed deliveries.
Fix missing requests, signature errors, and timeouts.
## Setup
In WordPress admin, go to **AI Puffer > Settings > Developers**.
To enable event webhooks:
1. Turn on **Event Webhooks**.
2. Enter a **Signing Secret** if your receiver will verify requests.
3. Click **Add Endpoint**.
4. Enter a name and endpoint URL.
5. Turn on the endpoint.
6. Select the events this endpoint should receive.
Settings save automatically after you change them.
![Developer Settings with Event Webhooks enabled]()
![Webhook endpoint with subscribed events]()
The endpoint URL must be reachable from your WordPress server. For production, use an HTTPS URL.
An endpoint receives an event only when all of these are true:
| Requirement | Meaning |
| ------------------------- | ----------------------------------------- |
| Event Webhooks is enabled | The global switch is on. |
| Endpoint is enabled | The endpoint's own switch is on. |
| Endpoint URL is set | AI Puffer has a URL to send to. |
| Event is selected | The endpoint is subscribed to that event. |
## Events
| Event | Module | Fires when |
| -------------------------------- | -------------- | ------------------------------------------------------------------- |
| `chatbot.session_started` | Chatbots | A new chatbot conversation starts. |
| `chatbot.user_message_submitted` | Chatbots | A user sends a chatbot message. |
| `chatbot.response_generated` | Chatbots | The chatbot response is completed. |
| `chatbot.fb_submitted` | Chatbots | A user submits chatbot feedback. |
| `chatbot.form_submitted` | Chatbots | A visitor submits a form displayed by a chatbot rule. |
| `content.generated` | Content Writer | Content is generated from Content Writer, streaming, or automation. |
| `task.item_completed` | Automations | An automation queue item finishes. |
| `form.submitted` | AI Forms | An AI Form submission completes and returns a response. |
| `image.generated` | Images | An image, edit, or video generation request returns output. |
| `kb.source_indexed` | Knowledge Base | A source is indexed successfully. |
Endpoint subscriptions for chatbot feedback are normalized to `chatbot.fb_submitted`.
## Payload
AI Puffer sends JSON to each subscribed endpoint.
```http theme={null}
POST /your-webhook-url HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/json
```
### Headers
| Header | Meaning |
| -------------------------- | ------------------------------------------------------- |
| `X-AIPKit-Event` | Event name, such as `form.submitted`. |
| `X-AIPKit-Event-Id` | Unique event envelope ID. |
| `X-AIPKit-Delivery-Id` | Unique delivery ID for this endpoint attempt group. |
| `X-AIPKit-Idempotency-Key` | Stable key for deduplicating repeated delivery. |
| `X-AIPKit-Schema-Version` | Event schema version. Current value: `2026-05-21`. |
| `X-AIPKit-Timestamp` | Unix timestamp used for the signature. |
| `X-AIPKit-Signature` | HMAC signature. Sent only when a signing secret is set. |
| `X-AIPKit-Signature-Alg` | `sha256`. Sent only when a signing secret is set. |
### Envelope
Every event uses the same outer envelope. Event-specific fields are inside `data`.
```json theme={null}
{
"id": "9b3c1fd4-9a4b-4f10-b82c-53a9f0f4a8b1",
"type": "form.submitted",
"schema_version": "2026-05-21",
"occurred_at": "2026-04-25T09:00:00+00:00",
"idempotency_key": "0b6c1e2a...",
"site": {
"url": "https://your-site.com",
"name": "Your Site"
},
"plugin": {
"slug": "gpt3-ai-content-generator",
"version": "2.4.26"
},
"source": {
"module": "ai_forms",
"origin": "frontend_submission_completed"
},
"resource": {
"type": "form_submission",
"id": "conversation-uuid",
"label": "Submission for Contact Form"
},
"data": {
"form": {
"id": 123,
"name": "Contact Form"
},
"inputs": {
"email": "person@example.com",
"message": "I need help with pricing."
},
"response": {
"text": "Thanks. Here is a short reply..."
}
},
"meta": {
"form_id": 123,
"ai_provider": "OpenAI",
"ai_model": "gpt-4o-mini"
}
}
```
`resource` and `meta` are included when the event provides them.
### Event Data
Use `type` or `X-AIPKit-Event` to decide which fields to read from `data`.
`chatbot.session_started` and `chatbot.user_message_submitted` include bot, conversation, actor, message, and AI model details.
| Field | Meaning |
| --------------------------------- | --------------------------------------- |
| `data.bot.id` | Chatbot ID. |
| `data.bot.name` | Chatbot name. |
| `data.conversation.id` | Conversation UUID. |
| `data.conversation.message_count` | Number of messages in the conversation. |
| `data.actor.type` | `user` or `guest`. |
| `data.actor.user_id` | WordPress user ID when available. |
| `data.message.text` | User message text. |
| `data.ai.provider` | Provider used by the chatbot. |
| `data.ai.model` | Model used by the chatbot. |
`chatbot.response_generated` includes `data.response.text`. `chatbot.fb_submitted` includes `data.feedback`.
`chatbot.form_submitted` is sent when a visitor submits a form displayed by a chatbot rule's **Display form** action.
| Field | Meaning |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data.bot.id` | Chatbot ID. |
| `data.bot.name` | Chatbot name. |
| `data.conversation.id` | Conversation UUID. |
| `data.conversation.message_count` | Number of messages in the conversation. |
| `data.actor.type` | `user` or `guest`. |
| `data.actor.user_id` | WordPress user ID when available. |
| `data.form.id` | Rule form ID. |
| `data.form.name` | Rule form name. |
| `data.submission.id` | Submission ID. |
| `data.inputs` | Submitted form inputs, including common aliases such as `email`, `first_name`, `last_name`, `phone`, and `company` when matching fields exist. |
| `data.display_values` | Submitted values after option labels are resolved. |
| `data.labels` | Form field labels. |
| `data.summary` | Human-readable submission summary. |
| `data.page.id` | WordPress page or post ID when available. |
| `data.page.url` | Referring page URL when available. |
| `data.ai.provider` | Provider configured for the chatbot. |
| `data.ai.model` | Model configured for the chatbot. |
`content.generated` can come from Content Writer, streaming, or an automation task.
| Field | Meaning |
| ----------------------- | ------------------------------------------------ |
| `data.title` | Generated title when available. |
| `data.content` | Generated content. |
| `data.excerpt` | Excerpt when generated. |
| `data.meta_description` | SEO description when generated. |
| `data.focus_keyword` | Focus keyword when generated. |
| `data.tags` | Tags when generated. |
| `data.post.id` | Created post ID when a post was created. |
| `data.post.status` | WordPress post status. |
| `data.post.url` | WordPress post URL. |
| `data.ai.provider` | Provider used for generation. |
| `data.ai.model` | Model used for generation. |
| `data.task.id` | Automation task ID when generated by automation. |
`task.item_completed` is sent when an automation queue item completes.
| Field | Meaning |
| ----------------------------------- | ------------------------------------------------------- |
| `data.task.id` | Automation task ID. |
| `data.task.name` | Automation task name. |
| `data.task.type` | Automation task type. |
| `data.queue_item.id` | Queue item ID. |
| `data.queue_item.target_identifier` | Topic, URL, row, product, post, or other queued target. |
| `data.queue_item.status` | Final queue status. |
| `data.queue_item.attempts` | Number of attempts. |
| `data.result.message` | Result message. |
| `data.result.generated_post_id` | Generated post ID when available. |
| `data.ai.provider` | Provider used by the queue item when available. |
| `data.ai.model` | Model used by the queue item when available. |
`form.submitted` is sent after an AI Form returns a response.
| Field | Meaning |
| ----------------------- | --------------------------------- |
| `data.form.id` | AI Form ID. |
| `data.form.name` | AI Form name. |
| `data.submission.id` | Submission ID. |
| `data.submission.count` | Submission count. |
| `data.inputs` | Submitted form inputs. |
| `data.response.text` | AI response. |
| `data.ai.provider` | Provider used by the form. |
| `data.ai.model` | Model used by the form. |
| `data.actor.type` | `user` or `guest`. |
| `data.actor.user_id` | WordPress user ID when available. |
`image.generated` is sent after image, image edit, or video generation returns output.
| Field | Meaning |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `data.prompt` | Prompt used for generation. |
| `data.provider` | Image or video provider, for example `xAI`. |
| `data.model` | Model used for generation. |
| `data.mode` | Generation mode. |
| `data.media_type` | `image` or `video`. |
| `data.output_count` | Number of generated outputs. |
| `data.outputs.images` | Image output data. |
| `data.outputs.videos` | Video output data. |
| `data.usage` | Usage details when returned by the provider. xAI image responses can include `cost_in_usd_ticks` inside provider usage metadata. |
| `data.actor.type` | `user` or `guest`. |
`kb.source_indexed` is sent after a Knowledge Base source is indexed successfully.
| Field | Meaning |
| ------------------------- | -------------------------------------------- |
| `data.source.log_id` | Knowledge source log ID. |
| `data.source.post_id` | WordPress post ID when the source is a post. |
| `data.source.post_title` | Source title. |
| `data.source.post_url` | Source URL when available. |
| `data.provider` | Vector provider. |
| `data.store.id` | Vector store, index, or collection ID. |
| `data.store.name` | Vector store, index, or collection name. |
| `data.status` | Indexing status. |
| `data.message` | Indexing message. |
| `data.embedding.provider` | Embedding provider. |
| `data.embedding.model` | Embedding model. |
## Signatures
If a signing secret is set, AI Puffer signs the raw JSON body.
Signature base string:
```text theme={null}
{X-AIPKit-Timestamp}.{raw_request_body}
```
Signature algorithm:
```text theme={null}
HMAC-SHA256
```
Header format:
```text theme={null}
X-AIPKit-Signature: sha256=HEX_DIGEST
```
Verify the raw request body exactly as received. Do not parse JSON and then stringify it again before checking the signature.
Node example:
```js theme={null}
import crypto from "node:crypto";
function verifyAIPufferWebhook({ rawBody, timestamp, signature, secret }) {
const expected =
"sha256=" +
crypto
.createHmac("sha256", secret)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
const a = Buffer.from(signature);
const b = Buffer.from(expected);
if (a.length !== b.length) {
return false;
}
return crypto.timingSafeEqual(a, b);
}
```
## Delivery
Return any `2xx` status code to mark the delivery as successful.
```json theme={null}
{
"received": true
}
```
AI Puffer treats network errors and non-`2xx` responses as failed deliveries. Retryable failures include network errors, `408`, `409`, `425`, `429`, and `5xx` responses.
Default delivery behavior:
| Setting | Default |
| ----------------------- | ------------------------------------------ |
| Request timeout | `5` seconds |
| Redirects | `2` |
| Retry schedule | Immediate, `0.25` seconds, then `1` second |
| Queue worker batch size | `5` jobs |
| Cron fallback | Every 5 minutes |
| Failed queue retention | `7` days |
AI Puffer queues latency-sensitive frontend events so slow endpoints do not slow down the visitor request. This includes chatbot events, `form.submitted`, `content.generated`, and `image.generated` when they are not manual or admin-originated.
Some admin and manual events can be delivered synchronously.
Webhook receivers should be idempotent. Store `X-AIPKit-Idempotency-Key` or `X-AIPKit-Event-Id` and ignore duplicates that were already processed.
### Delivery Issues
Failed queued webhook deliveries appear in **AI Puffer > Settings > Developers**.
The panel shows the five most recent failed webhook jobs. Use **Retry** to run the delivery again, or **Clear** to remove it from the list.
![Webhook Delivery Issues panel with Retry and Clear actions]()
### Test an Endpoint
Use a temporary endpoint during setup.
1. Create a test URL in RequestBin, webhook.site, or a local tunnel.
2. Add the URL as an AI Puffer webhook endpoint.
3. Subscribe it to one event, such as `form.submitted`.
4. Trigger that event in WordPress.
5. Check the received headers and JSON body.
6. Replace the test URL with your production URL.
## Troubleshooting
Check these first:
1. **Event Webhooks** is enabled.
2. The endpoint is enabled.
3. The endpoint URL is correct and reachable from the WordPress server.
4. The endpoint is subscribed to the event you triggered.
5. Your server or firewall is not blocking outbound HTTP requests.
Each endpoint has its own event subscriptions. Edit the endpoint and confirm every expected event is selected.
Verify against the raw request body and `X-AIPKit-Timestamp`.
Common causes:
* The receiver parses and re-stringifies JSON before verification.
* The wrong signing secret is used.
* The receiver includes a different timestamp in the base string.
* The receiver strips or changes the raw body before verification.
Return a quick `2xx` response first, then do longer work in your own queue. AI Puffer waits up to 5 seconds for the endpoint response by default.
Retries can send the same event again. Deduplicate with `X-AIPKit-Idempotency-Key` or `X-AIPKit-Event-Id`.
Open **AI Puffer > Settings > Developers**. Use **Retry** if the endpoint is fixed. Use **Clear** if you no longer need that failed job.
## WordPress Hooks
Use these hooks for custom integrations.
| Hook | Type | Use |
| ------------------------------------------------ | ------ | -------------------------------------------- |
| `aipkit_event_webhooks_envelope` | Filter | Modify the envelope before delivery. |
| `aipkit_event_webhooks_targets` | Filter | Modify endpoint targets for an event. |
| `aipkit_event_webhooks_request_headers` | Filter | Add or modify outgoing request headers. |
| `aipkit_event_webhooks_request_args` | Filter | Modify `wp_remote_post` arguments. |
| `aipkit_event_webhooks_should_retry` | Filter | Change retry behavior for failed attempts. |
| `aipkit_event_webhooks_retry_delays` | Filter | Change retry delays. |
| `aipkit_event_delivery_queue_async_enabled` | Filter | Change whether an event uses async delivery. |
| `aipkit_event_delivery_queue_processing_enabled` | Filter | Enable or disable queue processing. |
| `aipkit_event_webhooks_emitted` | Action | Run code after an event is emitted. |
| `aipkit_event_webhooks_delivery_completed` | Action | Run code after a delivery succeeds. |
| `aipkit_event_webhooks_delivery_failed` | Action | Run code after a delivery fails. |
# Images
Source: https://docs.aipower.org/images
Add image and video generation tools to WordPress.
## Overview
Images adds a frontend generator to a WordPress page. Visitors enter a prompt, choose a provider and model if those controls are visible, and receive the generated media on the page.
Use it for image generation, image editing, Google video generation, logged-in user history, usage limits, logs, and connected app recipes.
In WordPress admin, go to **AI Puffer > Images**. Use the **Image Generator** tab to preview and publish the generator shortcode. Use the **Settings** tab for limits, UI text, custom CSS, and frontend model access.
Open the frontend image generator example.
See which providers support images, edits, and videos.
Let visitors create images from prompts.
Let visitors upload an image and describe changes.
Use Google video models from the frontend generator.
Embed the generator with a shortcode or block.
Configure the Limits, UI Text, Custom CSS, and Frontend Models tabs.
Send generated media events to external apps.
Review image, edit, and video activity.
## Providers
| Provider | Generate images | Edit images | Generate videos | Required setup |
| -------------- | --------------- | --------------------------------------------------- | --------------- | ------------------------------------------------------------------------------- |
| **OpenAI** | Yes | Yes | No | Add an OpenAI API key in **Settings > AI**, then sync models. |
| **Google** | Yes | Yes | Yes | Add a Google API key in **Settings > AI**, then sync image and video models. |
| **OpenRouter** | Yes | Yes, when the model supports image input and output | No | Add an OpenRouter API key in **Settings > AI**, then sync models. |
| **Azure** | Yes | No | No | Add the Azure API key and endpoint in **Settings > AI**, then sync deployments. |
| **xAI** | Yes | Yes | No | Add an xAI API key in **Settings > AI**, then sync image models. |
| **Replicate** | Yes | No | No | Add a Replicate API key in **Settings > Integrations**, then sync models. |
Set up at least one image provider before publishing the generator. If the model list is empty, configure the provider in [AI Providers](/ai-providers), sync models, then return to Images.
xAI image generation and image editing use xAI image models such as `grok-imagine-image`. Generated xAI URLs are temporary, so AI Puffer stores generated images in the WordPress Media Library when possible.
Image editing only works with OpenAI, Google, OpenRouter, and xAI models that support image editing. xAI edit mode accepts JPG/JPEG and PNG source images.
## Generate Images
To generate an image:
1. Open a page that contains the image generator.
2. Select the provider and model if those selectors are visible.
3. Enter the prompt.
4. Click **Generate**.
AI Puffer sends the prompt to the selected provider and displays the returned image in the results area. For logged-in users, generated images are saved to the WordPress Media Library.
![Images frontend generate mode]()
## Edit Images
Use edit mode when visitors should upload an image and describe the change they want.
To enable edit mode from the Images screen:
1. Go to **AI Puffer > Images > Image Generator**.
2. Click the settings icon next to the shortcode.
3. Set **UI Mode** to **Edit only** or **Generate + Edit**.
4. If you choose **Generate + Edit**, choose the **Default Mode** and whether to show the mode switch.
5. Click the shortcode snippet to copy the updated shortcode.
6. Add it to a page.
To edit an image on the frontend:
1. Select **Edit** if the mode switch is visible.
2. Select OpenAI, Google, OpenRouter, or xAI.
3. Select a model that supports editing.
4. Upload one source image.
5. Enter the edit prompt.
6. Click **Edit Image**.
| Upload rule | Value |
| ------------ | ------------------- |
| Files | One source image |
| Types | JPG, PNG, WEBP, GIF |
| xAI types | JPG, PNG |
| Maximum size | 10 MB |
![Images frontend edit mode]()
## Generate Videos
Video generation uses Google video models.
To use it:
1. Go to **AI Puffer > Settings > AI**.
2. Add the Google API key.
3. Sync Google models.
4. Return to **AI Puffer > Images**.
5. Publish the generator shortcode or block.
6. On the frontend, select **Google** and a video model.
7. Enter a prompt and click **Generate**.
Video generation is an async operation. Keep the page open while AI Puffer checks the status. Completed videos are saved as MP4 files in WordPress uploads.
![Images frontend video model]()
## Publish
### Shortcode
Add the basic shortcode to any page, post, or shortcode area:
```text theme={null}
[aipkit_image_generator]
```
Common examples:
```text theme={null}
[aipkit_image_generator mode="both" default_mode="generate"]
[aipkit_image_generator mode="edit"]
[aipkit_image_generator history="true"]
[aipkit_image_generator show_provider="false" show_model="false" provider="openai" model="gpt-image-2"]
[aipkit_image_generator show_provider="false" show_model="false" provider="xai" model="grok-imagine-image"]
[aipkit_image_generator theme="custom"]
```
Use the shortcode settings panel when you want to build the shortcode from the UI.
1. Go to **AI Puffer > Images > Image Generator**.
2. Click the settings icon beside the shortcode.
3. Choose the options you want.
4. Click the shortcode snippet to copy the updated shortcode.
5. Add it to a page or post.
![Images shortcode settings]()
| Option | What it controls |
| ------------------------ | ---------------------------------------------------------------- |
| **Show Provider Select** | Shows or hides the provider dropdown. |
| **Show Model Select** | Shows or hides the model dropdown. |
| **UI Mode** | Generate only, Edit only, or Generate + Edit. |
| **Default Mode** | The first selected mode when both Generate and Edit are enabled. |
| **Show Mode Switch** | Lets visitors switch between Generate and Edit. |
| **Show User History** | Shows previous generated media for logged-in users. |
| **Theme** | Light, Dark, or Custom CSS. |
| Attribute | Values | Default |
| ------------------ | ------------------------------------------------------------- | --------------------------- |
| `show_provider` | `true`, `false` | `true` |
| `show_model` | `true`, `false` | `true` |
| `provider` | `openai`, `google`, `openrouter`, `azure`, `xai`, `replicate` | `openai` |
| `model` | Provider model ID | `gpt-image-2` |
| `mode` | `generate`, `edit`, `both` | `generate` |
| `default_mode` | `generate`, `edit` | `generate` |
| `show_mode_switch` | `true`, `false` | `true` when `mode="both"` |
| `history` | `true`, `false` | `false` |
| `theme` | `dark`, `light`, `custom` | `dark` |
| `allowed_models` | Comma-separated model IDs | Uses global Images settings |
When provider or model selectors are hidden, the shortcode uses the `provider` and `model` attributes as fixed values.
### Block
Use the block when you prefer the block editor.
1. Edit a page or post.
2. Add the **AI Puffer Image Generator** block.
3. Choose whether to show provider and model selectors.
4. Choose the UI mode.
5. Enable history if needed.
6. Choose the theme.
7. Save the page.
![Images block in the WordPress block editor]()
The block renders the same generator as the shortcode.
### User History
History shows previously generated images and videos for logged-in users.
To enable it, turn on **Show User History** in the shortcode settings panel, enable history in the block, or add `history="true"` to the shortcode.
| Action | Availability |
| ----------------- | -------------------------------------- |
| Open media | Images and videos |
| Delete media | Media owner or admin |
| Edit from history | Images only, when edit mode is enabled |
Guest generations are not shown in user history.
![Images user history]()
## Settings
Open **AI Puffer > Images > Settings**.
The Settings screen is split into tabs.
| Tab | What it contains |
| ------------------- | ----------------------------------------------------------- |
| **Limits** | Guest, user, role, reset, and quota message settings. |
| **UI Text** | Frontend labels, placeholders, hints, and empty-state text. |
| **Custom CSS** | CSS for generators using the custom theme. |
| **Frontend Models** | Models visitors can select on the frontend. |
![Images Settings]()
### Limits
Limits control how much image generator usage is allowed for guests and logged-in users.
Open **Limits**.
1. Set **Guest quota**.
2. Choose **Quota mode** for logged-in users.
3. Set **User quota** or **Role-based quotas**.
4. Choose **Reset period**.
5. Edit **Quota reached message**.
6. Configure optional primary and secondary buttons.
| Value | Meaning |
| --------------- | ------------------------------------------ |
| Empty | Unlimited |
| `0` | Disabled |
| Positive number | Maximum allowed usage for the reset period |
Reset periods are **Never**, **Daily**, **Weekly**, and **Monthly**.
For credit-based image access, define pricing rules in [Usage](/usage#pricing-rules). To sell prepaid credits, create WooCommerce credit packages in [Usage](/usage#woocommerce-credit-packages).
### UI Text
UI Text changes the frontend labels without editing code.
Open **UI Text**.
| Field | Default |
| ------------------------------- | ------------------------------------------------------- |
| **Generate button label** | Generate |
| **Edit button label** | Edit Image |
| **Mode tab label (Generate)** | Generate |
| **Mode tab label (Edit)** | Edit |
| **Generate prompt placeholder** | Describe the image you want to generate... |
| **Edit prompt placeholder** | Describe how you want to edit the uploaded image... |
| **Source image label** | Source image |
| **Upload dropzone title** | Drop image here or click to upload |
| **Upload dropzone meta** | JPG, PNG, WEBP, GIF up to 10MB |
| **Upload hint** | Upload an image, then describe the edits in the prompt. |
| **History title** | Your Images |
| **Results empty text** | Generated images will appear here. |
### Custom CSS
Custom CSS applies to generators using the custom theme.
Open **Custom CSS**.
Use the custom theme in the shortcode:
```text theme={null}
[aipkit_image_generator theme="custom"]
```
Then target the custom wrapper:
```css theme={null}
.aipkit_image_generator_public_wrapper.aipkit-theme-custom {
/* custom styles */
}
```
### Frontend Models
Frontend Models controls which models visitors can select when the frontend provider or model selectors are visible.
Open **Frontend Models**.
1. Select the models visitors can use.
2. Leave all models unselected if you want to allow every configured image and video model.
3. Save the settings.
AI Puffer builds the frontend provider list from the selected allowed models. For example, if you only select OpenAI models, the frontend provider selector only shows OpenAI.
You can override the global setting for one page with the `allowed_models` shortcode attribute.
## Connected Apps
Connected Apps can run a recipe after a successful image or video generation.
1. Go to **AI Puffer > Settings > Apps**.
2. Connect the app or webhook destination.
3. Create a recipe that uses the **Image Generated** event.
4. Publish the image generator on a page.
5. Generate an image or video to test the recipe.
AI Puffer emits `image.generated` after the output is complete. For payload fields, see [Event Webhooks](/event-webhooks).
## Logs
Image and video requests are logged with the module set to `image_generator`.
Logs can include the prompt, provider, model, mode, usage, WordPress user, guest session, and edit source image metadata. Source image binary data is not stored in the log.
Usage operations:
| Operation | Used for |
| ---------------- | ----------------------- |
| `generate` | Image generation |
| `edit` | Image editing |
| `video_generate` | Google video generation |
## Troubleshooting
Check that Images is enabled in **AI Puffer > Settings > Modules** and that the shortcode is on a published page. Admin users may see a module-disabled message; visitors see empty output.
Configure the provider in **AI Puffer > Settings > AI** or **Settings > Integrations**, sync models, then reload the Images screen. If Frontend Models is restricted, confirm that the selected models still exist.
Use OpenAI, Google, or OpenRouter. The selected model must support image editing, and the visitor must upload one JPG, PNG, WEBP, or GIF image under 10 MB.
Google video generation can take time. Keep the page open while AI Puffer checks the operation status. If it times out, try a shorter prompt and review the related log entry.
History only appears for logged-in users. Enable **Show User History** in the shortcode settings panel, enable history in the block, or add `history="true"` to the shortcode.
Open **AI Puffer > Images > Settings > Limits** and review the guest, user, or role-based quota. If you sell credits, also check the user's balance and the pricing rules in [Usage](/usage).
# Introduction
Source: https://docs.aipower.org/index
AI Puffer documentation for WordPress modules, providers, knowledge, and usage.
AI Puffer is a WordPress plugin that adds AI tools to your website and admin area.
You connect your own AI provider keys, choose which model each feature should use, and use the tools through WordPress pages, shortcodes, blocks, products, and scheduled tasks.
You can use AI Puffer to add a chatbot, write posts and product content, build AI forms, generate images, run recurring automations, index knowledge sources, and track usage.
The main modules are Chatbots, Content Writer, Automations, AI Forms, Images, Knowledge Base, and Usage. Each module has its own settings, but they share the same provider connections and usage records.
Use **AI Puffer > Settings > Modules** to choose which modules appear in the AI Puffer navigation.
## Modules
Create popup, embedded, and external chatbots.
Generate and optimize posts, pages, and products.
Run scheduled content, rewrite, indexing, and product tasks.
Build forms that send structured input to AI.
Add image, edit, and video generation tools.
Add site content, files, and vectors for retrieval.
Track usage, set limits, and sell credits.
Use AI tools inside post lists and editors.
AI Puffer supports providers and services such as OpenAI, Google, Azure, OpenRouter, xAI, DeepSeek, Ollama, Anthropic, ElevenLabs, Replicate, Pinecone, Qdrant, and Chroma. Availability depends on the module and the provider features you enable.
Usage records requests made through the plugin. It can be used for logs, limits, pricing rules, user balances, and WooCommerce credit packages.
# Installation
Source: https://docs.aipower.org/installation
Install the free plugin or upload the Pro plugin ZIP file.
AI Puffer can be installed from the WordPress plugin directory or uploaded as a ZIP file.
Use the free version first if you want to test the plugin before buying Pro. Use the Pro ZIP file if you already purchased a license.
Install from the WordPress plugin directory.
Upload a plugin ZIP file from WordPress.org, your purchase email, or the User Portal.
## Install the free version
1. Open your WordPress admin dashboard.
2. Go to **Plugins > Add New**.
3. Search for **AI Puffer**.
4. Click **Install Now**.
5. Click **Activate** after the installation finishes.
![AI Puffer in the WordPress Add Plugins search results]()
If the button says **Active**, the plugin is already installed and active on that site.
After activation, open **AI Puffer** from the WordPress admin menu.
## Upload a plugin ZIP file
Use this method if you downloaded the plugin ZIP from WordPress.org, your purchase email, or the User Portal.
1. Open your WordPress admin dashboard.
2. Go to **Plugins > Add New**.
3. Click **Upload Plugin**.
4. Choose the plugin ZIP file.
5. Click **Install Now**.
6. Click **Activate Plugin**.
![WordPress Upload Plugin screen]()
Upload the `.zip` file directly. Do not unzip the plugin before uploading it to WordPress.
## Upgrade from Free to Pro
You can upgrade from inside WordPress or from the AI Puffer website.
### From WordPress
1. Install and activate the free version.
2. Open **AI Puffer** in the WordPress admin menu.
3. Click **Upgrade**.
4. Choose your license.
5. Complete checkout.
![AI Puffer Upgrade link in the WordPress admin menu]()
After checkout, you will receive an email with your license key and the Pro plugin download link.
### From the website
1. Open the [AI Puffer pricing page](https://aipower.org/pricing/).
2. Choose a license.
3. Complete checkout.
4. Check your email for the license key and Pro plugin download link.
## Safari ZIP setting
If you use Safari on macOS, make sure Safari does not automatically unzip downloaded files.
1. Open Safari.
2. Go to **Safari > Settings**.
3. Open the **General** tab.
4. Turn off **Open "safe" files after downloading**.
WordPress needs the `.zip` file. If Safari already extracted it, download the file again after changing this setting.
# Knowledge Base
Source: https://docs.aipower.org/knowledge-base
Add and manage source data for AI Puffer retrieval.
## Overview
Knowledge Base stores the content AI Puffer can search before it generates an answer or a piece of content.
Use it for support answers, product details, documentation, policies, posts, pages, WooCommerce products, uploaded documents, and other source text you want AI Puffer to use as context.
Use OpenAI Vector Stores, Pinecone, Qdrant, or Chroma.
Create, select, or delete vector targets.
Add data and manage source records.
Configure chunking, batches, content rules, semantic search, and other settings.
Publish and configure a frontend vector search form.
Fix missing targets, dimension errors, and empty results.
## Providers
| Provider | Target name | How it works |
| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| **OpenAI** | Vector store | AI Puffer sends the source data to OpenAI Vector Stores. No separate embedding model is selected in AI Puffer for this target. |
| **Pinecone** | Index | AI Puffer creates embeddings with the model you choose, then stores the vectors in a Pinecone index. |
| **Qdrant** | Collection | AI Puffer creates embeddings with the model you choose, then stores the vectors in a Qdrant collection. |
| **Chroma** | Collection | AI Puffer creates embeddings with the model you choose, then stores the vectors in a Chroma collection. |
For Pinecone, Qdrant, and Chroma, the index or collection dimension must match the embedding model.
For example, if your Pinecone index, Qdrant collection, or Chroma collection is **3072 dimensions**, use a **3072-dimension** embedding model when adding data and when searching that data later.
If the dimension does not match, the vector provider can reject the data or return unusable search results.
### OpenAI
OpenAI Vector Stores use your OpenAI account directly.
1. Go to **AI Puffer > Settings > AI**.
2. Select **OpenAI** as the AI provider.
3. Enter your OpenAI API key.
4. Sync models if needed.
5. Go to **AI Puffer > Knowledge Base > Stores** to create or refresh OpenAI vector stores.
OpenAI Vector Stores do not require a separate embedding model selection in Knowledge Base. OpenAI handles file storage, chunking, embedding, and vector search on its side.
![OpenAI API key settings]()
### Pinecone
Pinecone is configured from the Integrations settings.
1. Go to **AI Puffer > Settings > Integrations**.
2. Select **Pinecone**.
3. Enter your **Pinecone API Key**.
4. Click **Sync Indexes** to load indexes from Pinecone.
5. Go to **AI Puffer > Knowledge Base > Stores** to create, refresh, or delete indexes.
When you create a Pinecone index in AI Puffer, enter the dimension that matches the embedding model you plan to use.
![Pinecone API key]()
### Qdrant
Qdrant requires both an endpoint URL and an API key.
1. Go to **AI Puffer > Settings > Integrations**.
2. Select **Qdrant**.
3. Enter your **Qdrant URL**.
4. Enter your **Qdrant API Key**.
5. Click **Sync Collections** to load collections from Qdrant.
6. Go to **AI Puffer > Knowledge Base > Stores** to create, refresh, or delete collections.
When you create a Qdrant collection in AI Puffer, enter the dimension that matches the embedding model you plan to use.
![Qdrant API key]()
### Chroma
Chroma uses endpoint, tenant, and database settings.
1. Go to **AI Puffer > Settings > Integrations**.
2. Select **Chroma**.
3. Enter your **Chroma URL**. For Cloud, you can use [https://api.trychroma.com](https://api.trychroma.com)
4. Enter your **Chroma API Key** if you use Chroma Cloud or an authenticated server.
5. Enter the **Tenant**.
6. Enter the **Database**.
7. Click **Sync Collections** to load collections from Chroma.
8. Go to **AI Puffer > Knowledge Base > Stores** to create, refresh, or delete collections.
For local Chroma, the default tenant is `default_tenant` and the default database is `default_database`.
![Chroma API key]()
### Embedding Providers
Pinecone, Qdrant, and Chroma store vectors that AI Puffer creates with a selected embedding model. Before adding data to these providers, configure the embedding provider you want to use in **AI Puffer > Settings > AI**.
Supported embedding providers include OpenAI, Google, Azure, and OpenRouter. The selected embedding model must match the dimension of the Pinecone index, Qdrant collection, or Chroma collection.
xAI is not an embedding provider or vector store provider in the current integration. xAI chatbots, forms, and text workflows can still use retrieved Knowledge Base context from OpenAI, Pinecone, Qdrant, or Chroma because AI Puffer sends that context as text.
## Manage Vector Stores
Use **AI Puffer > Knowledge Base > Stores** to create, refresh, inspect, or delete vector targets.
The Stores tab is where you manage OpenAI vector stores, Pinecone indexes, Qdrant collections, and Chroma collections. The Data tab uses these targets when you add content.
![Knowledge Base provider selector]()
### OpenAI Vector Stores
1. Add your OpenAI API key in **AI Puffer > Settings > AI**.
2. Go to **AI Puffer > Knowledge Base > Stores**.
3. Select **OpenAI** as the provider.
4. Click **Create Store**.
5. Enter a store name.
6. Click **Create**.
OpenAI handles the vector store search on its side. AI Puffer stores a local source record so you can see what was added.
![OpenAI Create Vector]()
### Pinecone Indexes
1. Add your Pinecone API key in **AI Puffer > Settings > Integrations**.
2. Go to **AI Puffer > Knowledge Base > Stores**.
3. Select **Pinecone** as the provider.
4. Select the embedding model you plan to use.
5. Click **Create Store**.
6. Enter an index name.
7. Enter the dimension for the selected embedding model.
8. Click **Create**.
Use the same embedding model when you add data to the index and when a module searches that index.
![Pinecone Create Index]()
### Qdrant Collections
1. Add your Qdrant URL and API key in **AI Puffer > Settings > Integrations**.
2. Go to **AI Puffer > Knowledge Base > Stores**.
3. Select **Qdrant** as the provider.
4. Select the embedding model you plan to use.
5. Click **Create Store**.
6. Enter a collection name.
7. Enter the dimension for the selected embedding model.
8. Click **Create**.
Use the same embedding model when you add data to the collection and when a module searches that collection.
![Qdrant Create collection]()
### Chroma Collections
1. Add your Chroma endpoint, tenant, database, and API key in **AI Puffer > Settings > Integrations**.
2. Go to **AI Puffer > Knowledge Base > Stores**.
3. Select **Chroma** as the provider.
4. Click **Create Store**.
5. Enter a collection name.
6. Click **Create**.
Chroma collections do not require a dimension when they are created in AI Puffer. Use the same embedding model when you add data to the collection and when a module searches that collection.
![Chroma Create collection]()
Use **Refresh** when you need AI Puffer to fetch the latest stores, indexes, or collections from the selected provider.
To delete a target, use the available action in the Stores table.
## Add Data
Use **AI Puffer > Knowledge Base > Data** to add new source data and manage existing source records.
Before adding data:
1. Go to **AI Puffer > Knowledge Base > Data**.
2. Select a provider.
3. Select the target vector store, index, or collection.
4. For Pinecone, Qdrant, or Chroma, select the embedding model.
5. Click **+ Add Data**.
![Knowledge Base Add data panel]()
### Q\&A
Use Q\&A for short answers that should be easy to retrieve later.
1. Select **Q\&A**.
2. Enter the question.
3. Enter the answer.
4. Click **Add Q\&A**.
AI Puffer stores the pair as text:
```text theme={null}
Q: question text
A: answer text
```
![Knowledge Base Q&A tab]()
### Text
Use Text for policies, instructions, product notes, support snippets, or any source text that does not already exist as WordPress content.
1. Select **Text**.
2. Paste the source text.
3. Click **Add Text**.
![Knowledge Base Text tab]()
### Files
Use Files when the source is already in a document.
1. Select **Files**.
2. Click **Choose files**.
3. Select one or more files.
Files start uploading and training after selection.
Supported file extensions:
```text theme={null}
.pdf, .docx, .txt, .md, .csv, .json
```
For Pinecone, Qdrant, and Chroma, AI Puffer extracts text, splits large files into chunks, creates embeddings, and stores each chunk in the selected index or collection. File chunks can be embedded in batches to reduce the number of embedding API requests.
File size is limited by your WordPress/PHP upload settings. OpenAI Vector Store uploads also use OpenAI's file limits.
![Knowledge Base Files tab]()
### Website
Use Website when the source is WordPress content.
1. Select **Website**.
2. Choose **All** or **Choose items**.
3. Select the content types.
4. If using **Choose items**, select the individual published items.
5. Click **Add Items**.
Website training uses published content. Posts and pages are selected by default. WooCommerce products appear when WooCommerce is active. Public custom post types can also appear.
When WordPress content is indexed, AI Puffer builds the source text from the URL, title, excerpt, content, public custom fields, public taxonomies, and available WooCommerce product data.
![Knowledge Base Website all mode]()
### Manage Data
The source table in the Data tab shows the local records created while adding data.
| Column | What it shows |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Status** | Trained, Processing, Failed, or another provider status. |
| **Item** | Post title, text preview, file name, or source identifier. Provider, target, and embedding details appear below the item name. |
| **Type** | Site Content, Text, Q\&A, File Upload, or User Upload. |
| **Updated** | Last update time and relative age. |
| **Actions** | Available actions for the source. |
![Knowledge Base source table]()
Available actions:
| Action | Use it for |
| ----------- | ----------------------------------------------------------------------------- |
| **View** | Review the stored source preview. |
| **Edit** | Edit a text source and save it again. |
| **Retrain** | Re-index a WordPress content source after the content changes. |
| **Delete** | Remove the source from the external provider and from the local source table. |
![Knowledge Base source table]()
![Knowledge Base source preview]()
## Settings
Open **AI Puffer > Knowledge Base > Settings** to configure Knowledge Base behavior.
The Settings screen is split into tabs.
| Tab | What it contains |
| ----------------- | ------------------------------------------------------ |
| **Chunking** | Document chunking controls. |
| **Batches** | Embedding batch controls. |
| **Content Rules** | Rules for which WordPress content fields are embedded. |
| **Others** | Semantic Search and user upload visibility. |
### Chunking
Document chunking controls how AI Puffer splits large uploaded files and WordPress Website content before embedding them for Pinecone, Qdrant, or Chroma.
| Setting | Default | Range | Use it for |
| ------------------------ | ------- | --------------- | ----------------------------------------------------------------------------- |
| **Avg chars per token** | `4` | `2` to `4` | Estimates how many characters equal one token. |
| **Max tokens per chunk** | `3000` | `256` to `6000` | Sets the maximum chunk size before embedding. |
| **Overlap tokens** | `150` | `0` to `1000` | Repeats a small part of the previous chunk so context does not break sharply. |
Use smaller chunks when an embedding provider rejects long input. Keep some overlap for long documents where meaning continues across sections. Some embedding models have lower hard limits than the visible maximum, so AI Puffer may apply a safer model-specific cap during indexing.
OpenAI Vector Store file uploads use OpenAI File Search chunking instead of the Pinecone, Qdrant, and Chroma chunking settings above.
| OpenAI File Search setting | Default | Range | Use it for |
| -------------------------- | ------- | ----------------------------- | ----------------------------------------------------------------------------------------- |
| **Indexing strategy** | `Auto` | `Auto` or `Custom` | Lets OpenAI choose chunking automatically, or lets AI Puffer send custom chunking values. |
| **Max chunk size tokens** | `800` | `100` to `4096` | Sets the maximum OpenAI File Search chunk size when **Custom** is selected. |
| **Chunk overlap tokens** | `400` | `0` to half of max chunk size | Repeats part of the previous OpenAI File Search chunk when **Custom** is selected. |
![Knowledge Base Batches settings]()
### Batches
The **Batches** tab contains **Embedding Batches**, which controls how many file chunks AI Puffer sends to the embedding provider in one request.
1. Go to **AI Puffer > Knowledge Base > Settings**.
2. Open **Batches**.
3. Adjust the batch size for the embedding provider you use.
4. Wait for the settings autosave to finish.
If the Batches tab shows **Upgrade**, activate Pro before saving batch settings.
| Provider | Default | Maximum |
| -------------- | ------- | ------- |
| **Google** | `100` | `100` |
| **OpenAI** | `50` | `100` |
| **OpenRouter** | `50` | `100` |
| **Azure** | `50` | `100` |
| **Ollama** | `10` | `100` |
![Knowledge Base Batches settings]()
For example, a batch size of `50` means AI Puffer sends up to 50 prepared file chunks to the embedding API at once. Larger batches can make file upload training much faster because they reduce repeated API calls.
Embedding batch settings apply only to chunked file uploads for Pinecone, Qdrant, and Chroma. Website training uses document chunking, but these batch-size settings do not change Q\&A, Text, Website training, semantic search queries, or OpenAI Vector Store file uploads.
If a provider returns rate limit errors such as HTTP `429`, lower that provider's batch size and try again. AI Puffer can pause and retry file upload processing when the provider sends a retry delay, but lowering the batch size is usually better for accounts with stricter quotas.
### Content Rules
Content Rules define which WordPress fields are included when Website training or list-screen indexing sends WordPress content to a vector target.
1. Go to **AI Puffer > Knowledge Base > Settings**.
2. Open **Content Rules**.
3. Click **Configure**.
4. Select a post type.
5. Adjust **Basic Labels** if you want different labels for source URL, title, excerpt, or content.
6. Enable or disable custom fields.
7. Enable or disable taxonomies.
8. For WooCommerce products, enable or disable product data such as SKU, price, stock, dimensions, and attributes.
9. Save.
If the Save button shows **Upgrade**, activate Pro before saving indexing rules.
![Knowledge Base indexing controls]()
### Others
Open **AI Puffer > Knowledge Base > Settings**, then open **Others**.
The Others tab contains Semantic Search and admin visibility settings.
#### Semantic Search
Semantic Search publishes a search form that queries a Pinecone index, Qdrant collection, or Chroma collection from the frontend.
In **Others**, click **Configure** in the **Semantic Search** row.
1. Select **Vector DB**: Pinecone, Qdrant, or Chroma.
2. Select the index or collection.
3. Select the embedding model.
4. Set **Number of Results**.
5. Set **No Results Text**.
6. Test a query in **Try semantic search**.
7. Copy the shortcode.
```text theme={null}
[aipkit_semantic_search]
```
Semantic Search uses the global settings from this panel. It does not use OpenAI Vector Stores in the current UI.
Use the same embedding model that was used when the Pinecone, Qdrant, or Chroma data was added.
![Knowledge Base Semantic Search settings]()
#### Admin Visibility
| Setting | What it does |
| --------------------- | ----------------------------------------------------------------------- |
| **Hide user uploads** | Hides chatbot upload records from the main Knowledge Base source table. |
The post-list **Index** button is managed from **AI Puffer > Settings > Utilities**. See [WordPress Utilities](/wordpress-utilities#content-indexing).
| Control | What it does |
| ------------------------------ | ---------------------------------------------- |
| **Index Status** column | Shows whether a post has already been indexed. |
| **Index Status** filter | Filters content by indexed or not indexed. |
| **Add to Vector Store** action | Sends selected posts to a vector target. |
## Troubleshooting
Configure the provider credentials, then sync or create the vector target again.
Confirm the embedding model dimension matches the index or collection dimension.
Check **Knowledge Base > Settings > Content Rules** for that post type.
Enable **AI Puffer > Settings > Utilities > Index button** and confirm the user role can access the vector content indexer module.
Confirm the selected target contains trained data and the same embedding model is selected.
# Pro Activation
Source: https://docs.aipower.org/pro-activation
Install the Pro plugin and activate your license key.
After purchasing Pro, Freemius sends the plugin download link and license key by email.
If you bought a monthly or annual license, you usually receive two emails:
| Email | Contains |
| -------------- | ------------------------------------------ |
| Download email | Pro plugin ZIP file and license key. |
| Receipt email | Payment receipt and invoice download link. |
Lifetime purchases may arrive as one email that includes the download link, license key, receipt, and invoice.
## Download the Pro ZIP file
1. Open the purchase email.
2. Download the Pro plugin ZIP file.
3. Keep the license key available. You will need it after activation.
Do not unzip the file before uploading it to WordPress.
## Upload the Pro plugin
1. Open your WordPress admin dashboard.
2. Go to **Plugins > Add New**.
3. Click **Upload Plugin**.
4. Choose the Pro plugin ZIP file.
5. Click **Install Now**.
6. Click **Activate Plugin**.
## Activate the license
If you upgraded from inside WordPress, the license may already be activated.
If the activation screen appears:
1. Paste the license key from your email.
2. Click **Agree & Activate License**.
3. Wait for the confirmation message.
After activation, the licensed plugin options become available in the plugin settings.
## Download an older version
Older versions are available from the User Portal.
1. Open the [User Portal](https://users.freemius.com/downloads).
2. Go to **Downloads**.
3. Find AI Puffer.
4. Open the version menu next to the download button.
5. Download the version you need.
Use older versions only when you need to test or roll back a specific issue.
# Usage
Source: https://docs.aipower.org/usage
Review logs, manage credits, define pricing rules, and sell credit packages.
## Overview
Usage is where you review saved AI activity and manage AI Puffer credits.
In WordPress admin, go to **AI Puffer > Usage**.
The screen has two tabs: **Logs** and **Billing**. Logs are for reviewing saved requests and conversations. Billing is for pricing rules, ledger activity, user balances, and WooCommerce credit packages.
AI Puffer credits are internal plugin credits. They do not replace OpenAI, Google, Anthropic, xAI, Replicate, or other provider billing. Provider API usage is still billed by the provider account you connect.
Search, inspect, export, delete, and retain saved activity.
Define how model usage is converted into AI Puffer credits.
Review credits added, debited balances, and usage entries.
Edit user balances and reset periodic usage.
Sell credit packages and publish a customer dashboard.
Check common setup and billing issues.
![Usage screen with Logs and Billing tabs]()
Key terms:
| Term | Meaning |
| ---------------- | ---------------------------------------------------------------- |
| **Credit** | An internal AI Puffer unit stored on a logged-in user's account. |
| **Balance** | The user's available prepaid credits. |
| **Quota** | A periodic usage limit for guests, users, or roles. |
| **Pricing rule** | A rule that turns model usage into credits. |
| **Ledger** | A record of purchases, admin balance changes, and usage. |
## Logs
Open **AI Puffer > Usage > Logs**.
Logs show saved activity from AI Puffer modules. Use them to review conversations, inspect request metadata, check vector search results, export records, and control retention.
### Conversation Logs
Conversation logs store the saved message history for chatbot and other AI requests. Use filters to find the records you need, then open a row to inspect the full exchange.
| Control | Use it for |
| --------------- | -------------------------------------------- |
| **Search logs** | Search saved log content. |
| **Chatbot** | Show all bots, one bot, or logs with no bot. |
| **Module** | Filter by module. |
| **Date range** | Show the last 7, 30, or 90 days. |
| **Export logs** | Download matching logs as a CSV file. |
| **Delete logs** | Delete logs matching the active filters. |
Click a row to open **Conversation Details**. The detail panel shows the full exchange, timestamps, provider and model metadata, usage tokens, request payloads when saved, and a delete button for that single log.
![Usage logs with filters and conversation details]()
### Vector Scores
When a chatbot, Content Writer request, or other AI request uses vector context, the assistant message can show a **Score** badge.
The score shows how closely the retrieved content matched the user's request. Click the badge to see the vector provider, source, score, and content preview.
Use scores to tune Knowledge Base retrieval. If useful content is not being used, lower the threshold or increase the result limit. If unrelated content is used, raise the threshold.
| Score | Meaning |
| ------------- | ------------------------------------------------------ |
| **85%+** | Strong match. |
| **70-84%** | Usually useful. |
| **50-69%** | Weak match. Review the source text. |
| **Below 50%** | Poor match. The answer may be using unrelated context. |
Scores explain retrieval quality. They do not grade the final AI answer.
![Conversation details with vector score results]()
### Export and Delete
To export logs:
1. Open **AI Puffer > Usage > Logs**.
2. Apply filters if needed.
3. Open the actions menu.
4. Click **Export logs**.
The CSV includes log ID, date, user, source, module, message count, token count, preview, and conversation UUID.
To delete logs:
1. Open **AI Puffer > Usage > Logs**.
2. Apply filters if you only want to delete part of the log history.
3. Open the actions menu.
4. Click **Delete logs**.
5. Confirm the action.
To delete one conversation, open the row and click **Delete** in Conversation Details.
### Log Retention
Log retention automatically removes old logs.
To configure it:
1. Open **AI Puffer > Usage > Logs**.
2. Click **Set retention**.
3. Enable **Auto-delete logs**.
4. Choose **Delete logs older than**.
5. Save the setting.
Available retention periods:
```text theme={null}
1 day
3 days
7 days
15 days
30 days
60 days
90 days
6 months
1 year
```
The retention modal also shows the pruning schedule and last run time.
![Log Retention modal]()
## Billing
Open **AI Puffer > Usage > Billing**.
Billing connects three things:
1. **Pricing rules** decide how much a request costs in AI Puffer credits.
2. **Balances** store prepaid credits for logged-in users.
3. **Quotas** limit usage for guests, users, or roles when a balance is not enough.
For logged-in users, AI Puffer deducts from the credit balance first. If the balance does not cover the full request cost, the remaining usage is counted against the user's quota. For guests, there is no persistent balance, so usage is checked against the guest quota.
Quotas are configured inside the module that uses them: Chatbots, AI Forms, or Images. The Usage screen shows and resets recorded usage, but it is not where you configure module limits.
### Pricing
Open **AI Puffer > Usage > Billing > Pricing**.
Pricing rules tell AI Puffer how many credits a model operation should cost.
#### How Pricing Works
Credits are internal AI Puffer units. You decide how many credits each request should cost.
Use **Flat** when every request should cost the same amount. Use **Per 1K Tokens** when longer chat or form requests should cost more. Use **Per Image** or **Per Video** for media tools.
For chat and AI forms, tokens are the pieces of text sent to and returned from the AI provider. **Input tokens** are the user message, instructions, and context sent to the model. **Output tokens** are the AI response.
For xAI text requests, pricing rules use the token usage returned by the xAI response when it is available. For xAI image generation and image editing, AI Puffer records provider usage metadata when xAI returns it, but credit deduction still follows your configured image pricing rule such as **Per Image** or **Flat**.
Example token rule:
| Field | Value |
| ----------- | ------------------------------ |
| Input rate | 1 credit per 1K input tokens |
| Output rate | 2 credits per 1K output tokens |
If a request uses 800 input tokens and 300 output tokens:
| Usage | Calculation | Cost |
| ------ | -------------- | ----------- |
| Input | 800 / 1000 x 1 | 0.8 credits |
| Output | 300 / 1000 x 2 | 0.6 credits |
| Total | 0.8 + 0.6 | 1.4 credits |
AI Puffer rounds the result up, so this request is charged as **2 credits**.
Example flat rule:
| Field | Value |
| -------------- | --------- |
| Billing method | Flat |
| Unit rate | 5 credits |
Every matching request costs **5 credits**, no matter how long the prompt or response is.
To create a pricing rule:
1. Click **New Pricing**.
2. Select **Usage type**.
3. Select **Provider & Model**.
4. Select **Billing method**.
5. Enter the rate.
6. Click **Save Rule**.
![Billing Pricing tab]()
![New Pricing rule modal]()
Supported usage types:
| Module | Usage type |
| ------------------- | --------------------- |
| **Chatbot** | Chat |
| **AI Forms** | Form Submit |
| **Image Generator** | Generate, Edit, Video |
Supported billing methods:
| Billing method | Applies to | Rate field |
| ----------------- | ---------------------------------- | -------------------------------- |
| **Per 1K Tokens** | Chat and AI Forms | Input rate and output rate. |
| **Per Image** | Image generation and image editing | Unit rate per image. |
| **Per Video** | Video generation | Unit rate per video. |
| **Flat** | Any supported usage type | One fixed unit rate per request. |
Pricing rules can be enabled, disabled, edited, or deleted from the Pricing table.
If a matching pricing rule exists, AI Puffer uses that rule to estimate and record credit usage. If no rule matches, it falls back to the raw recorded usage units.
### Activity
Open **AI Puffer > Usage > Billing > Activity**.
Activity shows the ledger for the selected time range.
Available ranges:
```text theme={null}
Last 7 days
Last 30 days
Last 90 days
```
Summary cards:
| Card | Meaning |
| -------------------- | ----------------------------------------------------- |
| **Credits Added** | Credits added through purchases or admin adjustments. |
| **Balance Debited** | Credits deducted from user balances. |
| **Quota-Only Usage** | Usage that did not deduct a balance. |
| **Ledger Entries** | Total ledger records in the selected range. |
The ledger table shows time, actor, type, module/model, credit change, and usage units.
![Billing Activity tab]()
### Balances
Open **AI Puffer > Usage > Billing > Balances**.
Balances is for logged-in WordPress users. Use it to search users, edit credit balances, review periodic usage, reset usage, and view purchase history.
The table includes:
| Column | Meaning |
| ------------------ | ----------------------------------------------- |
| **User** | Display name and email. |
| **Credit Balance** | Editable prepaid credit balance. |
| **Usage** | Recorded periodic usage and active scopes. |
| **Latest Reset** | Most recent usage reset time. |
| **Actions** | Details, Reset all, and History when available. |
To edit a balance:
1. Search for the user.
2. Edit **Credit Balance**.
3. Press **Enter** or click outside the field.
AI Puffer saves the new balance and records the difference as an admin adjustment in the ledger.
To reset usage:
1. Click **Details** for a user.
2. Click **Reset usage** for one scope, or **Reset all** for all scopes.
3. Confirm the reset.
Resetting usage does not change the user's credit balance.
![Billing Balances tab]()
![Billing Balances tab with periodic usage details]()
### WooCommerce Integration
Open **AI Puffer > Usage > Billing > WooCommerce**.
Use this tab to publish a customer dashboard and connect WooCommerce products to AI Puffer credits.
WooCommerce credit delivery requires a WordPress user account. Guest checkout orders without a linked user cannot receive credits automatically.
Customer dashboard:
1. Create a WordPress page, such as **Credits & Usage**.
2. Add this shortcode:
```text theme={null}
[aipkit_token_usage]
```
3. Publish the page.
4. Open **AI Puffer > Usage > Billing > WooCommerce**.
5. Set **Customer dashboard URL** to that page.
6. Set **Default buy credits URL** if you want dashboard buttons and quota messages to send users to a specific page.
The dashboard shows credit balance, recent purchases, and quota usage for Chatbots, AI Forms, and Images.
![Billing WooCommerce tab]()
Shortcode options:
| Attribute | Default | Use it for |
| ----------------- | ------------------------------------------- | ------------------------------------- |
| `chatbot` | `true` | Show or hide chatbot quota usage. |
| `aiforms` | `true` | Show or hide AI Forms quota usage. |
| `imagegenerator` | `true` | Show or hide Images quota usage. |
| `title` | `Credits & Usage` | Dashboard title. |
| `intro` | `View your credits, purchases, and quotas.` | Intro text. |
| `buycredits` | `true` | Show or hide the buy credits button. |
| `buycreditslabel` | `Buy credits` | Buy credits button label. |
| `buycreditsurl` | Empty | Override the buy credits URL. |
| `purchasehistory` | `true` | Show or hide recent purchase history. |
Examples:
```text theme={null}
[aipkit_token_usage chatbot="false"]
[aipkit_token_usage title="Credits" intro="View your balance and usage."]
[aipkit_token_usage buycreditslabel="Buy more credits" buycreditsurl="https://example.com/credits"]
```
Credit packages:
1. Open **WooCommerce > Products**.
2. Create or edit a product.
3. Find the **AI Puffer: Credit Package** box.
4. Enable **Sell this product as an AI Puffer credit package**.
5. Enter **Credits Granted Per Quantity**.
6. Set the normal WooCommerce product price.
7. Publish or update the product.
Credits are granted when the WooCommerce order becomes **Completed**. Quantity is multiplied by **Credits Granted Per Quantity**.
![AI Puffer credit package box in WooCommerce product editor]()
If pricing rules exist, the product editor can show a rough package value, such as how many chat requests, form submissions, images, or videos the package may cover at current pricing.
Package previews are for sizing only. The real cost depends on the actual provider response, token usage, selected model, and matching pricing rule.
## Troubleshooting
1. Open [AI Providers](/ai-providers).
2. Confirm the provider API settings are saved.
3. Sync models for that provider.
4. Return to **Usage > Billing > Pricing** and create the rule again.
Check these items:
| Check | Expected value |
| ------------------------ | -------------------------------------- |
| WooCommerce order status | Completed. |
| Order user | Linked to a WordPress user account. |
| Product setting | Marked as an AI Puffer credit package. |
| Credit amount | Greater than `0`. |
1. Confirm the visitor is logged in.
2. Confirm the page contains `[aipkit_token_usage]`.
3. Check role access if role access is enabled.
4. Confirm the related module has recorded usage for that user.
5. Confirm the shortcode attribute for that module is not set to `false`.
Check these items:
1. Confirm the WooCommerce order is completed.
2. Confirm the user's credit balance increased in **Usage > Billing > Balances**.
3. Confirm the user is logged in.
4. Confirm the module has a matching pricing rule.
5. Confirm the request cost does not exceed the user's remaining balance plus available quota.
1. Open **Usage > Logs**.
2. Click **Set retention**.
3. Enable **Auto-delete logs**.
4. Choose a shorter retention period.
5. Delete old logs manually if needed.
1. Open **Usage > Billing > Activity**.
2. Select a date range that includes the change.
3. Check whether the balance was changed from **Usage > Billing > Balances** or through a completed WooCommerce order.
Manual balance edits and completed credit package orders create ledger entries.
# User Portal
Source: https://docs.aipower.org/user-portal
Manage licenses, downloads, subscriptions, invoices, and billing details.
The User Portal is where paid users manage their AI Puffer account.
Use it to download the plugin, manage licenses, update billing details, view invoices, and change subscriptions.
Open the portal here: [users.freemius.com](https://users.freemius.com)
## Portal access
After checkout, Freemius sends an email with your portal access details.
If you do not have the password, use **Forgot Password** on the portal login page.
## Websites
Use **Websites** to see where AI Puffer is installed and which site has an active license.
Open: [Manage Websites](https://users.freemius.com/websites)
You can:
* View connected websites.
* Deactivate a license from a website.
* Reuse the license on another website after deactivation.
### Move a license to another site
1. Open **Websites**.
2. Select the website that currently uses the license.
3. Select AI Puffer if the site has more than one product.
4. Open the license details.
5. Click **Deactivate**.
After deactivation, activate the same license on the new WordPress site.
## Downloads
Use **Downloads** to download the latest Pro ZIP file or an older version.
Open: [Downloads](https://users.freemius.com/downloads)
To download an older version:
1. Open **Downloads**.
2. Find AI Puffer.
3. Open the version menu next to the download button.
4. Select the version you need.
Beta versions, when available, appear in the same version menu with a **Beta** label.
## Updates
Plugin updates appear in the WordPress admin dashboard.
As long as your license is active, you can update the Pro plugin from **Dashboard > Updates** or **Plugins**.
## Licenses
Use **Licenses** to view license keys and check license status.
Open: [Manage Licenses](https://users.freemius.com/licenses)
## Upgrade a license
Use this when you want to move from a single-site license to a license that covers more sites.
1. Open **Renewals & Billing**.
2. Select the subscription.
3. Open the plan or license upgrade menu.
4. Choose the new license.
5. Complete checkout.
Freemius prorates the payment based on the current subscription.
## Payments and invoices
Use **Payments** to view payment history, download invoices, or update payment details.
Open: [Payments](https://users.freemius.com/payments)
To download an invoice:
1. Open **Payments**.
2. Find the payment.
3. Click **Invoice**.
## Add VAT or business details
1. Open **My Profile**.
2. Update your billing information.
3. Add your Tax or VAT ID.
4. Save the profile.
Open: [Profile Settings](https://users.freemius.com/profile)
Future invoices will include the updated billing details.
## Update payment method
1. Open **Renewals & Billing**.
2. Select the subscription.
3. Click **Update** next to the payment method.
4. Complete checkout with the new card or PayPal account.
## Cancel auto-renewal
1. Open **Renewals & Billing**.
2. Select the active subscription.
3. Click **Cancel Auto-Renew**.
4. Confirm the cancellation.
Canceling auto-renewal stops future renewals. The license remains usable according to the terms shown in the portal.
## Support
Paid users can open support from the portal.
Open: [Support](https://users.freemius.com/support)
# WordPress AI Connectors
Source: https://docs.aipower.org/wordpress-ai-connectors
Route WordPress AI Client requests through AI Puffer.
WordPress 7.0 includes a built-in AI Client. Plugins, themes, and WordPress AI features can use `wp_ai_client_prompt()` to send AI requests through connectors configured in WordPress.
AI Puffer can manage those connectors. When management is enabled, WordPress AI Client requests route through AI Puffer provider settings, model defaults, logs, credits, and pricing rules.
This feature is available only on WordPress versions that include the WordPress AI Client and Connectors API.
Let AI Puffer manage WordPress AI connectors.
Understand providers, defaults, and model selection.
Use existing logs, credits, and pricing rules.
Work with WordPress connector approval checks.
## Requirements
You need:
1. WordPress 7.0 or later with AI support enabled.
2. AI Puffer installed and active.
3. At least one provider configured in **AI Puffer > Settings > AI**.
Provider API usage still belongs to your provider account. AI Puffer does not include provider credits.
## Enable Management
You can enable management from the WordPress connector screen:
1. Open **WordPress Admin > Settings > Connectors**.
2. Find the AI Puffer banner.
3. Click **Enable**.
After enabling, the banner changes to **Managed by AI Puffer**. WordPress AI Client requests now run through AI Puffer.
![WordPress Connectors API]()
You can also enable it from AI Puffer settings:
1. Open **AI Puffer > Settings > Developers**.
2. Find **WordPress AI Connectors**.
3. Turn it on.
![WordPress AI Connectors setting in AI Puffer]()
If you dismissed the connector-page banner before enabling, use the **WordPress AI Connectors** setting in **AI Puffer > Settings > Developers**.
## Stop Management
To stop AI Puffer from managing WordPress AI connectors:
1. Open **WordPress Admin > Settings > Connectors**.
2. Find the **Managed by AI Puffer** banner.
3. Click **Stop**.
![WordPress Connectors API]()
You can also open **AI Puffer > Settings > Developers** and turn off **WordPress AI Connectors**.
Stopping management does not delete your AI Puffer provider settings. It only stops AI Puffer from taking over the WordPress AI Client connector layer.
## How Routing Works
When management is enabled, AI Puffer registers these providers for the WordPress AI Client:
| Connector | Typical use |
| -------------------------- | --------------------------------------------------------- |
| OpenAI via AI Puffer | Text, vision-capable text models, and image generation. |
| Google via AI Puffer | Gemini text, vision-capable models, and image generation. |
| Anthropic via AI Puffer | Claude text and supported image input. |
| OpenRouter via AI Puffer | Models available through your OpenRouter account. |
| Azure OpenAI via AI Puffer | Azure OpenAI deployments. |
| DeepSeek via AI Puffer | Text generation. |
| xAI via AI Puffer | Grok text, supported image input, and image generation. |
| Ollama via AI Puffer | Local or self-hosted text models. |
AI Puffer also exposes default route models for WordPress AI features:
| Route | Uses |
| ------------------- | ----------------------------------------------------- |
| Default text model | Text generation and most editor/admin AI features. |
| Fast text model | Lightweight text tasks when a fast model is suitable. |
| Default image model | WordPress AI image generation requests. |
AI Puffer infers these routes from your existing provider settings. You do not need to configure a separate WordPress AI Client model list.
## Usage Logs, Credits, and Pricing
AI Puffer logs WordPress AI Client requests separately from AI Puffer module requests.
| WordPress AI request | AI Puffer usage area |
| ------------------------------------ | ------------------------------------------ |
| Text generation | WP AI Client logs and text pricing rules. |
| Vision or image input to text models | WP AI Client logs and text pricing rules. |
| Image generation | WP AI Client logs and image pricing rules. |
Chatbot, AI Forms, and Images quotas are not used for WordPress AI Client requests. Those quotas belong to specific AI Puffer modules, while a generic `wp_ai_client_prompt()` request is not tied to a chatbot, form, or image-generator request.
Generated requests are logged with the module label **WP AI Client**. In conversation details, you can see the provider, model, usage, request type, and response data when available.
If you use credits or pricing rules, AI Puffer records the final usage after the response returns. Module quotas are not enforced for these requests.
## Connector Approvals
The WordPress AI plugin includes an experimental **Connector Approvals** screen. If that feature is enabled, WordPress can block AI connector requests until an administrator approves the caller.
When AI Puffer manages connectors, approvals can involve two layers:
| Approval | Why it may be needed |
| ----------------------- | ------------------------------------------------------------------------------ |
| AI Puffer | AI Puffer is the gateway that sends the provider request. |
| Calling plugin or theme | Another plugin or theme may be the original caller of `wp_ai_client_prompt()`. |
If a request is blocked, open **WordPress Admin > Tools > Connector Approvals** and review the pending request. Approve only the plugins, themes, and connectors you want to allow.
## For Developers
Use the standard WordPress AI Client API. You do not need to call AI Puffer-specific PHP functions for WordPress AI Client compatibility.
```php theme={null}
$result = wp_ai_client_prompt( 'Write a short product summary.' )
->using_temperature( 0.4 )
->generate_text_result();
if ( is_wp_error( $result ) ) {
return $result;
}
return rest_ensure_response( $result );
```
For image generation:
```php theme={null}
$image = wp_ai_client_prompt( 'A clean product photo on a white background.' )
->generate_image();
if ( is_wp_error( $image ) ) {
return $image;
}
echo ' ) . ')
';
```
When AI Puffer is managing connectors, these calls use AI Puffer's configured providers and usage controls.
## Troubleshooting
Check these items:
1. Confirm the site is running WordPress 7.0 or later.
2. Confirm AI support and the Connectors API are available on the site.
3. Open **AI Puffer > Settings > Developers**.
4. Turn on **WordPress AI Connectors** if the connector-page banner was dismissed.
Open **WordPress Admin > Tools > Connector Approvals**.
Approve AI Puffer for the connector first. If the request came from another plugin or theme, approve that caller too.
Check the provider settings used by AI Puffer:
1. Open **AI Puffer > Settings > AI**.
2. Confirm the selected provider and default model.
3. Sync models if the model list is stale.
4. For image generation, check **AI Puffer > Images** settings.
The provider account is out of credits, blocked by billing settings, or using a key from the wrong account.
Open the provider dashboard and check billing, spend limits, and API key access.
# WordPress Utilities
Source: https://docs.aipower.org/wordpress-utilities
Use AI Puffer tools inside WordPress post lists and editors.
## Overview
WordPress Utilities are AI Puffer tools that appear inside normal WordPress admin screens.
Use them when you are already reviewing posts, pages, products, or editor content and want to update or index that content without opening a full module screen.
Turn these utilities on or off from **AI Puffer > Settings > Utilities**.
Update selected posts from the list screen.
Generate title, excerpt, meta, or tag suggestions for one post.
Send selected posts to a vector store, index, or collection.
Use Assistant from the Products list.
Run AI actions on selected text in the Classic Editor.
Run AI actions from the block toolbar.
## Content Assistant
Content Assistant appears as an **Assistant** button next to **Add New** on supported post list screens.
Use it when you want to update several posts, pages, or products in one run. It can update title, content, meta description, focus keyword, excerpt, tags, and URL slug.
To enable the Assistant button:
1. Go to **AI Puffer > Settings > Utilities**.
2. Turn on **Content Assistant**.
This controls the bulk **Assistant** button and the row **Assistant** menu on supported post, page, and product list screens.
![Utilities settings for Content Assistant]()
Row menu suggestions use the default AI provider and model from **Settings > AI**. Content Assistant lets you choose the provider and model before running.
To run Content Assistant:
1. Go to a WordPress post list, such as **Posts**, **Pages**, or **Products**.
2. Select one or more rows.
3. Click **Assistant** next to **Add New**.
4. Select a template if you want to reuse saved settings.
5. Choose the provider and model.
6. Under **What to update**, enable the fields you want to change.
7. Edit a prompt if needed.
8. Open settings if you want to adjust creativity, content length, reasoning, or Knowledge Base context.
9. Click **Start Processing**.
10. Review the progress log before closing the modal.
![Assistant button on a WordPress post list]()
![Content Assistant modal]()
Use Content Assistant on a small selection first. It edits real WordPress records.
## Row Assistant Menu
The row menu is for one post at a time.
When **Content Assistant** is enabled in **Settings > Utilities**, hover over a post row and click **Assistant** to open the menu. It includes:
| Action | What it does |
| ---------------------- | ------------------------------------------------------------- |
| **Generate Title** | Creates title suggestions from the current title and content. |
| **Generate Excerpt** | Creates excerpt suggestions from the post content. |
| **Generate Meta Desc** | Creates SEO meta description suggestions. |
| **Generate Tags** | Creates tag suggestions. |
To use it:
1. Go to a supported post list.
2. Hover over a row.
3. Click **Assistant**.
4. Choose an action.
5. Wait for suggestions.
6. Click the suggestion you want to apply.
![Assistant row menu on a post list]()
## Content Indexing
Content Indexing appears as an **Index** button next to **Add New** on post, page, and product list screens.
Use it to add selected WordPress content to Knowledge Base retrieval.
To show or hide the **Index** button:
1. Go to **AI Puffer > Settings > Utilities**.
2. Turn **Index button** on or off.
![Utilities setting for the post-list Index button]()
| Provider | Target | Extra requirement |
| ------------ | ------------ | ---------------------------------------------------------------------- |
| **OpenAI** | Vector store | Select an existing OpenAI vector store. |
| **Pinecone** | Index | Select the same embedding model that matches the index dimension. |
| **Qdrant** | Collection | Select the same embedding model that matches the collection dimension. |
| **Chroma** | Collection | Select the same embedding model used when the collection was indexed. |
To index selected posts:
1. Create or select the target in **AI Puffer > Knowledge Base > Stores**.
2. Go to a supported WordPress post list.
3. Select one or more rows.
4. Click **Index** next to **Add New**.
5. Select **OpenAI**, **Pinecone**, **Qdrant**, or **Chroma**.
6. Select the target vector store, index, or collection.
7. For Pinecone, Qdrant, or Chroma, select the embedding model.
8. Click **Start Indexing**.
For Chroma, configure the connection and collection before using the post-list indexer.
![Chroma API key]()
![Chroma Create collection]()
![Index button on a WordPress post list]()
![Add Content to Vector Store modal]()
For Pinecone, Qdrant, and Chroma, the embedding model dimension must match the index or collection dimension. For example, a 3072-dimension index or collection needs a 3072-dimension embedding model.
The post list includes an **Index Status** filter with **Indexed** and **Not Indexed** options.
The **Index Status** column is hidden by default. Open Screen Options, enable **Index Status**, and apply the change.
When the column is visible, indexed rows show the vector target where the post was added.
![Index Status screen option on a WordPress post list]()
## WooCommerce Assistant
WooCommerce Assistant uses the same Assistant tools on the **Products** list.
Use it when you want to update product titles, descriptions, short descriptions, SEO fields, tags, or URL slugs from the product list screen.
To use Content Assistant on products:
1. Go to **Products > All Products**.
2. Select one or more products.
3. Click **Assistant** next to **Add New**.
4. Choose the provider and model.
5. Enable the fields you want to update.
6. Edit prompts if needed.
7. Click **Start Processing**.
![Assistant button on the WooCommerce Products list]()
To use the row menu on one product:
1. Go to **Products > All Products**.
2. Hover over a product row.
3. Click **Assistant**.
4. Choose **Generate Title**, **Generate Excerpt**, **Generate Meta Desc**, or **Generate Tags**.
5. Apply the suggestion you want to use.
When the current item is a WooCommerce product, product data is available to the assistant prompts as context, including price, SKU, stock status, dimensions, attributes, purchase note, and product categories.
WooCommerce Assistant updates product content fields. It does not change price, SKU, stock, dimensions, or other product data fields.
## Classic Editor Assistant
The Classic Editor Assistant adds an **Assistant** dropdown to the TinyMCE toolbar.
Use it to rewrite, expand, summarize, simplify, create outlines, generate FAQs, or run your own custom actions on selected text.
To use it:
1. Go to **AI Puffer > Settings > Utilities**.
2. Turn on **Editor Assistant**.
3. Open a post or page in the Classic Editor.
4. Use the **Visual** editor.
5. Select the text you want to process.
6. Click **Assistant** in the editor toolbar.
7. Choose an action.
8. Review the inserted output.
![editor-assistant-settings on a WordPress post list]()
![Content Assistant in the Classic Editor toolbar]()
To customize the menu:
1. Open the **Assistant** dropdown in the Classic Editor.
2. Choose **Customize menu**.
3. Select an action to edit its label, prompt, and insert position.
4. Move actions up or down, add a new action, or delete actions you do not use.
5. Click **Save**.
Use `%s` in a custom prompt where the selected editor text should be inserted.
The Classic Editor and Block Editor assistants share the same action list. Changes saved from either editor apply to both menus.
If the Classic Editor button is missing, check **Editor Assistant** in **Settings > Utilities** and make sure the user's profile does not disable the visual editor.
## Block Editor Assistant
The Block Editor Assistant appears in the block toolbar when text is selected.
To use it:
1. Go to **AI Puffer > Settings > Utilities**.
2. Turn on **Editor Assistant**.
3. Open a post or page in the Block Editor.
4. Select text inside a text-based block.
5. Click the Assistant icon in the block toolbar.
6. Choose an action.
7. Review the result.
![Content Assistant in the Block Editor toolbar]()
If the generated output includes headings, lists, or paragraphs, AI Puffer can insert it as formatted editor content. The Block Editor notice includes **Undo** when the change can be reverted from the notice.
To customize the menu, open the Assistant menu in the Block Editor and choose **Customize menu**. You can edit action labels, prompts, insert positions, order, and add or delete actions.
The Classic Editor and Block Editor assistants share the same action list.
## Troubleshooting
Go to **AI Puffer > Settings > Utilities** and turn on **Content Assistant**. Also confirm the current user can edit the post type and has access to the Content Assistant module.
Go to **AI Puffer > Settings > Utilities** and turn on **Index button**. The button appears on supported post, page, and product list screens when the user has access to Content Indexing.
Select one or more rows using the checkboxes in the WordPress list table, then click **Assistant** again.
Turn on **Editor Assistant** in **AI Puffer > Settings > Utilities**, then select text inside the editor. The assistant actions need selected text because the action prompt uses that text as input.
Open **Customize menu** from the editor Assistant menu, edit the action prompt, and include `%s`. AI Puffer replaces `%s` with the selected editor text before sending the request.
Check the provider credentials, sync targets again, and confirm the selected embedding model dimension matches the index or collection dimension.
Check the default provider and model in **Settings > AI**. Row menu and editor assistant actions use that default configuration.