Actions

Actions transform your AI assistant from a simple Q&A bot into an active agent that can interact with external systems, retrieve real-time data, and perform operations on behalf of users.

What is an Action?

An Action is a configurable HTTP request that your assistant can execute during conversations. When a user's request requires external data or operations, the assistant intelligently decides to invoke the appropriate action.

Example scenario:

User: "What's the status of order #12345?"
Assistant invokes the check_order_status action with order_id=12345
Assistant: "Your order #12345 shipped yesterday and should arrive by Friday. Here's your tracking number: 1Z999AA1234567890"

How Actions Work

You define actions — Create HTTP request templates with parameters
You describe them — Write clear descriptions so the AI knows when to use them
User asks a question — That requires real-time or external data
AI decides to act — Based on the question and action descriptions
AI extracts parameters — From the conversation context
Request is executed — FineGuide calls the external API
AI interprets response — And communicates results to the user

Creating Actions

Navigate to Actions

Go to Assistants → [Your Assistant]
Click the Actions tab

Create New Action

Click Create Action to open the action editor.

Action Components

Component	Required	Description
Name	Yes	Unique identifier (snake_case, letters and underscores only)
Description	Yes	Explains what the action does — helps AI decide when to use it
Method	Yes	HTTP method (GET, POST, PUT, DELETE, PATCH)
URL	Yes	API endpoint, can include
Headers	No	Request headers (authentication, content-type)
Parameters	Yes	Values the AI extracts from conversation
Body	No	Request payload for POST/PUT requests

Basic Example

json

{
  "name": "get_order_status",
  "description": "Retrieves the current status of a customer order using their order number",
  "method": "get",
  "url": "https://api.yourstore.com/orders/{{order_id}}",
  "content-type": "application/json",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  "parameters": [
    {
      "name": "order_id",
      "type": "string",
      "required": true,
      "location": "path",
      "description": "The order ID or order number provided by the customer"
    }
  ],
  "body": []
}

Parameters

Parameters are dynamic values that the AI extracts from the conversation and uses when calling the action.

Parameter Structure

Field	Description
name	Parameter identifier
type	Data type: `string`, `number`, or `boolean`
required	Is this parameter mandatory?
location	Where in the request: `path`, `query`, `body`, or `headers`
description	Helps AI understand what value to extract

Parameter Locations

Path Parameters — Embedded in the URL:

URL: https://api.example.com/orders/{{order_id}}

Query Parameters — Added to URL as query string:

URL: https://api.example.com/products?category={{category}}&limit={{limit}}

Body Parameters — Included in request body:

json

{
  "customer_email": "{{email}}",
  "message": "{{message}}"
}

Header Parameters — Added to request headers:

Authorization: Bearer {{api_token}}

Import Options

Import from cURL

Have an existing API call as a cURL command? Import it directly:

Click Import cURL
Paste your cURL command
FineGuide parses it into an action
Review and adjust as needed

Example cURL:

bash

curl -X POST https://api.mailgun.net/v3/domain/messages \
  -u 'api:key-xxxxx' \
  -F to='[email protected]' \
  -F subject='Hello' \
  -F text='Message body'

Import from n8n

Connect your n8n automation platform to import workflows:

First, connect n8n in Settings → n8n
Go to Actions → Import from n8n
Browse available workflows
Select and import as actions

Action Templates

FineGuide provides pre-built templates for popular services. Templates handle the complex configuration so you just provide your credentials.

Available Templates

Service	Templates
Shopify	Search products, check availability, order status, product recommendations
WooCommerce	Get products, order lookup
AfterShip	Track packages across 700+ carriers
Mailgun	Send emails
Twilio	Send SMS messages
HubSpot	Create CRM contacts
Trello	Create cards

Using Templates

Go to Actions → Templates tab
Browse available templates
Click a template to configure
Enter your credentials (API keys, domains, etc.)
Template is converted to a working action

Testing Actions

Before using actions in production, test them:

Select an action from the list
Click the Test button (⚡ icon)
Enter test values for each parameter
Click Execute
Review the response

What to check:

Is the response what you expected?
Are error cases handled properly?
Is the response format consistent?

Best Practices

Write Clear Descriptions

The AI uses descriptions to decide when to invoke actions. Be specific:

Good:

"Retrieves the current shipping status and tracking information for an order using the order number"

Bad:

"Gets order info"

Handle Errors Gracefully

Design your API to return clear error messages. The AI will communicate these to users.

Secure Your Credentials

