Custom Functions

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

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

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"]
  }
}

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:

{
  "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

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

Custom Functions Guide — Step-by-step setup tutorial
Function Calling — Enable/disable functions
Advanced Configuration — Complete agent configuration

Overview

Agents

Voice Calls

Export

Text Chat

Batch Calling

Webhooks

Custom Functions

Overview

Endpoints

List Functions

For a Specific Agent

For All User’s Agents

For Organization

Create a Function

Update a Function

Delete a Function

How TalkifAI Calls Your Endpoint

Parameters Format

Permissions

​Overview

​Endpoints

​List Functions

​For a Specific Agent

​For All User’s Agents

​For Organization

​Create a Function

​Update a Function

​Delete a Function

​How TalkifAI Calls Your Endpoint

​Parameters Format

​Permissions

​Related Documentation

Overview

Endpoints

List Functions

For a Specific Agent

For All User’s Agents

For Organization

Create a Function

Update a Function

Delete a Function

How TalkifAI Calls Your Endpoint

Parameters Format

Permissions

Related Documentation