> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talkifai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Functions

> Create and manage custom API integrations that agents call in real-time during conversations.

## Overview

Custom Functions give your agent the ability to **take real actions** during a call — check order status, book appointments, query your database, update your CRM.

When the agent decides to call a function, TalkifAI sends a **POST request to your endpoint** with the parameters it extracted from the conversation. Your server responds with data, and the agent uses it in its reply.

```
User says: "What's the status of my order?"
       ↓
Agent calls: check_order_status({ order_id: "12345" })
       ↓
TalkifAI → POST https://api.yourcompany.com/order-status
       ↓
Your server responds: { "status": "shipped", "eta": "Jan 20" }
       ↓
Agent says: "Your order shipped! It should arrive by January 20th."
```

For setup instructions, see [Custom Functions Guide →](/guides/custom-functions)

***

## Endpoints

| Method   | Path                                              | Description                    |
| -------- | ------------------------------------------------- | ------------------------------ |
| `GET`    | `/api/custom-functions?agentId={id}`              | List functions for an agent    |
| `POST`   | `/api/custom-functions/{agentId}`                 | Create a function for an agent |
| `PUT`    | `/api/custom-functions/{agentId}`                 | Update an existing function    |
| `DELETE` | `/api/custom-functions/{agentId}?functionId={id}` | Remove a function              |

***

## List Functions

### For a Specific Agent

```bash theme={null}
GET /api/custom-functions?agentId={agentId}
Authorization: Bearer YOUR_API_KEY
```

**Response:**

```json theme={null}
{
  "functions": [
    {
      "id": "func_abc123",
      "name": "check_order_status",
      "label": "Check Order Status",
      "description": "Looks up the current status of a customer's order",
      "endpoint": "https://api.yourcompany.com/orders/status",
      "method": "POST",
      "headers": {
        "Authorization": "Bearer secret-key"
      },
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "string",
            "description": "The order ID to look up"
          }
        },
        "required": ["order_id"]
      },
      "agentId": "agent_xyz",
      "createdAt": "2024-01-10T09:00:00Z",
      "updatedAt": "2024-01-10T09:00:00Z"
    }
  ]
}
```

### For All User's Agents

```bash theme={null}
GET /api/custom-functions
Authorization: Bearer YOUR_API_KEY
```

**Response:**

```json theme={null}
{
  "functions": [
    {
      "id": "func_abc123",
      "name": "check_order_status",
      "label": "Check Order Status",
      "endpoint": "https://api.yourcompany.com/orders/status",
      "agent": {
        "id": "agent_xyz",
        "name": "Customer Support Bot",
        "organizationId": "org_123"
      }
    }
  ]
}
```

### For Organization

```bash theme={null}
GET /api/custom-functions?organizationId={orgId}
Authorization: Bearer YOUR_API_KEY
```

**Response:**

```json theme={null}
{
  "functions": [
    {
      "id": "func_abc123",
      "name": "check_order_status",
      "agent": {
        "id": "agent_xyz",
        "name": "Customer Support Bot",
        "organizationId": "org_123"
      }
    }
  ],
  "role": "admin"
}
```

***

## Create a Function

```bash theme={null}
POST /api/custom-functions/{agentId}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

**Request body:**

```json theme={null}
{
  "name": "check_order_status",
  "label": "Check Order Status",
  "description": "Looks up the current status of a customer order by order ID",
  "endpoint": "https://api.yourcompany.com/orders/status",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer your-internal-api-key",
    "X-Source": "talkifai"
  },
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The order ID to check"
      }
    },
    "required": ["order_id"]
  }
}
```

| Field         | Required | Description                                                            |
| ------------- | -------- | ---------------------------------------------------------------------- |
| `name`        | ✅        | Function identifier (snake\_case, used in system prompt)               |
| `label`       | ✅        | Human-readable name shown in Studio                                    |
| `description` | ❌        | What the function does — the agent uses this to decide when to call it |
| `endpoint`    | ✅        | Your API endpoint URL (must be HTTPS)                                  |
| `method`      | ❌        | HTTP method: `POST` (default), `GET`, `PUT`, `PATCH`                   |
| `headers`     | ❌        | Custom headers sent with every call (for auth, etc.)                   |
| `parameters`  | ❌        | JSON object defining the function's input parameters                   |

**Response:**

```json theme={null}
{
  "id": "func_new789",
  "name": "check_order_status",
  "label": "Check Order Status",
  "description": "Looks up the current status of a customer order by order ID",
  "endpoint": "https://api.yourcompany.com/orders/status",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer your-internal-api-key"
  },
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The order ID to check"
      }
    },
    "required": ["order_id"]
  },
  "agentId": "agent_abc123",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

<Note>
  After creating the function, **mention it in your system prompt** so the agent knows when to use it. Example: `"To check order status, use the check_order_status function."`
</Note>

***

## Update a Function

```bash theme={null}
PUT /api/custom-functions/{agentId}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

**Request body** — include `id` plus any fields to update:

```json theme={null}
{
  "id": "func_abc123",
  "endpoint": "https://api.yourcompany.com/v2/orders/status",
  "description": "Updated description for the agent"
}
```

**Response:** Updated function object.

***

## Delete a Function

```bash theme={null}
DELETE /api/custom-functions/{agentId}?functionId={functionId}
Authorization: Bearer YOUR_API_KEY
```

**Response:**

```json theme={null}
{
  "success": true
}
```

<Warning>
  Deleting a function immediately stops the agent from calling it. The function ID is also removed from the agent's `enabledCustomFunctions` array automatically.
</Warning>

***

## How TalkifAI Calls Your Endpoint

When the agent triggers a function, TalkifAI makes a POST to your endpoint:

**Request from TalkifAI to your server:**

```http theme={null}
POST https://api.yourcompany.com/orders/status
Content-Type: application/json
Authorization: Bearer your-internal-api-key   ← your custom header

{
  "order_id": "12345"
}
```

**Your server must respond within 10 seconds:**

```json theme={null}
{
  "status": "shipped",
  "carrier": "FedEx",
  "tracking": "9274899992136003",
  "eta": "2024-01-20"
}
```

The agent receives your response and uses it in its reply to the user. Return any JSON — the agent understands it.

***

## Parameters Format

Parameters are stored as a JSON object following **JSON Schema** format:

```json theme={null}
{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The customer's order ID (e.g., ORD-12345)"
    },
    "include_history": {
      "type": "boolean",
      "description": "Whether to include full order history",
      "default": false
    }
  },
  "required": ["order_id"]
}
```

**Supported types:** `string`, `number`, `boolean`, `array`, `object`

***

## Permissions

| Role   | Can View            | Can Create/Edit/Delete |
| ------ | ------------------- | ---------------------- |
| Owner  | ✅                   | ✅                      |
| Admin  | ✅                   | ✅                      |
| Member | ✅ (own agents only) | ❌                      |

**Notes:**

* Owners and Admins can manage functions for all agents in their organization
* Members can only view functions for agents they created
* Commercial agents: Only Owners/Admins can manage functions

***

## Related Documentation

* [Custom Functions Guide](/guides/custom-functions) — Step-by-step setup tutorial
* [Function Calling](/platform/advanced-configuration#3-function-calling-api) — Enable/disable functions
* [Advanced Configuration](/platform/advanced-configuration) — Complete agent configuration