Never expose sensitive API keys in descriptions
Use environment variables where possible
Rotate keys regularly

Keep Actions Focused

Create specific actions rather than complex multi-purpose ones:

Good:

get_order_status
cancel_order
update_shipping_address

Bad:

order_operations (tries to do everything)

Test Thoroughly

Before enabling:

Test with valid inputs
Test with invalid inputs
Test edge cases
Verify response handling

Common Use Cases

E-commerce

Action	Purpose
`check_order_status`	Look up order delivery status
`track_package`	Get shipping tracking info
`search_products`	Find products by criteria
`check_inventory`	Verify product availability
`get_recommendations`	Suggest related products

Customer Support

Action	Purpose
`lookup_account`	Find customer account details
`check_subscription`	Verify subscription status
`create_ticket`	File a support request
`schedule_callback`	Book a call with support

Lead Generation

Action	Purpose
`create_crm_contact`	Add lead to CRM
`schedule_demo`	Book a product demo
`send_quote`	Email a price quote
`add_to_newsletter`	Subscribe to mailing list

Booking/Scheduling

Action	Purpose
`check_availability`	See open time slots
`make_reservation`	Book an appointment
`cancel_booking`	Cancel existing reservation
`send_reminder`	Trigger reminder notification

Troubleshooting

Action Not Being Invoked

Check description — Is it clear when to use this action?
Verify parameters — Are descriptions helping AI extract values?
Test manually — Does the action work when tested directly?

Wrong Parameters Extracted

Improve descriptions — Be more specific about expected values
Add examples — Include format examples in parameter descriptions
Simplify — Break complex actions into simpler ones

API Errors

Check credentials — Are API keys correct and not expired?
Verify endpoint — Is the URL correct?
Test independently — Does the API work outside FineGuide?
Check permissions — Does the API key have required access?

Slow Responses

API performance — Is the external API slow?
Reduce complexity — Simplify the request if possible
Caching — Consider if the API supports caching

Technical Reference

JSON Schema

json

{
  "name": "string (required, snake_case)",
  "description": "string (required)",
  "method": "get|post|put|delete|patch (required)",
  "url": "string (required, URI format)",
  "content-type": "string (required)",
  "headers": {
    "Header-Name": "header-value"
  },
  "parameters": [
    {
      "name": "string (required)",
      "type": "string|number|boolean (required)",
      "required": "boolean (required)",
      "location": "path|query|body|headers (required)",
      "description": "string (required)"
    }
  ],
  "body": [
    {
      "content-type": "string",
      "data": "string or object"
    }
  ]
}

Supported HTTP Methods

Method	Use Case
`GET`	Retrieve data
`POST`	Create resources, send data
`PUT`	Update/replace resources
`PATCH`	Partial updates
`DELETE`	Remove resources

Next Steps

Configure Webhooks — Send events to your systems
Set up Session Variables — Track conversation context
Review Analytics — Monitor action usage

Actions ​

What is an Action? ​

How Actions Work ​

Creating Actions ​

Navigate to Actions ​

Create New Action ​

Action Components ​

Basic Example ​

Parameters ​

Parameter Structure ​

Parameter Locations ​

Import Options ​

Import from cURL ​

Import from n8n ​

Action Templates ​

Available Templates ​

Using Templates ​

Testing Actions ​

Best Practices ​

Write Clear Descriptions ​

Handle Errors Gracefully ​

Secure Your Credentials ​

Keep Actions Focused ​

Test Thoroughly ​

Common Use Cases ​

E-commerce ​

Customer Support ​

Lead Generation ​

Booking/Scheduling ​

Troubleshooting ​

Action Not Being Invoked ​

Wrong Parameters Extracted ​

API Errors ​

Slow Responses ​

Technical Reference ​

JSON Schema ​

Supported HTTP Methods ​

Next Steps ​

Actions

What is an Action?

How Actions Work

Creating Actions

Navigate to Actions

Create New Action

Action Components

Basic Example

Parameters

Parameter Structure

Parameter Locations

Import Options

Import from cURL

Import from n8n

Action Templates

Available Templates

Using Templates

Testing Actions

Best Practices

Write Clear Descriptions

Handle Errors Gracefully

Secure Your Credentials

Keep Actions Focused

Test Thoroughly

Common Use Cases

E-commerce

Customer Support

Lead Generation

Booking/Scheduling

Troubleshooting

Action Not Being Invoked

Wrong Parameters Extracted

API Errors

Slow Responses

Technical Reference

JSON Schema

Supported HTTP Methods

Next Steps