AI Meeting Agent API: How to Send an Agent Into a Meeting With Code

An AI meeting agent API lets your code create a video meeting and send an AI participant into it. The agent sees, hears and speaks, follows a script toward goals you set, and returns a transcript, recording and scored analysis when the call ends. A recorder bot sits in the call and writes it down; an agent holds the conversation itself. With Waterr, the first live meeting is two requests: list your scenarios, then create a meeting from one and hand over the link. The rest of this guide covers the lifecycle, the ways to dispatch the agent, and what to check before production.

The build-it-yourself route means owning turn-taking, persona drift, goal scoring and room cleanup. The agent API takes those off your list. If you want the category definition first, it lives in what an AI meeting API is. This post is the how.

What an AI meeting agent API does

The word "agent" is doing the work. A recorder bot joins a call that two humans are already having. An AI meeting agent is a participant and runs the conversation.

Four things get confused with it, and a table sorts them out:

The practical test is who holds the conversation. If the answer is "your user, and the tool watches," that is a notetaker, and the notetaker versus meeting agent comparison covers the trade-off. If the answer is "the AI, toward a goal," you are in agent territory.

Underneath, the participant joins a real-time room over WebRTC, the browser standard for audio and video between peers (W3C WebRTC). In Waterr's API that room comes back to you as a URL. You never touch the media layer.

The lifecycle: scenario, meeting, join, live, results

Everything starts with a scenario. In Waterr, a scenario is the complete conversation package: the persona (name, job title, demeanor, background), the meeting script that drives behavior turn to turn, and the goals the participant is scored against after the call. Goals are invisible during the session.

From there, the session lifecycle is five steps:

1. Create a meeting. POST /meetings with a scenario_id and person_name. Status is created.
2. Participant joins. They open the URL, see a welcome screen with the persona, accept consent if it is enabled, grant mic and camera, and enter. Status is active.
3. Session active. The AI persona runs the conversation against the script. Audio is transcribed live. Video is recorded and vision processes camera or screen input, if enabled. The session ends when the participant leaves, the duration limit hits, or your server calls PUT /meetings/{id}/end with an ended_at timestamp.
4. Session ends. Recording is finalized, the transcript is processed into sentences, goal evaluation begins. Status is ended.
5. Analysis generated. The transcript is evaluated against each goal. Scores, feedback and speech analytics are stored and available at GET /analyses/meeting/{id}.

That last endpoint returns 404 until the analysis exists, so a client either polls or, better, listens for a webhook. More on that below.

Dispatching an agent: link, schedule, embed

"Send Agent" is the product surface for getting a scenario's agent in front of a participant. Every scenario has its own Send Agent page, and the Send Agent walkthrough gives you two modes. There is a third path for code that lives inside your own product.

Share link. Copy a link and send it through any channel. The participant opens it and the agent takes the call. The link expires 24 hours after creation by default, and you can extend that. See Link.

Scheduled invite. Create a calendar event for a specific time. The participant gets an invite with a link that only works inside the scheduled window, and you can make it time-bound or one-time use. This is the right shape for interviews and assessments where a specific slot matters. See Schedule and the scheduling docs.

Per-send context. Both modes accept a note the agent factors into the call, for example "take this interview more towards communication skills". The base scenario stays untouched, and the context only applies to sessions from that send. That is how you tune one scenario across a cohort without cloning it.

Embed. Put the meeting inside your own page. Public scenarios use a plain iframe snippet. Private scenarios, or any flow where you already know who the visitor is, use a short-lived signed embed token minted from your backend with POST /v1/embed-tokens, which also returns a ready-to-paste iframe snippet.

One honest boundary: this post describes agents that run in Waterr-hosted rooms, reached by link, invite or embed. It does not promise the agent joining a call you host elsewhere. Check the docs before you design around that. For the non-code walkthrough of Send Agent, see the Send Agent post.

Giving the agent abilities

A talking persona is the floor. Each of these is a documented capability you attach to a scenario:

• Custom functions. Let the persona call your code mid-meeting, defined once and attached to any scenario. The tool can run on your server or inside your visitor's browser. This is how an agent books a slot, looks up an order, or writes to your CRM during the call.
• Knowledge base. Attach reference files so the persona grounds answers in your data, either deciding when to retrieve or retrieving on every turn.
• Web search. The persona can search the web during the conversation for current information.
• Vision. The persona can see participants through camera and screen share.
• Multi-agent. Run several agents in one meeting, with mid-call handoffs between them.
• MCP server. Your own coding agent can connect over MCP to list scenarios, fetch meetings and pull analyses, using OAuth sign-in or a wai_ API key.

Not every tool works in every surface. Some, like file presentation or page tools, need a page to act on and are documented per surface. Read the capability page before you build a flow on it.

Getting results back

When the meeting ends you have three artifacts, and they do not all land at once.

