Skip to main content
Starting an AI voice agent call creates a normal Ringee outbound call plus the voice-agent record that tracks the conversation and analysis.

​
Pre-call checks

Ringee refuses the call unless all of these are true:
  • an organization workspace is active;
  • the agent belongs to that workspace and is ready;
  • outbound calling is enabled for the user;
  • the destination is not on the workspace’s Do Not Call list;
  • the workspace has available credits, unless a free-call trial applies;
  • the chosen caller number is eligible for AI voice agent calls;
  • every required agent variable is present and no unknown variable was supplied.
The destination is normalized to E.164 before dialing. MCP and CLI require E.164 at their own input boundary.

​
Start a call

metadata is opaque caller data. Ringee stores it on the voice-agent call and echoes it back in the result, which makes it useful for CRM ids and workflow correlation. When it includes external_id or externalId, Ringee also exposes that value as data.externalId on every related Custom Integration webhook. If the destination does not match an existing contact, Ringee creates one when possible. first_name, last_name and email fill the new contact’s identity. A failure to create that convenience record does not block the requested call.
Starting a call is non-idempotent and bills real usage. Do not automatically retry an ambiguous response. First check whether a call id was returned or whether the call appears in Ringee history.

​
Call status

Status describes the phone leg, not what the conversation achieved.

​
Outcomes

Outcome describes what the conversation achieved. A completed call can still have not_interested or unknown as its outcome. Historical appointment_booked and callback_requested values are normalized to meeting_booked and callback_scheduled before Ringee returns a result.

​
Polling

Use the call id returned by the start request:
Stop polling once the status is terminal and the analysis fields your workflow needs are populated. Analysis can arrive shortly after the phone leg ends.

​
Webhook lifecycle

An AI Voice Agent call uses the same signed outbound webhook pipeline as a human call. Depending on what happened, subscribed integrations can receive a terminal call.completed or call.failed, a later call.outcome.updated, and separate callback.created, meeting.created or recording.ready events. Each call-linked event carries the Ringee callId. When available, it also carries data.user, data.agent and your data.externalId. Deliveries are independent and ordering is not guaranteed, so upsert by callId and deduplicate by eventId. The id returned when you start the call identifies the AI Voice Agent call and is the call_id used by result polling. It is not the same as the telephony data.callId; call.outcome.updated exposes it separately as data.agentCallId.

​
Billing

An AI voice agent call has two provider-cost components:
  1. the ordinary telephony leg;
  2. the conversation engine and its model usage.
Ringee settles both from provider usage records and debits each component exactly once. AI_VOICE_AGENT_PROFIT_MARGIN applies to the AI component; normal call margin settings apply to the voice leg. Bring-your-own model providers also bill the model usage to your provider account. The self-hosted AI_VOICE_AGENT_MAX_CALL_SECONDS value places a hard ceiling on one call.

​
Next steps

MCP

Let an assistant place and monitor a call

Self-hosting

Configure callbacks, models, limits and storage

Webhook events

Map call, outcome, meeting and recording payloads