Juhendid

Ülesanded

Ülesanne helistab ühe agendiga adressaatide loendile vastavalt reeglitele, mille te ette seate - eelarve, kõneaken, katsete arv. Midagi ei valita, kuni te ülesande ise käivitate.

Mis on ülesanne

Ülesanne (task_...) on väljaminevate kõnede kampaania: üks agent volai mootoril, adressaatide loend telefoninumbri ja valikuliste süsteemipromptimuutujatega ning reeglid (eelarve, kõneaken, katsete ja kõne kestuse maksimum). Eesmärgi järgi on kolm tüüpi - invoice (maksemeeldetuletus), appointment (kohtumise kinnitus) ja custom (kõik muu) - kahe esimese puhul, kui source on integration, kannab iga adressaat lisaks viidet arvele või sündmusele (externalRefs), mida agent kõne ajal mainib.

Olekud ja üleminekud

Praktikas läheb ülesanne alati olekust `draft` otse olekusse `running` (`start`); kustutamine (`DELETE`) töötab ainult märgitud olekutes.

Täpne kustutamistingimus: olek on üks märgitutest JA ühelgi kirjel pole status: "in_progress" (kõne, mille valimine algas ja pole lõppenud) - muidu task_not_deletable.

Adressaatide import (CSV)

POST /v1/tasks/csv-preview parsib CSV-faili ja tagastab selle koos ridade kaupa vigadega - MIDAGI ei salvestata, see on lihtsalt eelvaade enne ülesande loomist või uuendamist. Portaali uue ülesande vorm kutsub sama funktsiooni.

• Eraldaja tuvastatakse automaatselt (koma või semikoolon) esimesest reast.
• Veerg phone peab olema olemas - suur- ja väiketäht, ümbritsevad tühikud ja lõpukoolon ei loe ning aktsepteeritakse ka telefon, tel või mobile; eelvaade tagastab veeru alati nimega phone. Töötab ka paljas numbrite loend ilma päiseta (üks rea kohta, üks veerg). Muidu ebaõnnestub kogu CSV ühe phone veaga päisel.
• Iga teine veerg on agendi süsteemiprompti muutuja ({{column_name}}) - kuni 20 veergu, nimi kuni 64 märki, väärtus kuni 512 märki.
• Telefoninumber normaliseeritakse samamoodi nagu mujal API-s (normalizePhone) - kehtetu või tühi number on viga ainult SELLEL real, ülejäänud CSV töödeldakse ikkagi.
• Lahter, mis näeb välja nagu arvutustabeli valem (algab märgiga =, +, - või @), lükatakse tagasi - kaitse CSV-süstimise vastu faili Excelis avamisel.
• Kuni 1000 rida CSV kohta (sama ülempiir nagu ülesande adressaatide arv) ja 1 MB toorteksti; kogu ülesanne koos muutujatega peab mahtuma 2 MB sisse, muidu tagastab loomine validation.

Vastus sisaldab headers, delimiter, rows (iga rida oma vigadega), validRows (ainult korralikud, täpselt sellisel kujul, nagu POST /v1/tasks recipients ootab) ja koondmassiivi errors. Saatke validRows otse recipients väärtusena ülesande loomisel või uuendamisel.

Eelarve ja kõneaken

Eelarve

budgetHal on kogu ülesande kulutuste ÜLEMPIIR hellerites. Loomisel peab see katma vähemalt ühe katse maksimaalse kestusega (muidu budget_too_low); käivitamisel reserveeritakse enne IGAT valimist katse suurim võimalik hind (reservedBudgetHal) ja alles vastatud kõne muudab selle väärtuseks spentHal. Reservatsioon on täpselt maxDurationSecs kestva kõne hind (kõneliin ja agendiliin, kumbki ümardatud üles helleri täpsuseni täpselt nagu arvestuses) ja kõne, mille lõpetas kestuse piir, arvestatakse kuni maxDurationSecs eest, isegi kui see lõpeb sekundi murdosa hiljem. Ülesanne ei kuluta kunagi rohkem, kui te talle budgetHal andsite.

Kõneaken

