Custom Actions

Transform Orac from chatbot to AI agent — call external APIs mid-conversation.

What are Custom Actions?

Custom Actions let Orac call your external APIs during a conversation. You define a webhook endpoint in the dashboard, describe when it should be used, and Orac's AI automatically decides when to trigger it based on what the visitor asks.

For example, a car dealer defines a “Search Inventory” action pointing to their inventory API. When a visitor asks “Show me SUVs under $30K”, Orac calls the API with the right parameters, gets the results, and presents them naturally in the conversation.

Actions are available on Pro (3 actions) and Business (10 actions) plans.

Creating an Action

1

Go to the Actions tab

Open your project dashboard and click the Actions tab (⚡ icon).

2

Click New Action

Fill in the form:

Name — a clear name like “Search Inventory” or “Book Appointment”.

Description — this is critical. It tells the AI when to use this action. Be specific: “Use when visitor asks about available vehicles, stock, models, or inventory.”

Webhook URL — the endpoint Orac will call. Must be publicly accessible.

HTTP Method — GET, POST, PUT, PATCH, or DELETE.

3

Add Parameters

Parameters are values the AI extracts from the conversation and sends to your API. Each parameter has a name, type (string/number/boolean), description, and required flag.

Example for an inventory search: type (string, “Vehicle type like sedan, SUV, truck”), max_price (number, “Maximum budget”).

4

Add Fallback Instructions (optional)

Tell the AI what to do when the action returns empty results or an error. Example: “If no vehicles match, suggest broadening their search or visiting the showroom.”

5

Test and Enable

Click Test to fire a test request to your webhook. Verify the response. Then toggle the action Enabled — disabled actions are never called.

Webhook Request Format

When Orac calls your webhook, it sends a JSON body with the extracted parameters:

// POST https://your-api.com/inventory
// Headers:
//   Content-Type: application/json
//   User-Agent: AskOrac/1.0
//   X-Visitor-Token: jwt-token (if configured)

{
  "type": "SUV",
  "max_price": 30000,
  "make": "Honda"
}

For GET requests, parameters are sent as query string: ?type=SUV&max_price=30000.

Your webhook should return JSON. Orac passes the response directly to the LLM, which formats it naturally for the visitor.

Webhook Response Format

Return any valid JSON. Orac's LLM interprets the data and presents it to the visitor in a natural, readable format.

// Recommended response format
{
  "results": [
    { "model": "CR-V", "year": 2024, "price": 28500, "color": "Blue" },
    { "model": "Passport", "year": 2024, "price": 29900, "color": "Silver" }
  ],
  "total": 2
}

// Error response
{ "error": "No vehicles found matching criteria" }

Multi-Step Chains

Orac supports up to 3 rounds of tool calling per message. This enables multi-step workflows:

1. Visitor: “Show me SUVs under $30K”

2. Orac calls Search Inventory → gets 0 results

3. Orac automatically broadens: calls Search Inventory again with higher budget

4. Gets results → presents alternatives: “I couldn't find SUVs under $30K, but here are some great options starting at $32K...”

No configuration needed — the AI decides when multiple rounds are necessary.

Visitor Authentication

For in-app support, you can pass a visitor authentication token that gets forwarded to your webhook:

<script
  src="https://askorac.com/widget.js"
  data-orac-id="your-project-id"
  data-orac-visitor-token="eyJhbGciOiJIUzI..."
  defer
></script>

The token is sent as an X-Visitor-Token header on every webhook call. Your API can use it to return personalized data — the user's orders, account details, subscription status, etc.

Orac never stores, processes, or logs this token. It's passed directly from the embed script to your webhook.

Built-in Tools

In addition to custom actions, Orac includes built-in tools that work automatically:

Calculator — handles any math: loan payments, percentages, unit conversions, tax calculations. No setup needed. When a visitor asks “What's the monthly payment on a $250K mortgage at 6.5%?”, Orac computes it precisely.

CSV Data Query — if you've uploaded CSV data in the Data tab, Orac can search, filter, and sort it mid-conversation. “Show me laptops under $1000 with 16GB RAM” → filters your product CSV and returns matching rows.

Industry Templates

When creating a new project, choose your industry for pre-configured actions. 15 templates available: Automotive, E-Commerce, Food, Medical, Electronics, SaaS, Government, Logistics, Education, Real Estate, Finance, Travel, Fitness, Legal, Manufacturing.

Templates create starter actions with placeholder webhook URLs. Replace the URLs with your real API endpoints, enable the actions, and you're live.