Tool-calls Event

When your Flireo AI agent is set to external, every time the agent needs to execute a function (tool), a request of type tool-calls is sent to your external server. This allows you to run custom logic, access databases, or trigger workflows—anything you want!

How It Works

You define tools/functions in your agent's model (see assistant-request).

When the AI decides to execute a function, Flireo sends a POST request to your server with the following payload:

{
  "eventTime": 1756278882619,
  "callId": "875573b5-4458-45be-bac2-4d2b869f8297",
  "eventType": "tool-calls",
  "fromCaller": "+31601234567",
  "toAssistant": "+31850123456",
  "tasksInitiated": [
    {
      "taskId": "call_kLsrB3eFvT6bvo67BqTv7iXc",
      "taskName": "send_task",
      "taskPayload": {
        "message": "Bericht voor het team: Jonas wil graag teruggebeld worden op telefoonnummer 06 01 23 45 67."
      }
    }
  ],
  "userMetadata": null
}

tasksInitiated: An array of tasks (tools) the agent wants your server to execute.

Each task includes a unique taskId, the function name (taskName), and the function arguments (taskPayload, a JSON object).

Multiple tasks can be initiated in a single event if your agent has several tools.

How to Handle the Request

Parse the incoming payload.

For each task in tasksInitiated:

Look at the taskName and taskPayload.

Execute the desired logic: update a database, send an email, fetch available slots, etc.

Prepare your response.
For each task, you must respond with the unique toolCallId (from taskId) and a result string.

Response Format

After executing each tool, reply to Flireo with:

{
  "results": [
    {
      "toolCallId": "call_kLsrB3eFvT6bvo67BqTv7iXc",
      "result": "Bericht succesvol ontvangen, het team zal Jonas terugbellen."
    }
  ]
}

results: An array matching the tasks initiated.

toolCallId: The original taskId from the request.

result: Any message or context the AI should use to continue the conversation.

This can be a confirmation, error, or rich context (e.g., available meeting slots, CRM data).

Multiple Tools Example

If multiple tools are called in one event, respond with all results:

{
  "results": [
    {
      "toolCallId": "call_abc123",
      "result": "Slot found: 2025-09-01 14:00"
    },
    {
      "toolCallId": "call_def456",
      "result": "Email sent to jonas@example.com"
    }
  ]
}

Best Practices

Always respond with every toolCallId present in the request.

The result field should give the AI context to keep the conversation flowing naturally.

Use this pattern for dynamic workflows (e.g., booking meetings, looking up customer info, sending notifications).

If a tool fails, return a helpful error message in the corresponding result.

Advanced: Building Powerful Workflows

The tools you define in your agent’s model (see assistant-request) can have any number of input parameters.

You can design complex workflows:

Check availability, then book a slot.

Fetch CRM data, then update a record.

Trigger external APIs, then return their output to the AI.

Example result for available slots:

{
  "results": [
    {
      "toolCallId": "call_xyz123",
      "result": "Beschikbare tijdslots: 14:00, 15:00, 16:30"
    }
  ]
}

Troubleshooting

If you forget to include a toolCallId in your reply, the AI will not know which tool was completed, and the workflow may break.

Always return a valid JSON object with all results.

Respond within 5 seconds to avoid timeouts.

Next:
Learn about end-of-call-report for capturing analytics and transcripts after each call.

How It Works#

How to Handle the Request#

Response Format#

Multiple Tools Example#

Best Practices#

Advanced: Building Powerful Workflows#