callingWindow on {timezone: "Europe/Prague", start, end, days} - praegu on ainus toetatud ajavöönd Praha, start/end kujul HH:MM (lõpp hõlmab kogu seda minutit: aken 09:00-18:00 lubab kõne veel kell 18:00:59 ja aken, mis lõpeb kell 23:59, katab terve päeva) ja days on numbrid 0-6 (0 = pühapäev). Ilma selleta kehtivad tööpäevad 9:00-18:00. Väljaspool akent tagastab start vea window_closed - oodake kas akna taasavanemist või muutke akent käsuga PATCH. Valikuline expiresAt on kampaania tähtaeg positiivse ohutu täisarvulise Unixi ajatemplina millisekundites. Seda kontrollitakse käivitamisel ja enne iga valimist, esimene kaasa arvatud. Sellel tähtajal või pärast seda ei alga uut kõnet ja ühtegi katset ei kulutata; käimasolev kõne lõpeb tavapäraselt. Poliitika lorela_enterprise kordusvahemik (retryMaxAgeDays, vaikimisi 5) loeb selle asemel N × 24 tundi esimesest arvestatud katsest, mitte ülesande loomisest.

Katsed ja kõne kestus

maxAttempts on 1-3 ilma poliitikata (vaikimisi 1) või 1-4 poliitikaga retryPolicy: "lorela_enterprise" (vaikimisi loomisel 4). See on ühe kontakti automaatsete valimiste suurim arv, esimene kõne kaasa arvatud (1 = kordusi pole). Arvesse läheb iga katse, kus kõne oleks võinud toimuda, sealhulgas vastamata kõne, kõnealuse isiku keeldutud kõne ja ebaselge tulemusega katse. Katse, mille volai enne valimist tagasi lükkas, arvesse ei lähe (näiteks blokeeritud, teie enda või kehtetu number, helistamiskeelu loend, number, millel käib teine kõne, kõnepiirangud); sellise katse väärtus on items[].attempts[].countsAsAttempt: false. Arvesse ei lähe ka kõne, mille marsruut ei jõudnud õigel ajal operaatorini, nii et adressaadi telefon ei helisenud kunagi (katsel on errorCode: "relay_not_routed", kõnel endReason: "rejected"): kontakt saab uue katse mitte varem kui minuti pärast (poliitikaga lorela_enterprise selle ajakava järgi) ja pärast kolmandat sellist järjestikust katset läheb ülevaatusele väärtusega reviewReason: "call:relay_not_routed". Arvesse ei lähe ka kõne, millest meie häälmootor kunagi aru ei andnud ja mille me pärast kahte aruandeta tundi valimata ja tasuta suleme (katsel on errorCode: "no_provider_report"): kontakt läheb tagasi ootele ja saab uue katse mitte varem kui minuti pärast (poliitikaga lorela_enterprise selle ajakava järgi). Kolm arvesse mineamata katset järjest, ka segatult relay_not_routed katsetega, saadavad kontakti ülevaatusele viimase reviewReason väärtusega, see tähendab call:no_provider_report; kontakte, mille selline kõne oli ülevaatusele saatnud varem (call:failed või poliitikaga call:unknown), automaatselt uuesti ei avata. Ilma poliitikata kehtib ülempiir ainult automaatsetele valimistele: kontakt, millele te pärast katsete ammendumist annate resolve väärtusega action: "retry", saab veel ühe valimise. maxDurationSecs (30-300) piirab ÜHE kõne pikkust, mille järel see lõpeb automaatselt - vaikimisi kestus on 120 sekundit. Lubage valikuline poliitika lorela_enterprise API või MCP kaudu enne esimest katset; olemasolevad ülesanded ei muutu automaatselt. Teine katse on mitte varem kui 8 minutit pärast esimese tegeliku katse algust, vahemikus 08:00-22:00 Europe/Prague. Kolmas kasutab järgmist teist akent 08:00-09:00 või 17:00-19:00; neljas kasutab vastupidist akent järgmisel kalendripäeval. Ülesande callingWindow ja selle nädalapäevad kehtivad endiselt; ühtegi poliitikakordust ei alga pärast kordusvahemikku: valikuline retryMaxAgeDays, päevade täisarv 1-30 (5, kui puudub), kehtib ainult koos poliitikaga. Vahemik lõpeb N × 24 tundi pärast iga kontakti esimest arvestatud katset (kindlad 24-tunnised päevad, seega suveaja muutumisel nihkub kohalik lõppaeg tunni võrra). Seda saab muuta käsuga PATCH ka pärast katsete algust (mitte olekus running või completed ülesandel, mida ei saa muuta): selle tõstmine peatatud ülesandel viib ainult vahemiku tõttu vahele jäetud kontaktid (reviewReason: "retry_age_expired") tagasi olekusse failed (ootavad järgmist katset) uue nextAttemptAt väärtusega, kui neil on veel katse alles ning ajakava järgmine aken jääb uue vahemiku sisse ja enne expiresAt; selle alandamine ei ava midagi uuesti. Kontakte avab uuesti ainult PATCH, mis vahemikku tõstab, seega saatke retryMaxAgeDays koos pikendatud expiresAt väärtusega ühes päringus. Sobivad ainult no_answer, missed, busy, lõpetatud kõnepost ja vastatud kõne, milles kõnealune isik midagi ei öelnud (kõik ilma inimkontaktita). Inimkontakt, keeldumine ja mootoririke peatavad automaatsed kordused; ebaselged tulemused vajavad ülevaatust. Viimane lubatud katse (maxAttempts), mis lõpeb sellise korratava tulemusega (vastamata, hõivatud, kõnepost või vastatud kõne, milles kõnealune isik midagi ei öelnud), sulgeb kontakti kui skipped väärtusega reviewReason: "retry_policy_exhausted" (nagu retry_age_expired, kui vahemik lõpeb): ülevaatamiseks ega kordamiseks pole midagi. Viimase katse ebaselge tulemus jääb olekusse review sama põhjusega. Ilma poliitikata ei muutu midagi: viimane vastamata katse on endiselt review. Kontrollitud inimese tagasihelistus pärast katsete ammendumist muudab kontakti olekuks completed. DNC, eelarve ja kõnepiirangud kehtivad endiselt: automaatne blokeerimine pärast 3 ebaõnnestumist 24 tunni jooksul võib neljanda katse takistada. PATCH ilma maxAttempts säilitab olemasoleva piiri. Poliitikaga tagastab käsitsi resolve väärtusega action: "retry" vea validation; lubatud on ainult ajastatud automaatsed katsed. Tõendatult valimata aegunud nõude võib taastada enne esimest tegelikku katset: aktiivset töötajat, valimiskavatsust, teenusepakkuja kõnet, reservatsiooni, tasu ega tagasihelistust pole ja ajaloos on ainult tõendatud enne valimist tehtud tagasilükkamised. Taastamine säilitab ajaloo ja piirangud ning tagastab kontakti peatatud ülesandes ootele; see ei vali. Kupongimeeldetuletusi ei saa uuesti avada. Käsitsi kordus ei saa mööda minna neljast katsest, kordusvahemikust ega peatumisest pärast inimkontakti.

