Skip to main content

​
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 →

​
Endpoints

MethodPathDescription
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

GET /api/custom-functions?agentId={agentId}
Authorization: Bearer YOUR_API_KEY
Response: 
{
  "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

GET /api/custom-functions
Authorization: Bearer YOUR_API_KEY
Response: 
{
  "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

GET /api/custom-functions?organizationId={orgId}
Authorization: Bearer YOUR_API_KEY
Response: 
{
  "functions": [
    {
      "id": "func_abc123",
      "name": "check_order_status",
      "agent": {
        "id": "agent_xyz",
        "name": "Customer Support Bot",
        "organizationId": "org_123"
      }
    }
  ],
  "role": "admin"
}

​
Create a Function

POST /api/custom-functions/{agentId}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Request body: 
{
  "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"]
  }
}
FieldRequiredDescription
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: 
{
  "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"
}
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."

​
Update a Function

PUT /api/custom-functions/{agentId}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Request body — include id plus any fields to update: 
{
  "id": "func_abc123",
  "endpoint": "https://api.yourcompany.com/v2/orders/status",
  "description": "Updated description for the agent"
}
Response: Updated function object.

​
Delete a Function

DELETE /api/custom-functions/{agentId}?functionId={functionId}
Authorization: Bearer YOUR_API_KEY
Response: 
{
  "success": true
}
Deleting a function immediately stops the agent from calling it. The function ID is also removed from the agent’s enabledCustomFunctions array automatically.

​
How TalkifAI Calls Your Endpoint

When the agent triggers a function, TalkifAI makes a POST to your endpoint: Request from TalkifAI to your server: 
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: 
{
  "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: 
{
  "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

RoleCan ViewCan 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