OneHux Forge
Get started

OneHux Forge Documentation

Platform Setup & Integration Guides

Connect your online store, payment gateways, and customer messaging channels to your AI agent in minutes. No complex code or manual token juggling required.

What you can connect

Commerce

Online Stores & Feeds

Sync product catalog, stock counts, order status, and instant cart checkouts across Google Sheets, Shopify, WooCommerce, and custom backends.

Payments

Payment Gateways

Stripe, PayPal, Paystack, Flutterwave, and OneHux Pay. Your agent generates secure checkout links and confirms orders directly into your account.

Messaging

Customer Channels

WhatsApp Business, Instagram DMs, Facebook Messenger, Website Widget, Telegram, and Google Business Profile reviews.

Services

Flights, Visas & Travel

Connect your booking engine or website via Forge Service Protocol (FSP-Service) for live flight availability, 30% deposit plans, and custom booking IDs.

Part 1

E-Commerce & Online Stores

Give your AI agent real-time access to your inventory, pricing, and order tracking.

Google Sheets & CSV Inventory Feed

Designed specifically for social sellers (Instagram, WhatsApp, TikTok) who track products and stock in a spreadsheet instead of a complex web platform.

How your spreadsheet should be structured:

Your sheet should have a header row with column titles. Forge automatically detects common column names:

Product NameSKU / CodePriceStock QuantityCategoryDescription
Vintage Leather JacketJKT-01350005JacketsHandcrafted brown genuine leather
Classic White SneakersSNK-02180000FootwearUnisex low-top sneakers (out of stock)

Connecting your Google Sheet:

  1. Google OAuth (Recommended): If you already connected Google Sheets under the Channels tab, your Google account is already authorized. Simply paste your spreadsheet URL or ID.
  2. Public Share Link: In Google Sheets, click Share → General access → Anyone with the link (Viewer). Copy the link.
  3. Open your agent's workspace, go to the Commerce tab, and click Store Connection.
  4. Select Google Sheets / CSV Feed from the dropdown.
  5. Paste your Google Sheet link (or public CSV URL) and optionally provide a tab name (e.g. Sheet1 or Inventory).
  6. Click Connect Google Sheet / Feed.
How to test: In the chat playground or live widget, ask: "Do you have the vintage leather jacket in stock and how much is it?". Your agent will confirm stock and quote ₦35,000. When asked for out-of-stock sneakers, it politely notes they are unavailable and suggests alternatives.

WooCommerce (WordPress)

Direct integration with your self-hosted WordPress store using the official WooCommerce REST API, featuring bi-directional stock and order synchronization.