Üldine läbilaskevõime

Agendi töövoog

Tüüpiline käik selles järjekorras:

1. Ülesande agent peab olema AVALDATUD ja avaldatud versioon TESTITUD (POST /v1/agents/{id}/draft/publish, seejärel POST /v1/agents/{id}/simulate) - muidu tagastab hilisem start vea agent_not_ready.
2. Valikuliselt POST /v1/tasks/csv-preview - kontrollib adressaatide CSV-d enne ülesande loomist.
3. POST /v1/tasks - loob ülesande olekus draft. Midagi ei valita.
4. GET /v1/tasks/{id} - lugege issues (kuivkäivituse valideerimine) ja veenduge, et ülesanne on käivitamiseks valmis.
5. Vajadusel PATCH /v1/tasks/{id} - kohandage reegleid, ALATI viimasest lugemisest pärineva revision väärtusega.
6. POST /v1/tasks/{id}/start - alustab valimist. Iga vastatud kõne arvestatakse kohe.
7. POST /v1/tasks/{id}/pause mis tahes ajal töö ajal; POST /v1/tasks/{id}/start jätkab uuesti.
8. Pärast katkestust (kõne keskel peatamine, aegunud nõue, veel teadmata hinnaga kõne või ebaselge valimine, mille kõne leiti) ühitab POST /v1/tasks/{id}/reconcile oleku tegelike kõnedega; selline ülesanne, millel on tööd alles, jõuab olekusse paused, isegi kui mõned kontaktid ootavad olekus review, seega saab start selle jätkata. Töötavat ülesannet ja muid põhjuseid (variables_limit, ebaõnnestunud arve- või kalendrikontroll, valimine, mille kõnet ei leita) reconcile ei muuda; otsustage ülevaatusel olevad kontaktid käsuga resolve.
9. Otsustage kontakt, mis jõudis ülevaatusele (items[].status: "review"), lõpp-punktiga POST /v1/tasks/{id}/items/{itemId}/resolve ja action: "retry" või "skip". Tavalise kirjepõhise põhjuse korral viib retry kontakti tagasi ootele ja ülesande olekusse paused; skip sulgeb kontakti ja ülesanne muutub paused, kui tööd on alles, või completed, kui iga kontakt on lõpetatud või vahele jäetud. Jätkake olekus paused ülesannet käsuga POST /v1/tasks/{id}/start.
10. Kui kontaktil on reviewReason: "dial:destination_auto_blocked", on number pärast korduvaid vastamata kõnesid automaatselt blokeeritud 30 päevaks ja ainult retry seda ei vabasta - kontakt läheks kohe tagasi olekusse review. Tühistage kõigepealt blokeering (POST /v1/dnc/{e164}/unblock, MCP-s unblock_destination, võtke number väärtusest items[].phone), seejärel resolve väärtusega action: "retry". Väärtuse dial:on_dnc korral eemaldage number kõigepealt helistamiskeelu loendist (DELETE /v1/dnc/{e164}), muidu jätke kontakt vahele. Konto enda numbri, teise volai konto numbri, kehtetu numbri, väljaspool Tšehhit ja Slovakkiat asuva numbri ja kõrgendatud tasuga liini puhul (dial:cannot_call_own_number, dial:cannot_call_volai_number, dial:invalid_number, dial:unsupported_country, dial:blocked_destination) uus katse ei aita: kasutage ainult skip.
11. Kui kontaktil on reviewReason: "billing_unknown", võis algne kõne juba toimuda, kuid selle hind on veel teadmata. Kutsuge kõigepealt reconcile ja vaadake seotud kõnet. retry märgib, et kontakti tuleks uuesti proovida, kuid uut kõnet ei lubata, kuni algne hind on lahendatud; ülesanne läheb siis olekusse paused ja vajab uut start. skip takistab uut kõnet; algne kõne jääb seotuks ja selle reservatsioon loeb eelarvesse, kuni hind on lahendatud. Kui tööd on alles, läheb ülesanne pärast skip otse olekusse paused ja selle saab käivitada; kui tööd pole alles, ootab see olekus needs_attention ja muutub completed, kui hind on lahendatud. Kõne, millele kunagi ei valitud (mootor keeldus), ei arvestata kunagi ja see lahendatakse kohe väärtusega 0.
12. Kontakti kõneta vahelejätmiseks, sest ta on vahepeal ostnud või tellimusest loobunud, saatke resolve väärtustega action: "skip", reason: "customer_purchased" või "unsubscribed", revision, stabiilne operationId ja evidenceRef, mis viitab oste- või loobumiskirjele (mitte kunagi telefoninumbrile ega e-posti aadressile). See töötab kontaktil pending olekus draft ülesandes ning kontaktidel pending/failed olekus paused ülesandes, kus pole lahendamata kõnet, ja säilitab katsed, kulud ja helistamiskeelu loendi. GET /v1/tasks/{id} näitab siis kviitungit väljal items[].resolution (reason, operationId, evidenceRef, resolvedAt); sama keha kordamine on ohutu, samas kui sama kontakti jaoks teine reason või evidenceRef tagastab 409 revision_conflict. Vahelejätmine ei lisa numbrit helistamiskeelu loendisse: tehke seda käsuga POST /v1/dnc, kui kontaktile ei tohi enam kunagi helistada.
13. DELETE /v1/tasks/{id} lõpus, kui ülesanne ei töötanud kunagi või on juba lõppenud ja soovite kirje eemaldada.

