Dokumentace

Odchozí volání

Dokumentace

Outbound je způsob, jak váš agent volá lidem místo čekání, až ho zavolají. Dva spouštěče pokrývají skoro každou reálnou potřebu:

  • Přes API — POST /v1/calls z vašeho kódu, jeden hovor po druhém. Nejčastější cesta pro produkční integrace.
  • CSV dávkou — nahrajte seznam kontaktů přes API a platforma pro vás řídí tempo vytáčení. Postaveno pro kampaně a běhy připomínek.

Oba končí spuštěním stejného scénáře ve stejném enginu. Pro interaktivní vyzkoušení scénáře použijte Test call v prohlížeči na Overview projektu — cvičí stejného agenta, aniž by někoho vytáčel.

Spouštění přes 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"
  }
}

Pole:

  • scenarioId — id outbound scénáře ve vašem projektu. Povinné.
  • phone — cílové číslo v E.164. Povinné.
  • parameters — volitelná mapa klíč–hodnota, kterou scénář může během hovoru číst. Použijte k předání kontextu per hovor (jméno zákazníka, čas schůzky, číslo objednávky).
  • callerIdNumber — volitelné; které z vašich ověřených caller ID se má prezentovat.
  • Idempotency-Key — doporučeno: váš unikátní identifikátor tohoto hovoru. Opakování stejného klíče do 24 hodin vrátí původní odpověď bez druhého vytáčení — důležité při retry neúspěšného API requestu. Znovupoužití klíče s jiným body vrátí 409.

Hovor se zařadí do fronty a vytáčí se ihned; naplánované spuštění v budoucnu je na roadmapě (zatím plánujte na své straně). Odpověď nese session id — stav a výsledky stáhnete přes GET /v1/sessions/{id}.

API klíče se vydávají v záložce projektu API keys. Klíče jsou scoped — dejte klíči jen oprávnění, která potřebuje (outbound:trigger, sessions:read). Rotace: vydejte nový klíč a starý odvolejte.

Spouštění CSV dávkou

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

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

CSV potřebuje alespoň sloupec phone; každý další sloupec se stane parametrem na řádek, který scénář může číst.

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

Až 100 000 řádků / 10 MB na dávku. Platforma řídí tempo vytáčení (ve výchozím stavu 5 hovorů za minutu — na žádost se per project zvyšuje), abyste nezahltili vlastní trunk ani cílového operátora.

Průběh sledujte přes API:

  • GET /v1/calls/batches — seznam dávek
  • GET /v1/calls/batches/{id} — živé počty: pending / live / completed / failed / abandoned
  • POST /v1/calls/batches/{id}/cancel — zastavit zbývající řádky

Výsledky a důvody selhání

Každý dokončený odchozí hovor se stejně jako příchozí vyhodnotí na outcome (success / real conversation / spam). Hovory, které se nikdy nestaly konverzací, místo toho nesou typovaný důvod selhání:

  • no_answer — vyzvánělo, nikdo nezvedl.
  • busy — linka byla obsazená.
  • voicemail_detected — detekován záznamník; agent ve výchozím stavu zavěsí, místo aby mluvil se strojem (zanechávání hlasových zpráv je na roadmapě).
  • invalid_number — cílové číslo není v provozu.
  • caller_id_unauthorized — operátor cíle odmítl naše caller ID.
  • provider_error — chyba telekomunikačního poskytovatele (vzácné).
  • internal_error — chyba platformy (vzácné; vyšetřuje se).

To vše se objeví v záznamech session, počtech dávky a vašich webhook eventech.

Compliance — vaše odpovědnost

Odchozí volání je regulované. Přesná pravidla závisí na zemi cíle, denní době a na tom, k čemu dal volaný souhlas. Platforma vám dává nahrávky a úplné záznamy session pro audit trail; soulad s TCPA (USA), GDPR (EU) nebo místními předpisy je vaše odpovědnost.

Praktické pokyny:

  • Získejte souhlas před voláním — uchovávejte důkaz. Nevolejte lidem, kteří o volání nepožádali.
  • Před spuštěním filtrujte do-not-call seznam — platforma dnes pro vás DNC seznam nevede, filtrujte seznamy kontaktů dřív, než dorazí na POST /v1/calls.
  • Kde je to povinné, přiznejte AI — disclosure dejte do pozdravu scénáře. Stále víc jurisdikcí to vyžaduje každý rok.
  • Respektujte pravidla denní doby — spouštějte v přiměřených místních hodinách; platforma neprosazuje quiet hours per země.
  • Sledujte connect rates — pokud spouštíte mnoho hovorů, které selžou nebo hned zavěsí, reputace vašeho caller ID u operátorů klesá. Zpomalte.

Rate limity

  • 100 mutačních requestů za minutu na API klíč (pokrývá POST /v1/calls)
  • 5 dial-outů za minutu pacing dávky na projekt (na žádost se zvyšuje)
  • Vyšší limity k dispozici — kontaktujte sales@aitelier.org.