# Documentation

- [Amazon](/docs/amazon): How to route Amazon buyer messages into Octocom, let the AI respond to them, and connect Amazon order data for automation — including what's possible with refunds and cancellations for FBA and FBM sellers.
- [Contact Form](/docs/contact-form): undefined
- [Octocom Copilot](/docs/copilot): An AI assistant built into the Octocom dashboard that can configure, debug, and test your bot, analyze your support data, and produce reports — all through chat, with every change gated behind your explicit approval.
- [Introduction](/docs/introduction): Welcome to the Octocom documentation. Octocom is an AI-powered customer support platform for ecommerce — this guide explains what it does, how it's organized, and where to start.
- [Octocom MCP](/docs/mcp): Connect your AI agent (Claude, Claude Code, or any MCP-compatible client) to Octocom so it can read and modify your bot's configuration, drive test conversations, and build custom integrations.
- [REST API](/docs/rest-api): Programmatic access to your Octocom data and configuration over plain HTTP — list and read conversations, manage workflows, articles and bot rules, search your product catalogue, record purchases, and more. This page explains what the API covers and where to find the full reference.
- [Storefront Search](/docs/storefront-search): Add an AI-powered product search bar to your storefront — instant suggestions, smart keyword + semantic matching, and filters — styled with your own HTML.
- [Virtual Try-On](/docs/virtual-tryon): Inject a 'Try it on' button on product pages that opens an AI-powered preview — customers upload a photo and see the product on themselves (apparel, accessories) or in their space (furniture, decor).
- [A/B Testing](/docs/ai-knowledge-and-logic/ab-testing): Run experiments on your bot's behavior. Test different conversation flows, refund strategies, or response styles — and measure which performs better.
- [Bot Operating Model](/docs/ai-knowledge-and-logic/bot-operating-model): How the Octocom AI bot actually works, from first principles. At its core it's a flexible, agentic LLM loop — a system prompt, a set of tools, and a model that reasons, calls tools, and replies. This page explains that loop, what shapes it, and what it can and can't do.
- [Bot Rules](/docs/ai-knowledge-and-logic/bot-rules): Bot rules are short, always-on instructions baked into the bot's system prompt. Powerful, but scarce by design — this page explains what they're for, why they're limited, and when to reach for a workflow or knowledge base article instead.
- [Common Patterns](/docs/ai-knowledge-and-logic/common-patterns): Practical recipes for common bot automation scenarios — order tracking, refunds, product lookups, in-chat purchases, and more.
- [Condition Providers](/docs/ai-knowledge-and-logic/condition-providers): Dynamically route workflows based on external data. Condition providers evaluate customer state and select the right workflow variant.
- [Custom Actions](/docs/ai-knowledge-and-logic/custom-actions): Connect your bot to external systems. Custom actions let workflows fetch data, create orders, process refunds, and more — using simple API calls or Python scripts.
- [Event Handlers](/docs/ai-knowledge-and-logic/event-handlers): Run custom Python code automatically when conversation events occur — close, handoff, and more. Use event handlers for CRM updates, notifications, analytics, and post-conversation workflows.
- [Follow-Ups & Auto-Resolve](/docs/ai-knowledge-and-logic/follow-ups-and-auto-resolve): Nudge quiet customers with automated follow-ups you control through bot rules and workflows, and automatically close email conversations that are truly resolved.
- [Human Escalation](/docs/ai-knowledge-and-logic/human-escalation): How the bot hands conversations to humans — the built-in transferConversation action, what actually happens on handoff, and custom escalation patterns like working-hour gates, department routing, and phone transfers.
- [Knowledge Base](/docs/ai-knowledge-and-logic/knowledge-base): The knowledge base is everything factual your bot can look up — articles, scraped websites, and uploaded documents. The bot never memorizes it; it searches on demand with the searchKnowledgeBase tool, which is available automatically as soon as there is anything to search.
- [Order Tracking](/docs/ai-knowledge-and-logic/order-tracking): Wire up order lookups for any backend by writing a small Python action that calls your existing order API. The bot uses it to answer 'Where's my order?', 'What's the status of #12345?', and similar questions.
- [Persona & Voice](/docs/ai-knowledge-and-logic/persona-and-voice): The configurable instruction blocks that define your bot's identity, voice, and global behavior — persona, tone, writing style, language, and safety guardrails. Tuned defaults out of the box; override only when you have a reason.
- [Python Context](/docs/ai-knowledge-and-logic/python-context): The context object passed to every Python function — conversation data, customer profile, business info, and more.
- [Python Helpers](/docs/ai-knowledge-and-logic/python-helpers): Built-in helper functions available in all Python-based features — custom actions, condition providers, event handlers, and sidebar widgets.
- [Recurring Jobs](/docs/ai-knowledge-and-logic/recurring-jobs): Run custom Python code on a recurring schedule — daily reports, periodic checks against external systems, scheduled cleanups. No external hosting required.
- [Workflows](/docs/ai-knowledge-and-logic/workflows): Automate structured conversations and actions. Workflows tell the AI exactly what to do in specific situations — from tracking orders to handling complaints.
- [Installation](/docs/bigcommerce/installation): undefined
- [Installation](/docs/magento/installation): Connect your Magento store to Octocom to enable automated post-sales support actions such as order tracking, address changes, and more.
- [The Conversation Sidebar](/docs/help-desk/conversation-sidebar): A tour of the right-hand panel — where to find context without asking the customer
- [Email auto-merging](/docs/help-desk/email-conversation-merging): How Octocom decides whether a new email joins an existing conversation or starts a fresh one
- [Macros](/docs/help-desk/macros): Saved replies and one-click actions for handling conversations faster
- [Managing Conversations](/docs/help-desk/managing-conversations): A short guide to managing conversations as a human agent in Octocom
- [Notes](/docs/help-desk/notes): Internal notes for leaving context on a conversation
- [Custom Sidebar Widgets](/docs/help-desk/sidebar-widgets): Pull data from your own systems into the conversation sidebar. Sidebar widgets give agents instant context — account lookups, warranty checks, CRM records — without leaving Octocom.
- [Tags & Priority](/docs/help-desk/tags-and-priority): Classifying and prioritizing conversations
- [Third Party Help Desk](/docs/help-desk/third-party-help-desk): How to use a third party help desk with Octocom
- [Views](/docs/help-desk/views): Default views and saved filters for organizing conversations
- [EU AI Act](/docs/security/ai-act-transparency): The EU AI Act's requirement to tell customers they're talking to an AI, whose responsibility it is, and how to implement the disclosure on every Octocom channel.
- [AI Deployment Checklist](/docs/security/ai-deployment-checklist): undefined
- [AI Reliability](/docs/security/ai-reliability): How Octocom keeps the bot accurate and trustworthy — grounding answers in your real knowledge and data, planning before acting, verifying before committing, and running the parts that must be exact as deterministic code.
- [AI Security](/docs/security/ai-security): Why an Octocom bot is safe to trust with real customer service — including sensitive workflows. Security comes from the architecture around the AI, not from the AI behaving. You decide what the model can reach and do, and deterministic software enforces it.
- [Bot Security Checklist](/docs/security/bot-security-checklist): A practical pre-launch review for a secure bot. What each risk is, how Octocom contains it, and the specific configuration decisions that are yours to make.
- [Authentication & Access Control](/docs/security/customer-authentication): How to control what the bot can access and act on — and how to verify who a customer is before unlocking anything sensitive. Every tool and condition provider receives inputs; you decide which to trust and what to verify.
- [Data Handling & GDPR](/docs/security/data-handling): How Octocom handles personal data under GDPR: controller and processor roles, where data lives, how long it's kept, and how deletion requests work.
- [Security Controls](/docs/security/security-controls): Octocom measures and policies for maintaining high security standards
- [Security Overview](/docs/security/security-overview): How Octocom keeps your business and customer data safe — across infrastructure, organizational practice, and the AI itself. Our security model, our data protections, and where to go for the details.
- [Subprocessors](/docs/security/subprocessors): The third parties Octocom relies on to deliver the service, with contracting entities and processing locations.
- [Browser Session Purchases](/docs/shopping-consultant/browser-session-purchases): undefined
- [Google Analytics 4 (GA4)](/docs/shopping-consultant/google-analytics-4): Track Octocom chat widget interactions in Google Analytics 4. Works automatically with gtag.js or via Google Tag Manager with a simple trigger setup.
- [Product Data](/docs/shopping-consultant/product-data): undefined
- [Comment Workflows](/docs/social-media/comment-workflows): How AI-powered comment workflows work — the concepts, building blocks, and strategies for automatically responding to social media comments.
- [Common Issues](/docs/social-media/common-issues): Troubleshooting common issues with Facebook and Instagram social media integrations.
- [Connecting Facebook and Instagram](/docs/social-media/connecting-meta): How to connect your Facebook pages and Instagram accounts to Octocom so the bot can handle DMs, comments, and mentions.
- [Browser Storage & Consent](/docs/web-chat/browser-storage-and-consent): Exactly what the Octocom chat widget stores in a visitor's browser, when it stores it, and how to classify it for cookie-consent purposes.
- [Chat Custom Data](/docs/web-chat/chat-custom-data): Inject custom data from your website into Octocom chat conversations using localStorage or URL query parameters. Use it to personalize bot behavior, power custom actions, and enrich analytics.
- [Control Widget With Code](/docs/web-chat/control-widget-with-code): How to open the bot programmatically
- [AI Suggestion Buttons](/docs/web-chat/interaction-buttons): Show a row of contextual question buttons on your storefront — AI-generated for the product the shopper is viewing, or a fixed list you set — that open the chat with the question pre-filled.
- [Launch Chat Widget](/docs/web-chat/launch-chat-widget): undefined
- [Open Widget With Link](/docs/web-chat/open-widget-with-link): How to open the chat widget by clicking a link
- [Chat Widget Tutorial](/docs/woocommerce/chat-widget-tutorial): undefined
- [Getting Started (Manual)](/docs/woocommerce/getting-started-manual): undefined
- [Getting Started (Marketplace)](/docs/woocommerce/getting-started-marketplace): undefined
- [Chat Embed Tutorial](/docs/shopify/chat-embed-tutorial): undefined
- [Chat Widget Tutorial](/docs/shopify/chat-widget-tutorial): undefined
- [Conversation Topics](/docs/ai-knowledge-and-logic/ai-analytics/conversation-topics): undefined
- [Data Collection](/docs/ai-knowledge-and-logic/ai-analytics/data-collection): How to use AI-powered data collection to automatically extract structured insights from every conversation — product issues, cancellation reasons, customer behavior, bot performance, and more.
- [AI Analytics & Insights](/docs/ai-knowledge-and-logic/ai-analytics): undefined
- [Sentiment Analysis](/docs/ai-knowledge-and-logic/ai-analytics/sentiment-analysis): undefined
- [add_conversation_event](/docs/ai-knowledge-and-logic/helpers/add-conversation-event): Record an event in the conversation timeline.
- [add_conversation_tag](/docs/ai-knowledge-and-logic/helpers/add-conversation-tag): Add a tag to the current conversation for filtering and analytics.
- [add_google_sheets_row](/docs/ai-knowledge-and-logic/helpers/add-google-sheets-row): Append a row to a Google Sheet.
- [delete_conversation_metadata](/docs/ai-knowledge-and-logic/helpers/delete-conversation-metadata): Delete a metadata key from the current conversation.
- [fetch_via_proxy](/docs/ai-knowledge-and-logic/helpers/fetch-via-proxy): Fetch a URL through Octocom's HTTP proxy (stable egress IP) instead of the default outbound IP. Available in product-sync parsers.
- [get_ab_test_variant](/docs/ai-knowledge-and-logic/helpers/get-ab-test-variant): Assign a consistent A/B test variant for the current conversation.
- [get_conversation_metadata](/docs/ai-knowledge-and-logic/helpers/get-conversation-metadata): Read a metadata value from the current conversation.
- [get_integration_credentials](/docs/ai-knowledge-and-logic/helpers/get-integration-credentials): Retrieve the stored third-party integration credentials for every business in your organization.
- [hand_off_conversation](/docs/ai-knowledge-and-logic/helpers/hand-off-conversation): Hand off the conversation to a human agent from within an action.
- [is_holiday](/docs/ai-knowledge-and-logic/helpers/is-holiday): Check if a date is a public holiday in a given country.
- [klaviyo_create_event](/docs/ai-knowledge-and-logic/helpers/klaviyo-create-event): Create a custom event in Klaviyo for a customer profile.
- [klaviyo_get_lists](/docs/ai-knowledge-and-logic/helpers/klaviyo-get-lists): Retrieve all mailing lists from the business's Klaviyo account.
- [klaviyo_subscribe_to_list](/docs/ai-knowledge-and-logic/helpers/klaviyo-subscribe-to-list): Subscribe an email to a Klaviyo mailing list.
- [klaviyo_suppress_profile](/docs/ai-knowledge-and-logic/helpers/klaviyo-suppress-profile): Globally suppress a Klaviyo profile to unsubscribe from all communications.
- [llm_classify_binary](/docs/ai-knowledge-and-logic/helpers/llm-classify-binary): Classify input as true or false using an LLM.
- [llm_classify_category](/docs/ai-knowledge-and-logic/helpers/llm-classify-category): Classify input into one of several categories using an LLM.
- [proxy_request & proxy_session](/docs/ai-knowledge-and-logic/helpers/proxy-request): Make HTTP requests through Octocom's stable egress IP — for third-party APIs that allowlist by IP address. Available in custom actions, condition providers, event handlers, sidebar widgets, and recurring jobs.
- [send_outbound_email](/docs/ai-knowledge-and-logic/helpers/send-outbound-email): Send an outbound email that creates a new handed-off conversation.
- [send_slack_notification](/docs/ai-knowledge-and-logic/helpers/send-slack-notification): Send a notification to a Slack channel via an Incoming Webhook URL.
- [set_conversation_metadata](/docs/ai-knowledge-and-logic/helpers/set-conversation-metadata): Store a key-value pair as metadata on the current conversation.
- [set_data_collection_result](/docs/ai-knowledge-and-logic/helpers/set-data-collection-result): Store a collected data result on the current conversation for analytics.
- [set_message_sending_delay](/docs/ai-knowledge-and-logic/helpers/set-message-sending-delay): Control how long the AI waits before actually sending its reply in email conversations.
- [shopify_get_customer_orders](/docs/ai-knowledge-and-logic/helpers/shopify-get-customer-orders): Retrieve a Shopify customer's orders by email address.
- [shopify_get_customer](/docs/ai-knowledge-and-logic/helpers/shopify-get-customer): Look up a Shopify customer by email address.
- [Example 1 (static XML, single feed)](/docs/ai-knowledge-and-logic/product-sync-parsers/example-1): Reference AI-product-sync parser. Single static XML feed with <Product> elements. Downloaded once on first call, then iter-parsed for memory-stable streaming. Demonstrates the simplest single-feed shape.
- [Example 2 (static XML, multiple feeds)](/docs/ai-knowledge-and-logic/product-sync-parsers/example-2): Reference AI-product-sync parser. Three static XML feeds (products + Greek URLs + reviews). Streams the main feed via ET.iterparse; review and Greek-URL maps are built once into module-level dicts and looked up per product. Conditional metafields are emitted via a (label, key) tuple list.
- [Example 3 (paginated JSON API)](/docs/ai-knowledge-and-logic/product-sync-parsers/example-3): Reference AI-product-sync parser. Paginated JSON API. fetch_next_chunk returns one page per call; cursor (page number) lives in state['parser']['page']. Demonstrates the natural shape for paginated REST sources where one HTTP call gives you one chunk.
- [Product Sync Parsers](/docs/ai-knowledge-and-logic/product-sync-parsers): Write a Python script that turns a product feed (XML / JSON / paginated API) into Octocom catalog rows. Covers the fetch_next_chunk / map_one contract, the state and context dicts, the product output schema, and the runtime helpers (including fetch_via_proxy).