Assistant-request Event

When you set your Flireo AI agent to external, every inbound call triggers a webhook to your server with the assistant-request event. Your server is responsible for responding with a full assistant configuration in JSON format—this lets you personalize and control your agent dynamically for each call.

How It Works

A call comes in to your agent.

Flireo sends a POST request to your configured server URL with the following payload:

{
  "eventType": "assistant-request",
  "fromCaller": "+31601234567",
  "toAssistant": "+31850123456"
}

Your server should:

Look up the caller (e.g., in your CRM or database)

Fetch any relevant context (name, email, recent orders, available timeslots, etc.)

Build the correct assistant configuration JSON (see below)

Return it as the response, with all the fields needed for your agent's behavior, messages, functions, and custom instructions

Example Assistant Configuration Response

Your server should reply with a JSON body that looks like this (fields can be tailored to your use case):

{
  "assistant": {
    "firstMessage": "Goedemorgen, met Julia van Voorbeeld Bedrijf. Hoe kan ik je helpen?",
    "endCallMessage": "Bedankt voor het bellen, tot ziens.",
    "voicemailMessage": "Hallo, dit is Julia. Zou je een momentje kunnen vinden om mij terug te bellen? Heel erg bedankt!",
    "analysisPlan": {
      "summaryPlan": { ... },
      "structuredDataPlan": { ... },
      "minMessagesThreshold": 10,
      "successEvaluationPlan": { ... }
    },
    "messagePlan": {},
    "firstMessageInterruptionsEnabled": false,
    "firstMessageMode": "assistant-speaks-first",
    "maxDurationSeconds": 600,
    "backgroundSound": "off",
    "endCallPhrases": [],
    "compliancePlan": {},
    "startSpeakingPlan": { ... },
    "stopSpeakingPlan": { ... },
    "keypadInputPlan": { ... },
    "transcriber": { ... },
    "model": {
      "model": "gpt-4.1-mini",
      "tools": [ ... ],
      "messages": [ ... ],
      "provider": "openai",
      "maxTokens": 150,
      "temperature": 0.3,
      "emotionRecognitionEnabled": false
    },
    "voice": {
      "model": "eleven_flash_v2_5",
      "voiceId": "ukiwGs47sHyibruHJ1vg",
      "provider": "11labs",
      "stability": 0.5,
      "similarityBoost": 0.6,
      "useSpeakerBoost": true,
      "inputPunctuationBoundaries": [".", "!", "?"]
    }
  }
}

See the full example at the top of this page for all possible fields and advanced configuration.

Building Your Custom Assistant JSON

Personalize at runtime:
Each time a call comes in, you can dynamically adjust the assistant's instructions, available tools, prompts, or messages based on the caller or business context.

Example workflow:

Lookup caller in your database by fromCaller

Fetch their email, preferred language, or available timeslots

Inject this data into the firstMessage, the AI system prompt, or anywhere in the assistant configuration

Why is this powerful?
You can make your agent truly dynamic, context-aware, and personalized for each caller—no static configuration required.

How to Get the JSON Template for Your Agent

You don’t need to guess the JSON structure!
After building your external agent in the dashboard (under /assistants/[id]), go to the Functions tab and use the “Copy JSON” button to get the correct assistant configuration.

Best Practices

Always respond within 5 seconds to avoid call errors.

Use HTTPS for your server endpoint.

Validate your assistant JSON before returning (all required fields must be present).

Use real data to personalize each call.

Next:
Learn about tool-calls for executing custom functions during the call, or see end-of-call-report for handling post-call analytics.

Assistant-request Event

How It Works#

Example Assistant Configuration Response#

Building Your Custom Assistant JSON#

How to Get the JSON Template for Your Agent#

Best Practices#

How It Works

Example Assistant Configuration Response

Building Your Custom Assistant JSON

How to Get the JSON Template for Your Agent

Best Practices