What you need:

  • WordPress site URL with HTTPS (e.g. https://myboutique.com).
  • WooCommerce Consumer Key (starts with ck_...).
  • WooCommerce Consumer Secret (starts with cs_...).

Generating API Keys in WordPress:

  1. Log in to your WordPress Admin dashboard.
  2. Navigate to WooCommerce → Settings → Advanced → REST API.
  3. Click Add key.
  4. Enter Description: OneHux Forge and Permissions: Read/Write (Read/Write allows the agent to push new orders directly into your dashboard to reserve inventory).
  5. Click Generate API key and copy both the Consumer Key and Consumer Secret.
  6. In Forge, go to Commerce → Store Connection, select WooCommerce, paste the credentials, and click Connect.
Bi-Directional Order Sync: When a customer checks out in chat, Forge instantly pushes a Pending order into WooCommerce to reserve items from live inventory. When the customer pays (via Paystack, Flutterwave, or Monnify), payment reconciliation immediately updates the order status in WooCommerce to Processing.

Shopify

Connect your Shopify store in seconds using either 1-Click Native OAuth or an Admin API Custom App Token.

Option A: 1-Click Shopify OAuth (Fastest)

  1. In Forge, go to Commerce → Store Connection and choose Shopify.
  2. Enter your store domain (e.g. your-boutique.myshopify.com).
  3. Click Authorize with Shopify →.
  4. Log in to Shopify and click Install App to approve permissions. You are redirected back with your store connected immediately.

Option B: Custom App Admin Token

  1. In Shopify Admin, go to Settings → Apps and sales channels → Develop apps.
  2. Click Create an app and name it OneHux Forge.
  3. Under Admin API configuration, grant: read_products, write_products, read_orders, write_orders, read_inventory, write_inventory, read_draft_orders, write_draft_orders.
  4. Click Install app and copy your token starting with shpat_.... Paste it in Forge and click Connect.
Bi-Directional Order Sync & Stock Reservation: When a customer builds a cart or places an order via chat, Forge creates a Draft Order or Pending order in Shopify with inventory_behaviour: "decrement_obeying_policy", automatically reserving product inventory so it cannot be sold to another customer. Once the customer completes payment, Forge automatically captures the transaction and marks the order paid in your Shopify Admin.

Custom Store & OneHux Apps (Forge Store Protocol v1)

For proprietary websites (built with Django, Laravel, Express, Go, Axum, Next.js) or first-party tools like OneHux Bazaar, OneHux POS, and OneHux Courier.

The Forge Store Protocol Specification (FSP v1):

Your backend implements standard JSON endpoints secured via HMAC-SHA256 request signatures:

  • GET /forge/v1/manifest — Store metadata, currency, and declared capabilities.
  • GET /forge/v1/products?q=... — Real-time product search with variants, images, and live stock.
  • GET /forge/v1/orders/{ref}?email=...&phone=... — Order lookup with strict dual-factor verification.
  • POST /forge/v1/carts — Generate hosted checkout links and draft carts.
  • POST /forge/v1/delivery/quote — Calculate instant shipping quotes based on customer address.
  • POST /forge/v1/shipments & GET /forge/v1/shipments/{waybill} — Dispatch delivery orders and query live tracking.

Full specification, HMAC signing test vectors, and client implementations are documented in docs/store-protocol.md.

Flights, Travel & Services (Forge Service Protocol v1)

For travel agencies, flight booking aggregators, visa processing companies, shortlet rentals, and appointment-based service platforms.

How Multi-Tenant Service Engine Unison Works:

Instead of hardcoded rules, any vendor connects their backend by entering their Service Base URL, optional HMAC Secret, and proprietary Booking ID Prefixes (e.g. HGT-FL-, WAK-, or APT-) in the Commerce → Services tab. Forge AI agents then query your backend in real time and create synchronized bookings.

The FSP-Service JSON Specification:

  • POST /forge/v1/flights/search

    Input: { origin: "LOS", destination: "ABV", departure_date: "2026-11-25", passengers: 1, cabin_class: "economy" }
    Returns: Array of flight options with carrier, times (morning/afternoon/evening), duration, total price, and 30% initial deposit.

  • POST /forge/v1/bookings/create

    Input: Validated customer intake details (name, phone, email, route, passenger details, total price).
    Returns: Vendor-native booking ID, confirmation status, and optional authenticated checkout deep-link URL.

  • GET /forge/v1/bookings/{ref}?phone=...&email=...

    Anti-snooping verified lookup returning current application or ticket status.

HMAC-SHA256 Request Signing:

Every request sent from Forge agents includes: X-Forge-Key-Id: <your_key_id>
X-Forge-Timestamp: <unix_epoch_seconds>
X-Forge-Signature: hmac_sha256(secret, request_body)

How to Test Your E-Commerce Integration

Ensure your store connection is working smoothly before putting your agent in front of customers.

1. Test Connection Status

In Forge, open Commerce → Store Connection and click Test Connection. Forge pings your store's manifest/catalog and displays active capabilities and live latency.

2. Test Product & Stock Queries

Open the Test Chat tab and ask: "Do you have [item name] in stock and how much is it?". Verify that your agent returns the correct price, currency, availability, and product image.

3. Test Order Tracking Verification

Ask: "Where is my order #1042?". Notice that Forge asks for your email or phone number first for customer privacy. Provide the matching contact info to confirm the status displays correctly.

4. Test Instant Cart & Checkout Link

Say: "I want to buy 2 [item name], can you send me a payment link?". Your agent will generate a checkout link or draft order permalink, reserving stock on your store backend.

Payment Gateways & Direct Checkout

Let customers pay instantly inside chats. The money goes directly to your merchant account — OneHux never holds your funds.

OneHux Pay / Paystack / Flutterwave

Ideal for Nigeria, Ghana, and African markets. Supports Cards, USSD, and Dedicated Virtual Bank Accounts for instant transfer confirmation.

Stripe & PayPal

For global transactions in USD, EUR, GBP, and 135+ currencies. Generates instant pre-filled hosted checkout links.

To connect, navigate to Commerce → Payment Gateways, choose your provider, enter your API keys (encrypted at rest), and test in Live or Test mode.

Part 2

Messaging & Social Channels

Where your customers talk to your AI agent.

Website Chat Widget

The simplest channel — no external account or approval required.

  1. Go to the Channels tab and click Website Widget.
  2. Set your welcome greeting and color scheme.
  3. Copy the snippet and paste it before the closing </body> tag on your site.

WhatsApp Business

Official Meta WhatsApp Business Cloud API integration via popup signup.

  1. Go to Channels → Connect WhatsApp.
  2. Log in with your Facebook account and select or create your Meta Business Account.
  3. Add and verify your business phone number via SMS/Call.
  4. Close the popup — WhatsApp activates immediately.

Instagram & Facebook

Answers DMs, auto-posts updates, and replies to comments automatically.

  1. Ensure your Instagram professional account is linked to your Facebook Page.
  2. Click Connect Facebook Page under Channels.
  3. Grant permissions and select the Facebook Page you manage.
  4. Both Facebook Messenger and Instagram DMs activate automatically.

Telegram

Connects your own custom Telegram bot in under a minute.

  1. Open Telegram and message @BotFather.
  2. Send /newbot and follow the prompts to choose a bot name and username.
  3. Copy the API token provided and paste it into Channels → Connect Telegram.

Google Business Profile

Automatic AI replies to customer reviews and publishing local business updates.

  1. Click Connect Google Business in the Channels tab.
  2. Authorize with your Google account and select your location profile.

TikTok & YouTube

Engage viewers by automatically answering questions left in your video comments.

  1. Click Connect YouTube or Connect TikTok under Channels.
  2. Authorize your creator channel. Forge monitors new video comments and posts helpful replies based on your business training.
Part 3

Productivity, CRM & Voice

Back-office automation, spreadsheet sync, and AI phone calling.

Google Sheets (Outbound CRM Logging)

Automatically export customer activity into your own dedicated Google Sheet.

Whenever your AI agent converses with a customer, Forge appends real-time records into 4 structured spreadsheet tabs:

  • Leads: Name, Email, Phone, Company, Lead Score, Outreach Status.
  • Bookings: Reference, Date/Time, Customer Contact, Google Meet link.
  • Orders & Quotes: Order Reference, Total Amount, Items summary, Status.
  • Interactions: Chat transcript excerpts and session timestamps.

Google Calendar & Meet

Two-way calendar sync, intelligent free/busy slot checking, and automatic Google Meet video meeting creation.

Connect your Google account under Channels → Google Calendar. When a customer asks to schedule a consultation, demo, or service call, your agent checks your live availability and confirms the appointment with an instant Google Meet link sent to both you and the customer.

Microsoft 365 / Outlook Calendar & Microsoft Teams

Enterprise-grade two-way calendar sync with Microsoft Graph and automatic Microsoft Teams meeting link generation.

  1. Go to Channels → Microsoft 365 / Outlook Calendar.
  2. Click Connect Outlook Calendar → and approve the requested Microsoft permissions (Calendars.ReadWrite).
  3. Once connected, Forge checks your real-time busy intervals via Microsoft Graph so appointments never conflict.
  4. When customers book, Forge automatically generates a secure Microsoft Teams video meeting link (teams_url) saved directly to your calendar event and customer record.

Inbound & Outbound AI Phone Calling

A dedicated telephone number powered by high-speed neural voice AI.

  1. Go to the Channels tab and look under Phone Numbers.
  2. Rent a local or toll-free number (supports US, UK, Canada, Nigeria, and 50+ countries).
  3. Configure your voice greeting and latency preferences. Customers can call your number to speak directly with your AI assistant.
Part 4

Staff Alerts, Escalations & Quiet Hours

Get notified on Slack, Discord, or WhatsApp when important events occur or when human staff intervention is required.

Slack, Discord & WhatsApp Staff Alerts

Deliver real-time alerts to your team channels without letting confidential customer details leak.

Configuring Notification Rules

  1. In your agent's dashboard, open the Staff Notifications settings.
  2. Choose which events notify your team:
    • Human Takeover Requested: Customer explicitly asks to speak to staff or needs complex resolution.
    • New Order Placed: Instant notification with order total and item breakdown.
    • Negative Feedback / Escalation: Frustrated customer sentiment detected.
  3. Select your alert channel:
    • Slack: Paste your Slack Incoming Webhook URL (e.g. https://hooks.slack.com/services/...). Alerts include rich formatting and Take over conversation link buttons.
    • Discord: Paste your Discord Webhook URL. Alerts format as clean color-coded embed cards.
    • WhatsApp Staff Alert: Enter the staff mobile number in E.164 format (e.g. +2348012345678).
Automated Redaction & Quiet Hours: All customer messages are automatically sanitized before dispatch: sensitive payment card numbers, BVN/NIN, OTPs, and private tokens are masked with [REDACTED]. Non-urgent alerts during scheduled Quiet Hours are held as deferred digests and delivered automatically when quiet hours end. Unacknowledged handoffs automatically trigger multi-round reminders to ensure no customer inquiry is dropped.

Frequently Asked Questions

How do I test if my Google Sheet or CSV catalog is working?

After connecting your sheet under Commerce → Store Connection, click Sync Catalog. Then open your agent's chat playground and ask: "What products do you have available?" or "Do you have [item name] in stock?". Your agent will read directly from your spreadsheet rows.

What happens if a customer wants to buy from a Google Sheet store?

If you have a payment gateway connected (Paystack, Stripe, or PayPal), the agent automatically creates an order record and sends the customer a secure payment link for the exact total.

Do I need a Meta or Shopify developer account?

No for Meta — WhatsApp, Facebook, and Instagram connect via direct one-click popup sign-in. For Shopify, you simply create a Custom App inside your existing Shopify admin in under two minutes.

Are customer order inquiries secure?

Yes. When a customer asks "Where is my order #1042?", Forge strictly requires a second factor (their email or phone number matching the order on file). Imposters cannot peek at other customers' orders.

Questions about OneHux Forge?

Email [email protected] or ask the Help assistant in the corner.

Activate your agent free