• Analysis. Per-goal scores with written feedback, strengths, growth areas and highlights, at GET /analyses/meeting/{id}.
• Transcript. Processed into sentences at session end.
• Recording. A separate asynchronous fetch at GET /recordings/meeting/{meetingId}. It is finalized and uploaded after the session, so do not assume it exists the moment the call ends.

For a single call that returns summary, transcript and goal scores, the quickstart points to GET /meetings/{id}, documented under Post-Meeting Data.

Polling works in a prototype. In production you want webhooks. Waterr delivers signed, retried events: meeting.created, meeting.ended, transcript.ready, recording.ready, participant.joined, participant.left, session.analysis_complete and analysis.failed. Each request carries a Waterr-Signature header with a timestamp and an HMAC-SHA256 of the raw body, which you verify against your endpoint's signing secret. The event-by-event detail is in the webhook post.

A minimal code example: two calls

Every new account is seeded with two scenarios, Plus One and Requirement Gathering, so you do not need to build a persona to see an agent run. Authentication is a bearer API key, and your workspace is inferred from it.

const API = 'https://api.waterr.ai/v1';
const API_KEY = process.env.WATERR_API_KEY; // wai_...
const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json',
};

// 1. Find the Plus One starter scenario
const { data: scenarios } = await fetch(`${API}/scenarios`, { headers })
  .then(r => r.json());
const plusOne = scenarios.find(s => s.default_kind === 'plus_one');

// 2. Create a meeting
const { data: meeting } = await fetch(`${API}/meetings`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    person_name: 'John Doe',
    scenario_id: plusOne.id,
  }),
}).then(r => r.json());

console.log('Join here:', meeting.meeting_url);

The response includes meeting_url (open it in a browser), daily_meeting_url, a room_token and the meeting id you use to fetch results later. That is the whole dispatch.

When you outgrow the starters, you can describe a scenario in plain language and have one generated through POST /scenarios/create-with-gpt, or create a persona and then a scenario by hand for full control. The request fields are in the quickstart. If you are building a screening flow specifically, how to build an AI interviewer covers goal and script design. And if you are choosing between raw HTTP and a client library, the SDK post is the read.

Production checklist

Before this goes in front of real participants:

• Auth. Keep the wai_ key on your server. Never ship it to a browser. For browser flows use a signed embed token.
• Consent. Turn on the consent message so participants see your recording and data-use disclosure before they join. The consent screen appears before the device check, so participants agree before the agent ever sees them.
• Webhook verification. Check the signature and the timestamp freshness on every request. The docs recommend a five-minute tolerance. Store the signing secret when you create the endpoint, because it is shown once. Rotating it is a separate call.
• Idempotent handlers. Retries mean the same event can arrive more than once. Key your handler on the event, not on arrival.
• Observability. If you self-host the meeting engine, you can stream the speech-to-text, model and text-to-speech spans, plus token usage, to any OpenTelemetry-compatible backend. The observability docs list Langfuse, Honeycomb, Grafana, New Relic, Datadog, SigNoz and Phoenix. This is a self-hosting option, not a setting on the hosted API.
• White label. If participants are your customers, white label replaces Waterr branding with yours on the participant-facing experience. It is available on Enterprise plans.

The full programmatic surface is on the API resources page.

Frequently asked questions

What is an AI meeting agent API?

It is an HTTP API that creates a video meeting and puts an AI participant in it. The agent follows a script and goals, talks with the human in real time, and returns a transcript, recording and scored analysis afterwards. You supply the scenario and the participant. The API supplies the room and the conversation.

How is an AI meeting agent different from a meeting recorder bot?

A recorder bot joins a conversation between humans and captures it. It does not speak or pursue anything. A meeting agent is a participant that runs the conversation toward goals you define, then scores the result. If you need a record of calls you already have, use a recorder. If you need the call to happen, use an agent.

Can the agent take actions during the call?

Yes, through custom functions. You define a tool once, attach it to a scenario, and the persona calls your code mid-meeting, on your server or in the visitor's browser. It can also search the web, retrieve from attached files, and hand off to another agent. Availability varies by meeting surface, so check each capability page.

How do I get results after the meeting?

Fetch them from the API or receive them by webhook. The analysis comes from GET /analyses/meeting/{id}, and the recording is a separate asynchronous fetch because it finalizes after the session. For production, subscribe to signed webhooks such as session.analysis_complete, transcript.ready and recording.ready instead of polling.

Can I white-label the agent?

Yes, on Enterprise plans. White label replaces Waterr branding with your own brand identity on the participant-facing experience. Combine it with a signed embed token and the agent runs inside your product, under your brand, with the participant already identified by your backend.

The pattern that holds up is boring: one scenario, one meeting call, one webhook handler. Get that loop running against a starter scenario this week, then spend your effort on the script and the goals, because those are what the participant actually experiences.