Documentation

Outbound calling

All docs

Outbound is how your agent calls people instead of waiting to be called. Three triggers cover almost every real-world need:

  • From the UI — single call to a specific contact, useful for one-off testing and small lists
  • By API — POST /v1/calls from your code, the most common path for production integrations
  • By CSV — upload a contact list with optional parameters, useful for campaigns

All three end up running the same scenario in the same engine. The differences are only in how the call gets queued and how you watch the results.

Triggering from the UI

Open the project's Calls tab → New outbound call. Pick a scenario, type the phone number in E.164 (+1…, +34…, +7…), and click Call. The platform queues the call, dials, and surfaces the live session in the Live tab as it happens.

This path is best for testing — pick a phone number you control, watch the agent behave end-to-end.

Triggering by API

The single endpoint is:

POST /v1/calls
Authorization: Bearer <project-api-key>
Idempotency-Key: <your unique id>
Content-Type: application/json

{
  "scenario": "appointment_reminder",
  "phone": "+34123456789",
  "metadata": {
    "customer_name": "Maria",
    "appointment_at": "2026-05-15T18:00:00Z"
  },
  "scheduled_for": "2026-05-15T15:00:00Z"
}

Fields:

  • scenario — the outbound scenario IDN. Required.
  • phone — E.164 destination. Required.
  • metadata — arbitrary key-value map your scenario reads from session.metadata. Use this to pass per-call context (customer name, appointment time, order number).
  • scheduled_for — optional ISO-8601 future time. Without it, the call queues immediately. With it, the call dispatches at the requested time (within a small dispatch tolerance).
  • Idempotency-Key — your unique identifier for this call. Repeating the same key returns the same call without dialing twice — important when you retry a failed API request.

The response is a session id you can fetch later, plus a status (queued, dialing, connected, completed, failed).

API keys are issued in the Connections → API keys tab. Keys are scoped — give a key only the permissions it needs (outbound:trigger, sessions:read, webhooks:manage). Rotate by issuing a new key and revoking the old.

Triggering by CSV

Open Calls → New batch. Upload a CSV with at least a phone column. Other columns become metadata for each row.

phone,customer_name,appointment_at
+34123456789,Maria,2026-05-15T18:00:00Z
+34987654321,Carlos,2026-05-15T19:00:00Z
…

Settings per batch:

  • Scenario — which scenario to run
  • Pacing — calls per minute (default 5; raise per project on request)
  • Start time — immediate or scheduled
  • Caller ID — which of your verified caller IDs to use

The batch progress page shows live counts (queued / dialing / connected / completed / failed), per-call outcomes, the success and goal-completion rate, and a downloadable CSV of results.

Outcomes and failure reasons

Every outbound call ends with one of these states:

  • completed — the call connected and ran to its end. Has an outcome (success / middle / spam).
  • no_answer — rang out, no human picked up.
  • busy — line was busy.
  • voicemail_detected — answering machine detected (AMD); the call hangs up by default and is not billed for the outcome (leaving voicemails is on the post-MVP roadmap).
  • invalid_number — destination number is not in service.
  • caller_id_unauthorized — the destination's carrier rejected our caller ID.
  • provider_error — telephony provider error (rare).
  • internal_error — platform error (rare; investigated automatically).

All of these surface in your CSV results, your webhook events, and your billing breakdown.

Compliance — your responsibility

Outbound calling is regulated. The exact rules depend on the destination country, the time of day, and what your callee has consented to. The platform gives you the tools (recordings, audit logs, opt-out scripts, do-not-call list import); compliance with TCPA (USA), GDPR (EU), or local regulations is your responsibility.

Practical guidance:

  • Get consent before calling — keep proof. Do not call people who did not ask to be called.
  • Honour do-not-call — the platform supports a per-project DNC list. Numbers on it are blocked from dispatch.
  • Disclose AI — the agent identifies itself as an AI receptionist by default. You can change the wording per scenario; in jurisdictions that require disclosure (more and more, every quarter), do not turn it off.
  • Respect time-of-day rules — schedule dispatches accordingly. The platform does not enforce per-country quiet hours yet.
  • Watch the spam classification — the platform flags inbound calls that look like spam to you, but it also tracks your outbound spam rate. If you trigger too many calls that hang up immediately, your caller ID reputation degrades. Slow down.

Rate limits

Per project, default outbound limits:

  • 5 calls per minute dispatch rate (raise on request)
  • No fixed daily cap — your wallet balance is the cap

Per API token, default limits:

  • 60 requests per minute on POST /v1/calls
  • 1000 requests per hour total
  • Idempotency-key dedup happens before rate-limiting, so retries do not count.

Higher limits available on request via sales@aitelier.org.