Skip to content
RelationsAI
Getting started

Platform overview

RelationsAI runs AI voice agents that hold phone conversations on your behalf. You design and publish agents in the RelationsAI console, then use the API to start calls and campaigns, read results and receive events. This page shows how the pieces connect so you know which part of your integration talks to what.

The console and the API

The console and the API work on the same workspace. The console is where people set things up; the API is where your software does the day-to-day work.

TaskWhere
Build, configure, test and publish agentsConsole Console only
Add phone numbers and assign them to agentsConsole Console only
Members, roles, billing, balance, calling hours, consent policy, security settingsConsole Console only
Create, rotate and revoke API keysConsole Console only
Read agents, check whether an agent can call, read phone numbersAPI
Place calls and read their status, transcript, recording and analysisAPI
Create, start, pause, resume and stop campaignsAPI (or console)
Sync contacts, consent and the do-not-call listAPI (or console)
Register webhook endpoints and inspect deliveriesAPI (or console)

Agent authoring through the API is Planned. See API availability for the full list.

Lifecycle of a call

A call is asynchronous: the request that places it returns before anyone answers.

  1. Accepted. POST /v1/calls checks the agent, your account, balance and spend limits, the do-not-call list, consent, calling hours and the per-number daily limit. If everything passes, it answers 202 Accepted with the call in queued status. If anything fails, nothing is dialled and you get an error that says why.
  2. Dialled and connected. The call moves to in_progress when the person answers. (A separate ringing status is not reported today; the workspace's capabilities.call_ringing_status says when it is.)
  3. Ended. status becomes ended and outcome says how: completed, no_response, no_answer, busy, failed or unknown. RelationsAI sends a call.ended event. The outcome is known at this point but can still be corrected until the call settles.
  4. Settled. After the call ends, the transcript, recording and analysis are produced and the charge is finalised, usually within a minute. When everything is final, settled becomes true and RelationsAI sends call.settled. Until then, outcome, duration_seconds and cost can still change.

Campaigns follow the same idea at a larger scale: you create one, add recipients, start it, and its status (running, paused, stopped, completed, failed) and progress change as it calls each recipient. See Core concepts.

Events and webhooks

Instead of polling, register a webhook endpoint: an HTTPS URL on your server. RelationsAI sends it a signed JSON event when something happens, such as call.ended, call.settled, campaign.started or campaign.completed. Deliveries are at least once and can arrive out of order, so your receiver verifies the signature, discards duplicates by event id and answers quickly. See Webhooks and Receiving webhooks.

Workspaces and modes

Your organisation in RelationsAI is a workspace. Every key belongs to one workspace and one mode:

  • A test key (rai_test_...) works in test mode: calls are simulated, nothing is dialled or charged, and every object has "livemode": false.
  • A live key (rai_live_...) works in live mode: real calls to real people, charged to the workspace balance, with "livemode": true.

Calls, campaigns, contacts, do-not-call entries, webhook endpoints and events created in one mode are invisible in the other. Agents and phone numbers are shared configuration, readable in both. See Environments.

Compliance built in

The same checks apply to calls from the console, campaigns and the API, in test mode as in live mode. They run when a call is placed, and for a campaign when it starts and when it resumes:

  • Do-not-call list. A call to a number on the list is refused (dnc_listed), and a campaign leaves listed numbers out when it starts. A campaign that is already running is not screened again: a number added to the list during a run can still be called by that run. To stop that, pause and resume the campaign (the resume is refused while a remaining recipient is listed) or stop it.
  • Consent. When the workspace requires consent, a number that matches a contact without recorded consent is refused (consent_required). A number with no contact record is not checked for consent.
  • Calling hours. Calls outside the hours set in the console are refused (outside_calling_hours).
  • Per-number daily limit. One number is not called more often in 24 hours than the workspace allows (contact_daily_limit_reached).
  • AI disclosure. An agent cannot be published unless its instructions tell the people it calls that they are speaking with an AI.

No API key or request option can switch these checks off. Do-not-call screening can be switched off for a single campaign only in the console, by a person; the API refuses to start or resume such a campaign (campaign_dnc_override_enabled), and the campaign's dnc_screening shows disabled_in_console. Your integration's job is to keep consent and the do-not-call list accurate; see Consent and do-not-call.

Where to go next

IntroductionQuickstart