AI Actions Setup Guide with Examples

AI Actions Setup Guide with Examples

AI Actions let the chatbot call your external APIs to fetch real-time data or perform operations during a conversation. Instead of generic answers, the bot can look up orders, check account status, or trigger workflows.

How AI Actions Work

1. A customer asks something like "What's the status of my order?"
2. The AI determines which action to call based on the action's description
3. The AI extracts parameters from the conversation (e.g., order number)
4. Helpium calls your API endpoint with those parameters
5. The AI formats the response into a helpful message

Creating an Action

Go to Settings → Integrations → AI Actions and click New Action.

Required Fields

• Name: A descriptive name (e.g., "Look Up Order Status")
• Slug: URL-friendly identifier, auto-generated from name
• Description: Tell the AI when to use this action. Be specific! Example: "Returns the current status and tracking info for a customer order. Use when a customer asks about order status, shipping, or delivery."
• URL: Your API endpoint URL
• HTTP Method: GET, POST, PUT, or DELETE

Authentication Types

Type	Description	Use Case
None	No authentication	Public endpoints
API Key	Sends a static token in a header	Server-to-server calls
Customer Bearer	Sends the customer's Sanctum token	Authenticated user endpoints

Customer Bearer is powerful — it lets the AI act on behalf of the logged-in customer, calling your API with their auth token. The customer must be identified via Helpium.identify({ bearerToken }) for this to work.

Parameters

Define the inputs the AI should extract from the conversation:

• Name: Parameter name sent to your API
• Type: string, number, or boolean
• Required: Whether the AI must have this value before calling
• Description: Helps the AI understand what to extract. Example: "The order number, usually starts with ORD-"

Example 1: Order Status Lookup (API Key Auth)

Name: Look Up Order Status
Slug: look-up-order-status
Description: Returns the current status and tracking information for a customer order.
             Use when a customer asks about their order status, shipping, or delivery timeline.
URL: https://api.yourstore.com/orders/{order_number}
Method: GET
Auth Type: API Key
Auth Header: X-API-Key
Auth Token: your_store_api_key

Parameters:
  - order_number (string, required): The order number, typically starts with ORD-

Example 2: Account Balance (Customer Bearer Auth)

Name: Check Account Balance
Slug: check-account-balance
Description: Returns the customer's current account balance and recent transactions.
             Use when a customer asks about their balance, credits, or recent charges.
URL: https://app.yourservice.com/api/account/balance
Method: GET
Auth Type: Customer Bearer
No parameters needed — the bearer token identifies the customer.

Example 3: Cancel Subscription (Customer Bearer Auth)

Name: Cancel Subscription
Slug: cancel-subscription
Description: Cancels the customer's active subscription. Use only when the customer
             explicitly confirms they want to cancel. Always confirm before calling.
URL: https://app.yourservice.com/api/subscription/cancel
Method: POST
Auth Type: Customer Bearer
Parameters:
  - reason (string, optional): The reason for cancellation

Best Practices

• Write clear descriptions. The AI uses the description to decide when to call the action. Vague descriptions lead to incorrect usage.
• Use Customer Bearer auth for personalized data. It's more secure than passing user IDs as parameters.
• Set appropriate timeouts. Default is 10 seconds. Increase for slow endpoints, decrease for simple lookups.
• Test thoroughly. Use the test button on each action's settings page to verify it works before enabling.
• Start simple. Begin with read-only actions (GET) before adding actions that modify data (POST/PUT/DELETE).