Documentation

Outbound calling

Documentation

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

  • By API — POST /v1/calls from your code, one call at a time. The most common path for production integrations.
  • By CSV batch — upload a contact list via the API and the platform paces the dial-outs for you. Built for campaigns and reminder runs.

Both end up running the same scenario in the same engine. To try a scenario interactively, use the in-browser Test call on the project Overview — it exercises the same agent without dialing anyone.

Triggering by API

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

{
  "scenarioId": "0d7e0f5a-…",
  "phone": "+34123456789",
  "parameters": {
    "customer_name": "Maria",
    "appointment_at": "2026-05-15T18:00:00Z"
  }
}

Fields:

  • scenarioId — the id of an outbound scenario in your project. Required.
  • phone — E.164 destination. Required.
  • parameters — optional key-value map your scenario can read during the call. Use it to pass per-call context (customer name, appointment time, order number).
  • callerIdNumber — optional; which of your verified caller IDs to present.
  • Idempotency-Key — recommended: your unique identifier for this call. Repeating the same key within 24 hours returns the original response without dialing twice — important when you retry a failed API request. Reusing a key with a different body returns 409.

The call is queued and dialed immediately; scheduled dispatch at a future time is on the roadmap (schedule on your side for now). The response carries the session id — fetch GET /v1/sessions/{id} for status and results.

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

Triggering by CSV batch

POST /v1/calls/bulk
Authorization: Bearer <project-api-key>
Content-Type: multipart/form-data

scenarioId=<uuid>
callerIdNumber=+1…        (optional)
csv=@contacts.csv

The CSV needs at least a phone column; every other column becomes a per-row parameter your scenario can read.

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

Up to 100,000 rows / 10 MB per batch. The platform paces dial-outs (5 calls per minute by default — raised per project on request) so you do not flood your own trunk or the destination carrier.

Track progress through the API:

  • GET /v1/calls/batches — list your batches
  • GET /v1/calls/batches/{id} — live counts: pending / live / completed / failed / abandoned
  • POST /v1/calls/batches/{id}/cancel — stop the remaining rows

Outcomes and failure reasons

Every completed outbound call resolves to an outcome (success / real conversation / spam) exactly like an inbound one. Calls that never became a conversation carry a typed failure reason instead:

  • no_answer — rang out, no human picked up.
  • busy — line was busy.
  • voicemail_detected — answering machine detected; the agent hangs up by default rather than talking to a machine (leaving voicemails is on the 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).

All of these surface in the session records, the batch counts and your webhook events.

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 recordings and full session records for your audit trail; 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.
  • Screen against your do-not-call list before triggering — the platform does not maintain a DNC list for you today, so filter your contact lists before they reach POST /v1/calls.
  • Disclose AI where required — put the disclosure in your scenario's greeting. More jurisdictions require it every year.
  • Respect time-of-day rules — trigger at appropriate local hours; the platform does not enforce per-country quiet hours.
  • Watch your connect rates — if you trigger many calls that fail or hang up immediately, your caller ID reputation degrades with carriers. Slow down.

Rate limits

  • 100 mutation requests per minute per API key (covers POST /v1/calls)
  • 5 dial-outs per minute batch pacing per project (raised on request)
  • Higher limits available — contact sales@aitelier.org.