Peaaegu iga kirjutuskutse (PATCH, start, pause, DELETE) võtab revision väärtuse ülesande viimasest lugemisest - sama optimistlik samaaegsuse kontroll nagu agendi mustanditel. Mittevastavus tagastab revision_conflict: lugege ülesanne uuesti (GET) ja korrake kehtiva revision väärtusega. Erand on reconcile - selle revision on valikuline.

MCP

Samad tööriistad nagu REST-is (list_tasks, get_task, create_task, update_task, pause_task, resolve_task_item, reconcile_task, start_task) - välja arvatud üks erinevus käivitamisel.

start_task kinnitab numbrid

MCP start_task võtab lisaks confirmedRecipients ja confirmedBudgetHal - need peavad täpselt vastama ülesande tegelikule adressaatide arvule ja eelarvele, muidu tagastab see validation koos tegelike väärtustega ja ei käivita MIDAGI. Nii ei saa kolmanda osapoole tehisintellekti agent, kes tegutseb ühe lõdvalt mõistetud juhise alusel, kogemata käivitada tasulist kampaaniat väljamõeldud numbritega - REST POST .../start sellist mehhanismi ei oma, sest seal kutsub seda konto omanik otse oma võtmega.

delete_task ja CSV eelvaade ei ole MCP-s - kustutamine jääb REST-i ja portaali (pöördumatu toiming, mis nõuab nime sisestamist) ning CSV eelvaade on lihtsalt vormi samm.

