> ## Documentation Index
> Fetch the complete documentation index at: https://fliqr.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Functions and Actions: Connecting AI to External APIs
> Let your AI Agent call external APIs mid-conversation — check order status, fetch live data, or trigger actions in other systems using defined functions.
A Knowledge Base gives your agent access to static content. Functions give it access to live data. When a customer asks "Where is my order?", a function lets the agent call your order management API, retrieve the current status, and reply with real information — without the conversation leaving Fliqr AI.
## Overview
Functions (also called tools or actions) are HTTP endpoints you define inside an AI Agent. When the agent determines that a function is relevant to answering a user's question, it extracts the required parameters from the conversation, calls your endpoint, and incorporates the response in its reply — all in a single turn.
The agent decides when to call a function based on the function's description and the user's message. You do not need to build explicit routing logic. The language model handles that decision.
## Prerequisites
* An AI Agent configured with a system prompt — see [Prompt Engineering](/docs/core-concepts/ai-agents/prompt-engineering)
* An HTTP endpoint that accepts requests and returns JSON responses
* (Recommended) Understanding of JSON Schema — functions use it to describe parameters
## When to Use Functions
Functions are the right tool when the answer requires data that changes in real time or is specific to the authenticated user:
* Check order status from your ERP or order management system
* Look up appointment availability in your booking system
* Create or update a contact record in your CRM
* Send a Slack or email notification when a lead qualifies
* Fetch a real-time product price or inventory level
* Submit a support ticket on the customer's behalf
If the data is static and infrequently updated (product descriptions, FAQ answers, policies), a [Knowledge Base](/docs/core-concepts/ai-agents/knowledge-sources) is simpler and does not require an API.
## How Functions Work
1. You define a function: name, description, HTTP method, URL, headers, and a JSON Schema describing its parameters.
2. During a conversation, the language model reads the function's description and decides whether it applies to the user's current message.
3. If it applies, the model extracts the parameter values from the conversation and Fliqr AI calls your endpoint.
4. Your API returns a JSON response. Fliqr AI passes that response back to the model.
5. The model writes a reply to the user using the returned data.
The user experiences this as a single, coherent response. The function call happens in the background.
## Add a Function to an Agent
Go to **AI Agents** → select your agent → **Functions** tab.
Click **Add Function**. A configuration panel opens with fields for name, description, method, URL, headers, and parameters.
The name is used internally (no spaces — use underscores). The description is what the language model reads to decide when to call this function. Write it as a clear, specific explanation of what the function does and what triggers it.
```text theme={null}
Name: get_order_status
Description: Retrieves the current status of a customer order by order ID.
Call this when a customer asks about the status, location,
or delivery date of a specific order.
```
Select the HTTP method (GET, POST, PUT, PATCH, DELETE) and enter your endpoint URL. Use `{{parameter_name}}` placeholders in the URL for path parameters.
```text theme={null}
Method: GET
URL: https://api.yourstore.com/orders/{{order_id}}
```
If your endpoint requires authentication, add the necessary headers. Use `{{secret_key}}` notation to reference secrets stored in your Fliqr AI environment — do not hard-code credentials.
```text theme={null}
Authorization: Bearer {{secret_key}}
Content-Type: application/json
```
Define each parameter the function needs. For each parameter, specify its type, a description, and whether it is required.
Click **Save**, then open the **Playground** and send a message that should trigger the function (e.g., "What's the status of order #4821?"). Verify that the agent calls the function and incorporates the response correctly.
## Example Function Definition
The following example defines a function that retrieves an order's status from an external API. You can use this as a starting template.
```json theme={null}
{
"name": "get_order_status",
"description": "Retrieves the current status of a customer order by order ID. Call this when a customer asks about the status, location, or estimated delivery of a specific order.",
"method": "GET",
"url": "https://api.yourstore.com/orders/{{order_id}}",
"headers": {
"Authorization": "Bearer {{secret_key}}"
},
"parameters": {
"order_id": {
"type": "string",
"description": "The order ID provided by the customer. Ask the customer for this if they have not already provided it.",
"required": true
}
}
}
```
## Structuring Function Results as Chat Messages
When a function returns data that should be presented as a structured message — a product card, a list of options, or a set of quick replies — combine function calls with JSON output prompting. Add an instruction to your system prompt:
```json theme={null}
When get_order_status returns a result, format your response as a JSON message:
[
{
"message": {
"text": "Your order {{order_id}} is currently {{status}}. Estimated delivery: {{estimated_date}}.",
"quick_replies": [
{ "content_type": "text", "title": "📦 Track Shipment", "payload": "Track Shipment" },
{ "content_type": "text", "title": "↩️ Request Return", "payload": "Request Return" }
]
}
}
]
```
This pairs function data retrieval with the structured output format your Flow expects, without requiring separate Flow blocks for each possible response.
## Multiple Functions on One Agent
You can add multiple functions to a single agent. The model selects the right function based on each function's description. To avoid unintended calls:
* Keep each function's description specific about its trigger conditions.
* If two functions cover similar topics, differentiate them clearly in the description (e.g., "use this for order status, not for return requests").
* Test each function individually in the Playground before testing combinations.
Functions execute on behalf of the authenticated user. Validate and sanitize all parameter inputs on your server side before acting on them. Do not rely on the language model's parameter extraction as a security boundary — treat function calls as you would any untrusted API input.
Write the function description as if you are explaining it to a colleague who needs to decide when to reach for it. A description like "Gets data" tells the model nothing. A description like "Retrieves the current inventory count for a specific product SKU — call this when a customer asks whether an item is in stock" produces accurate invocation decisions.
## Built-in and Flow-triggered functions
Besides custom HTTP tools, Fliqr AI supports AI Functions that collect parameters and trigger a Flow (for example booking or weather lookup). Create them under **AI Center → AI Tools → AI Functions**. Naming tips:
* Use multi-word names: `get_current_weather`, `book_appointment`
* Start descriptions with “Allows the user to…”
* Use meaningful parameter names (`email`, not random codes)
* Prefer returning the customer-facing result via a custom field output message so the Agent can rewrite it naturally
See [Appointment scheduling](/docs/core-concepts/ai-agents/appointment-scheduling) for a full example. For vendor ecosystems (Shopify, Stripe, Zapier), prefer [MCP servers](/docs/core-concepts/ai-agents/mcp-servers) when available.
## What's next
Attach MCP tools without writing every HTTP function.
Teach the agent when to call each tool.
Built-in path when AI should stop.
Format tool results as buttons and cards.