Agents & channels

An Agent is a configured persona: its own voice, its own knowledge (uploaded documents and links), its own tools, and often its own phone number. A single AiFlow deployment can run several Agents side by side, a sales agent, a support agent, a scheduling agent, without provisioning separate infrastructure for each.

Why an id shows up in almost every path

A deployment can host more than one Agent, so nearly every endpoint you call needs to know which one it's acting on. That's why agent_id or slug appears directly in the URL:

• POST /api/v1/agents/{agent_id}/events: agent_id is the Agent's numeric database id.
• POST /api/v1/agents/{slug}/widget/session: slug is a URL-safe string identifier for the same Agent.

Which one a given endpoint expects varies, some use the numeric id, others use the slug, so check the specific guide for the exact shape rather than assuming the two are interchangeable everywhere.

Creating and editing Agents uses the admin session token

Configuring an Agent itself (its persona, voice, knowledge, tools, and phone number) is also documented on this site, see Agents, but that's authenticated with an admin session token rather than an API key (see Authentication). If you're only integrating an external system against an already-configured Agent, all you need is the agent_id or slug you're targeting. Your admin team can give you that, or you can read it off the dashboard or the Agents endpoint yourself if you have access.

The three channels

Whichever way a visitor, caller, or system reaches an Agent, the conversation runs on the same underlying engine, only the entry point differs:

• Widget: a <script> tag embeds a floating voice or text chat on a website. See Embedding the widget.
• Phone: an inbound call to a number mapped to the Agent (the twilio_phone_number field, set the same way as any other Agent field, see Agents). Pointing that number's own webhook configuration at your deployment happens on Twilio's side, not through an AiFlow endpoint, and isn't covered on this site.
• Event-triggered: your system posts an event, and if it matches a rule your admin team configured, AiFlow calls or messages the recipient proactively, or runs a silent action with no call or message at all. See Triggers & events and Sending events.
• Connected mailbox: the Agent watches a real inbox for new mail and reacts on its own judgment. See Mailbox connections.