Vead

• task_not_found - Sellise id-ga ülesannet kontol ei ole.
• task_not_editable - Ülesanne töötab või on lõpetatud või on needs_attention ilma taastamisvõimaluseta - selle reegleid ei saa praegu muuta. POST .../items/{itemId}/resolve tagastab töötava ülesande puhul sama koodi: kontakt olekus review ilmub, kui ülesanne on veel running ja valib teisi - oodake, kuni see läheb olekusse needs_attention, või peatage see (POST .../pause).
• items_immutable - Adressaatide loendit ei saa asendada, kui on toimunud vähemalt üks valimiskatse või kontakt on vahele jäetud väärtusega reason (ost või tellimusest loobumine).
• budget_too_low - Eelarve ei kata isegi ühte katset maksimaalse kõne kestusega - tõstke budgetHal või alandage maxDurationSecs.
• task_not_startable - Ülesanne ei ole olekus draft/ready/paused või pole enam ühtegi adressaati, kellele helistada.
• task_needs_attention - Enne järgmist käivitamist on vaja POST .../reconcile - midagi (agendi versioon, mootor) muutus töö ajal.
• agent_not_ready - Agendi mustand on kas avaldamata või avaldatud versiooni pole testitud - avaldage see (POST /v1/agents/{id}/draft/publish) ja simuleerige seejärel avaldatud versiooni (POST /v1/agents/{id}/simulate) enne käivitamist.
• agent_version_changed - Agendi konfiguratsioon muutus ajal, mil ülesanne TÖÖTAS - testige seda ja käivitage uuesti käsuga reconcile.
• engine_required - Ülesande agent ei ole volai mootoril (useForOutboundTasks: true) - väljaminevad ülesanded nõuavad praegu mootorit, mitte ElevenLabsi.
• engine_contract_unavailable - Mootor ei teata praegu väljaminevate ülesannete muutujate ja piirangute toetust - proovige hiljem uuesti käivitada.
• window_closed - Väljaspool seadistatud kõneakent - oodake selle taasavanemist või muutke callingWindow.
• task_not_running - Peatamine töötab ainult töötaval ülesandel.
• item_not_resolvable - Kontakt ei ole olekus review - otsus (retry/skip) on võimalik ainult ülevaatust ootava kontakti puhul ja ainult siis, kui ülesanne ei tööta. Erand on vahelejätmine väärtusega reason (customer_purchased, unsubscribed): see nõuab mitteaktiivset pending kontakti draft ülesandes või pending/failed kontakti paused ülesandes, kus pole lahendamata kõnet.
• task_not_deletable - Kustutada saab ainult ülesande, mille ühtegi kirjet pole pooleli ja mis on olekus draft/ready/paused/completed/needs_attention.
• revision_conflict - Ülesanne muutus vahepeal - lugege see uuesti (GET) ja korrake kehtiva revision väärtusega.

Kõigi lõpp-punktide täielik veatabel on REST API viite jaotises Tasks.