Siirry sisältöön

Oppaat

Tehtävät

Tehtävä soittaa vastaanottajalistan läpi yhdellä agentilla etukäteen asetettujen sääntöjen mukaan - budjetti, soittoikkuna, yritysten määrä. Mitään ei soiteta, ennen kuin tehtävä käynnistetään käsin.

Mikä tehtävä on

Tehtävä (task_...) on lähtevä kampanja: yksi agentti volain moottorissa, vastaanottajalista puhelinnumeroineen ja valinnaisine järjestelmäkehotteen muuttujineen sekä säännöt (budjetti, soittoikkuna, yritysten ja puhelun keston enimmäismäärä). Tyyppejä on kolme käyttötarkoituksen mukaan - invoice (maksumuistutus), appointment (ajan vahvistus) ja custom (kaikki muu) - ja kahdella ensimmäisellä jokainen vastaanottaja kantaa lisäksi, kun source on integration, viittausta asiakirjaan tai tapahtumaan (externalRefs), jonka agentti mainitsee puhelussa.

Agentin on oltava volain omassa moottorissa (useForOutboundTasks: true luotaessa, ks. POST /v1/agents), ei ElevenLabsissa - moottori hoitaa järjestelmäkehotteen muuttujat, puhelun keston katon ja sen tarkistuksen, ettei sen kokoonpano ole muuttunut kampanjan aikana. Agentin luonnoksen on oltava JULKAISTU (PATCH /v1/agents/{id} tai POST /v1/agents/{id}/draft/publish) JA julkaistun version on oltava TESTATTU (POST /v1/agents/{id}/simulate) - jos jompikumpi vaihe puuttuu, käynnistys palauttaa agent_not_ready.

Tilat ja siirtymät

Käytännössä tehtävä siirtyy aina suoraan tilasta `draft` tilaan `running` (`start`); poistaminen (`DELETE`) onnistuu vain merkityissä tiloissa.

draft
Mitä se tarkoittaaJuuri luotu, start ei ole koskaan ajettu. Muokattavissa (PATCH), voidaan poistaa.
ready
Mitä se tarkoittaaMallin tila draft- ja running-tilojen välissä, jonka start hyväksyy lähtökohdaksi - mikään julkinen endpoint (ei REST eikä MCP) ei kuitenkaan nykyisin siirrä tehtävää sinne, joten käytännössä sitä ei esiinny. Jos se syntyisi, se on muokattavissa ja poistettavissa samoin kuin draft.
running
Mitä se tarkoittaaSoittaa vastaanottajille. EI MUOKATTAVISSA - PATCH palauttaa task_not_editable ilman poikkeuksia. Jos muuttujia on muutettava, tehtävä on ensin pysäytettävä (POST .../pause) ja muutettava vasta tilassa paused - ja vain niin kauan kuin yhtäkään vastaanottajaa ei ole vielä soitettu; ensimmäisen yrityksen jälkeen recipients (ja sen mukana muuttujia) ei voi enää vaihtaa (items_immutable) ja jäljelle jää uuden tehtävän luominen. Ei voi poistaa. Kun tehtävä osuu puhelurajaan (rate_limited - oman moottorin lähtevien minuuttien raja, samanaikaisten lähtevien puheluiden katto, oletuksena 10 puhelua minuutissa tai 1000 vuorokaudessa), se pysyy tilassa running: se asettaa lastError: "rate_limited", yritystä ei lasketa ja odottaville yhteystiedoille asetetaan items[].nextAttemptAt rajan päättyessä (Retry-Afterin mukaan, muuten 5 minuutin kuluttua; moottorin samanaikaisten puheluiden kattoa vastaan moottori lähettää Retry-After: 30). Ajan kuluttua se jatkuu itsestään. Samoin se odottaa, kun tilin samanaikaisten agenttipuheluiden kiintiö on täynnä (relay_lease_limit, oletuksena 2 käynnissä olevaa puhelua): lastError: "relay_lease_limit", seuraava yritys minuutin kuluttua, yritystä ei lasketa. Varattu numero (destination_busy - samaan numeroon on juuri käynnissä toinen puhelu, esimerkiksi toisesta tehtävästä tai käsin soitettu, tai numero on lukittu 15 minuutiksi epävarman soiton jälkeen) panee odottamaan vain kyseisen yhteystiedon, ei koko tehtävää: items[].lastError: "destination_busy", items[].nextAttemptAt numeron jäljellä olevan lukitusajan mukaan (vähintään 30 s, enintään 16 min, ilman lukitusta 90 s), yritystä ei lasketa (countsAsAttempt: false) ja muille yhteystiedoille soitetaan edelleen. Kuudennen peräkkäisen varattu-merkin jälkeen (eli 5 odotuksen jälkeen) yhteystieto siirtyy tilaan review arvolla reviewReason: "dial:destination_busy". Pysyvä este numerossa (on_dnc, destination_auto_blocked, cannot_call_own_number, cannot_call_volai_number, invalid_number, unsupported_country, blocked_destination) ei myöskään pysäytä tehtävää: yhteystieto siirtyy tilaan review arvolla reviewReason: "dial:<code>" (puhelua ei syntynyt, joten yrityksellä on countsAsAttempt: false eikä se kuluta maxAttempts-arvoa), tehtävä pysyy tilassa running, soittaa muille yhteystiedoille ja siirtyy tilaan needs_attention vasta, kun muuta työtä ei ole jäljellä. Jos volain operaattori keskeyttää tehtävän agentin käsin, tehtävä pysyy tilassa running eikä soita mitään; jatkamisen jälkeen se jatkuu itsestään. Keskeytetyn agentin tunnistaa kohdasta suspended: true vastauksessa GET /v1/agents/{id}.
paused
Mitä se tarkoittaaPysäytetty ennen seuraavaa puhelua (POST .../pause); jo käynnissä oleva puhelu päättyy. Muokattavissa, voidaan poistaa, start jatkaa sitä. Tauko kesken puhelun jättää arvon reviewReason: "dispatch_in_flight", kunnes reconcile (ajastin ajaa sen muutaman minuutin sisällä) on tilittänyt kyseisen puhelun, ja siihen asti start hylkää pyynnön virheellä task_needs_attention; sen jälkeen tehtävä, jolla on työtä jäljellä, pysyy tilassa paused, vaikka muut yhteystiedot odottaisivat tilassa review. Tauko juuri ennen varsinaista puhelua (puhelua ei ole vielä syntynyt) ei jätä arvoa dispatch_in_flight: ajastin palauttaa yhteystiedon odottavien joukkoon ja tehtävä on heti tilassa paused ilman syytä. Yhteystieto, jonka käsittely keskeytyi kaatumiseen ennen puhelun syntymistä, vapautetaan reconcilella aikaisintaan 15 minuuttia soiton aloittamisen jälkeen (claim 10 minuuttia plus 5 minuutin marginaali) ja palautetaan odottavien joukkoon; tehtävä, joka sillä välin pysähtyi vanhentuneeseen claimiin (dispatch_claim_expired), siirtyy silloin tilaan paused. Jos käynnissä oleva puhelu päättyy ilman tunnettua hintaa, tehtävä siirtyy ensin tilaan needs_attention arvolla reviewReason: "billing_unknown" ja palaa tilaan paused, kun hinta on saatu (reconcile täydentää sen). Jos maxAttempts laskee sillä välin niin, ettei yhdelläkään seuraavaa yritystä odottavalla yhteystiedolla ole enää vapaata yritystä, tehtävä pysyy tilassa paused (tällainen yhteystieto lasketaan työksi), mutta start hylkää sen virheellä task_not_startable, kunnes maxAttempts nostetaan.
completed
Mitä se tarkoittaaKaikilla vastaanottajilla on lopullinen tulos. Voidaan poistaa (mikään ei ole enää voimassa).
needs_attention
Mitä se tarkoittaaJokin vaatii väliintuloa - yleensä agentin kokoonpano on muuttunut ajon aikana (agent_version_changed), moottori on ollut tilapäisesti poissa käytöstä (engine_contract_unavailable) tai jo toteutuneen puhelun hintaa ei vielä tiedetä (billing_unknown). POST .../reconcile korjaa tilanteen; voidaan poistaa, kunhan mikään kohde ei ole jäänyt tilaan in_progress. Tilassa review oleva yhteystieto käsitellään kutsulla POST .../items/{itemId}/resolve (retry/skip); yhteystieto, jonka numerossa on pysyvä este (dial:on_dnc, dial:destination_auto_blocked, dial:cannot_call_own_number, dial:cannot_call_volai_number, dial:invalid_number, dial:unsupported_country, dial:blocked_destination tai dial:destination_busy kuudennen peräkkäisen varattu-merkin jälkeen), pysäyttää tehtävän vasta, kun muut yhteystiedot on käyty läpi. Soiton epävarma tulos (esimerkiksi dial:engine_unavailable) siirtää tehtävän heti tilaan needs_attention eikä muille yhteystiedoille soiteta. Kun tällaisen katkoksen (tai tuntemattoman hinnan) takana oleva puhelu on tilitetty reconcilella, tehtävä siirtyy tilaan paused, kunhan jokin yhteystieto odottaa seuraavaa yritystä, vaikka toiset olisivat tilassa review; tilaan needs_attention vain, kun soitettavaa ei ole jäljellä paitsi yksi yhteystieto tilassa review, ja tilaan completed, kun mitään ei ole jäljellä. Soitto, jonka tulos pysyy epävarmana (puhelua ei löydy), pitää tehtävän tilassa needs_attention, kunnes yhteystieto on ratkaistu. Tavallisen syyn kohdalla tehtävä siirtyy viimeisen ratkaisun jälkeen tilaan paused, jos työtä on jäljellä, tai tilaan completed, jos kaikki yhteystiedot on käsitelty tai ohitettu. Koko tehtävän tason syy pysyy tilassa needs_attention, kunnes se on ratkaistu; poikkeus on budget_exceeded, jossa kaikkien seuraavaa yritystä odottavien yhteystietojen ohittaminen päättää tehtävän, jos mitään palveluntarjoajan tilaa ei enää odoteta. Erityinen menettely tilalle billing_unknown on alla.

Poistamisen tarkka ehto: tila on yksi yllä merkityistä JA YHDELLÄKÄÄN kohteella ei ole tilaa status: "in_progress" (käynnissä oleva puhelu, joka ei ole vielä päättynyt) - muuten task_not_deletable.

Vastaanottajien tuonti (CSV)

POST /v1/tasks/csv-preview jäsentää CSV-tiedoston ja palauttaa sen yksittäisten rivien virheineen - MITÄÄN EI tallenneta, kyse on vain esikatselusta ennen tehtävän luomista tai muuttamista. Samaa toimintoa kutsuu portaalin uuden tehtävän lomake.

  • Erotin tunnistetaan automaattisesti (pilkku tai puolipiste) ensimmäisen rivin perusteella.
  • Sarake phone on pakollinen - isoilla ja pienillä kirjaimilla, nimen ympäröivillä välilyönneillä ja sen perässä olevalla kaksoispisteellä ei ole väliä, ja myös telefon, tel tai mobil hyväksytään; esikatselussa sarake palautetaan aina nimellä phone. Pelkkä numeroluettelo ilman otsikkoa (yksi per rivi, yksi sarake) hyväksytään myös. Muuten koko CSV hylätään yhdellä virheellä phone otsikon kohdalla.
  • Jokainen lisäsarake on muuttuja agentin järjestelmäkehotteelle ({{column_name}}) - enintään 20 saraketta, nimi enintään 64 merkkiä, arvo enintään 512 merkkiä.
  • Puhelinnumero normalisoidaan samalla tavalla kuin kaikkialla API:ssa (normalizePhone) - virheellinen tai tyhjä numero on virhe vain KYSEISELLÄ rivillä, loput CSV:stä käsitellään edelleen.
  • Solu, joka näyttää taulukkolaskentakaavalta (alkaa merkillä =, +, - tai @), hylätään - suoja CSV-injektiota vastaan, kun tiedosto avataan Excelissä.
  • Enintään 1000 riviä per CSV (sama katto kuin tehtävän vastaanottajien määrä) ja 1 Mt raakatekstiä; koko tehtävän liitteineen on mahduttava 2 Mt:iin, muuten luominen palauttaa validation.

Vastaus sisältää kentät headers, delimiter, rows (jokainen rivi virheineen), validRows (vain virheettömät, täsmälleen siinä muodossa, jota recipients odottaa kutsussa POST /v1/tasks) ja yhteenvedon errors. validRows lähetetään suoraan recipients-arvona tehtävää luotaessa tai muutettaessa.

Budjetti ja soittoikkuna

Budjetti

budgetHal on koko tehtävän menojen KATTO pienimmässä yksikössä (hal). Luotaessa sen on katettava vähintään yksi enimmäispituinen yritys (muuten budget_too_low); käynnistyksessä ennen JOKAISTA soittoa varataan yrityksen suurin mahdollinen hinta (reservedBudgetHal), ja vasta vastattu puhelu siirtää sen arvoon spentHal. Varaus on täsmälleen maxDurationSecs kestävän puhelun hinta (soittajan puoli ja agentin puoli, kumpikin pyöristettynä ylöspäin yhteen haliin samoin kuin veloituksessa), ja keston katon katkaisema puhelu veloitetaan enintään maxDurationSecs-ajalta, vaikka se päättyisi sekunnin murto-osan myöhemmin. Tehtävä ei koskaan kuluta enempää kuin budgetHal-arvossa on määritetty.

Soittoikkuna

callingWindow on {timezone: "Europe/Prague", start, end, days} - nykyisin tuetaan vain Prahan aikavyöhykettä, start/end muodossa HH:MM (loppu mukaan lukien koko minuutti: ikkuna 09:00-18:00 päästää läpi viimeisen puhelun kello 18:00:59, ikkuna 23:59:ään asti kattaa koko vuorokauden) ja days ovat luvut 0-6 (0 = sunnuntai). Ilman määritystä voimassa ovat arkipäivät 9:00-18:00. Ikkunan ulkopuolella start palauttaa window_closed - odota, kunnes ikkuna aukeaa, tai muuta ikkunaa kutsulla PATCH. Valinnainen expiresAt on kampanjan loppu positiivisena kokonaislukuna Unix-millisekunteina. Se tarkistetaan käynnistyksessä ja ennen jokaista soittoa, ensimmäinen mukaan lukien. Tuosta hetkestä alkaen uutta puhelua ei aloiteta eikä yritystä kuluteta; käynnissä oleva puhelu päättyy. Käytännön lorela_enterprise toistohorisontti (retryMaxAgeDays, oletus 5) lasketaan sen sijaan N × 24 tuntia ensimmäisestä lasketusta yrityksestä, ei tehtävän luomisesta. Kun agentti soittaa toisen maan numerosta, ikkuna noudattaa sen sijaan maan paikallista aikaa (Kanadan numerot America/Winnipeg, Meksikon numerot America/Mexico_City) ja tehtävä palauttaa kyseisen aikavyöhykkeen.

Numerosta maassa, jossa vastaanottajan paikallista aikaa ei ole varmennettu (Australia ja Uusi-Seelanti), ei ajasteta tehtäviä eikä kampanjoita: luominen tai käynnistys päättyy virheeseen destination_not_allowed. Saapuvat puhelut ja yksittäiset puhelut eivät vaikuta.

Yritykset ja puhelun kesto

maxAttempts on 1-3 ilman käytäntöä (oletus 1), käytännöllä retryPolicy: "lorela_enterprise" 1-4 (luotaessa oletus 4). Se ilmoittaa yhteystiedolle tehtävien automaattisten soittojen enimmäismäärän, ensimmäinen mukaan lukien (1 = ei toistoa). Jokainen yritys, jossa puhelu olisi voinut toteutua, lasketaan, eli myös vastaamattomat tai soitetun hylkäämät sekä epävarman tuloksen yritys. Yritystä, jonka volai hylkäsi jo ennen soittoa, ei lasketa (esimerkiksi estetty, oma tai virheellinen numero, soittokieltolista, numero, johon on juuri käynnissä toinen puhelu, puhelurajat); tällaisella yrityksellä on items[].attempts[].countsAsAttempt: false. Ei lasketa myöskään puhelua, jonka kohdetta operaattori ei saanut ajoissa, jolloin soitetun puhelin ei koskaan soinut (yrityksellä on errorCode: "relay_not_routed", puhelulla endReason: "rejected"): yhteystieto saa uuden yrityksen aikaisintaan minuutin kuluttua (käytännöllä lorela_enterprise sen aikataulun mukaan) ja kolmannen tällaisen peräkkäisen yrityksen jälkeen se siirtyy tarkistukseen arvolla reviewReason: "call:relay_not_routed". Ei lasketa myöskään puhelua, josta puhemoottorimme ei koskaan raportoinut ja jonka suljimme kahden tunnin hiljaisuuden jälkeen ei-soitettuna ja ilman hintaa (yrityksellä on errorCode: "no_provider_report"): yhteystieto palaa odottavien joukkoon ja saa uuden yrityksen aikaisintaan minuutin kuluttua (käytännöllä lorela_enterprise sen aikataulun mukaan). Kolme laskematonta yritystä peräkkäin, myös tyypin relay_not_routed yrityksiin sekoitettuina, siirtää yhteystiedon tarkistukseen viimeisen niistä vastaavalla reviewReason-arvolla, eli call:no_provider_report; yhteystiedot, jotka tällainen puhelu on aiemmin siirtänyt tarkistukseen (call:failed, käytännöllä call:unknown), eivät jatku itsestään. Ilman käytäntöä katto koskee vain automaattisia soittoja: yhteystieto, joka kulutettujen yritysten jälkeen saa resolve-kutsun arvolla action: "retry", saa vielä yhden soiton. maxDurationSecs (30-300) on YHDEN puhelun keston katto, jonka jälkeen se päättyy automaattisesti - oletuskesto on 120 sekuntia. Valinnainen käytäntö lorela_enterprise kytketään päälle API:n tai MCP:n kautta ennen ensimmäistä yritystä; olemassa olevat tehtävät eivät muutu itsestään. Toinen yritys tapahtuu aikaisintaan 8 minuuttia ensimmäisen varsinaisen yrityksen alusta ajalla 08:00-22:00 Europe/Prague. Kolmas siirtyy seuraavaan toiseen ikkunaan 08:00-09:00 tai 17:00-19:00, neljäs vastakkaiseen ikkunaan seuraavana kalenteripäivänä. Aina on voimassa myös callingWindow päivineen; toistohorisontin jälkeen käytäntö ei soita uudelleen: valinnainen retryMaxAgeDays on kokonaisluku päiviä 1-30 (ilman määritystä 5) ja koskee vain käytäntöä. Horisontti päättyy N × 24 tuntia yhteystiedon ensimmäisen lasketun yrityksen jälkeen (kiinteät 24 tunnin vuorokaudet, joten kellonsiirron yli lopun paikallinen aika siirtyy tunnilla). Sitä voi muuttaa kutsulla PATCH vielä yritysten alettuakin (ei tehtävälle, joka on tilassa running tai completed, sitä ei voi muuttaa): korotus keskeytetylle tehtävälle palauttaa pelkästään horisontin vuoksi pudonneet yhteystiedot (reviewReason: "retry_age_expired") tilaan failed (odottaa seuraavaa yritystä) uudella nextAttemptAt-arvolla, jos niillä on vielä vapaa yritys ja aikataulun lähin slotti osuu uuden horisontin sisään ja ennen arvoa expiresAt; lasku ei avaa mitään. Vain horisonttia korottava PATCH avaa uudelleen, joten retryMaxAgeDays ja pidennetty expiresAt on lähetettävä samassa kutsussa. Käytäntö toistaa vain no_answer, missed, busy, loppuun asti kuullun vastaajaviestin ja vastatun puhelun, jossa soitettu ei sanonut mitään (kaikki ilman kontaktia ihmiseen). Kontakti ihmiseen, hylkääminen ja moottorivirhe pysäyttävät automaattisen toiston; epäselvä tulos menee tarkistukseen. Viimeinen sallittu yritys (maxAttempts), joka päättyy tällaiseen toistettavaan tulokseen (vastaamaton, varattu, vastaaja tai vastattu puhelu, jossa soitettu ei sanonut mitään), sulkee yhteystiedon tilaan skipped arvolla reviewReason: "retry_policy_exhausted" (kuten retry_age_expired horisontin umpeuduttua): tarkistettavaa tai toistettavaa ei ole. Viimeisen yrityksen epäselvä tulos jää tilaan review samalla syyllä. Ilman käytäntöä mikään ei muutu: viimeinen vastaamaton yritys on edelleen review. Varmennettu ihmisen takaisinsoitto kulutettujen yritysten jälkeen asettaa yhteystiedon tilaan completed. DNC, budjetti ja rajat ovat edelleen voimassa: automaattinen esto 3 epäonnistumisen jälkeen 24 tunnin aikana voi pysäyttää myös neljännen yrityksen. Kutsussa PATCH ilman maxAttempts-arvoa aiempi raja säilyy. Käytännöllä manuaalinen resolve arvolla action: "retry" palauttaa virheen validation; sallittuja ovat vain sen automaattisesti ajastetut yritykset. Poikkeus on todistetusti soittamatta jääneen vanhentuneen claimin palautus ennen ensimmäistä varsinaista yritystä: ilman aktiivista workeria, dispatch-aikomusta, provider call ID:tä, varausta, hintaa tai callbackia ja vain todistetuilla ennen soittoa tapahtuneilla hylkäyksillä historiassa. Palautus säilyttää historian ja katot ja palauttaa yhteystiedon keskeytetyn tehtävän odottavien joukkoon; se ei itse soita. Muistutuksia ei voi avata uudelleen tällä tavalla. Manuaalinen toisto ei siis ohita neljää yritystä, toistohorisonttia eikä päättymistä ihmiskontaktin jälkeen.

Koko alustan läpäisykyky

Kaikkien tehtävien soitto KOKO alustalla (ei vain oman tilin) kulkee yhden cronin kautta, joka ajetaan kahden minuutin välein ja käsittelee enintään 20 kohdetta per ajo - MUTTA katto jaetaan samanaikaisesti käynnissä olevien tehtävien kesken, jotta yksi tehtävä ei voi kuluttaa sitä kokonaan: JOKAISESTA aktiivisesta tehtävästä soitetaan ajoa kohden täsmälleen YKSI vastaanottaja. Siksi myös täysin tyhjällä alustalla tehtävä ei koskaan soita useampaa kuin yhdelle vastaanottajalle 2 minuutissa - sata vastaanottajaa ei siis valmistu ~20 minuutissa vaan noin 200 minuutissa (100 x 2 minuuttia). Suunnittele soittoikkuna sen mukaan aikakriittisissä kampanjoissa (esimerkiksi appointment edellisenä päivänä ennen ajankohtaa).

Agentin työnkulku

Tyypillinen kulku tässä järjestyksessä:

  1. Tehtävän agentin on oltava JULKAISTU ja julkaistun version TESTATTU (POST /v1/agents/{id}/draft/publish, sen jälkeen POST /v1/agents/{id}/simulate) - muuten myöhempi start palauttaa agent_not_ready.
  2. Valinnaisesti POST /v1/tasks/csv-preview - tarkistaa vastaanottajien CSV:n ennen tehtävän luomista.
  3. POST /v1/tasks - luo tehtävän tilaan draft. Mitään ei soiteta.
  4. GET /v1/tasks/{id} - lue issues (dry-run-validointi) ja tarkista, että tehtävä on valmis käynnistettäväksi.
  5. Tarvittaessa PATCH /v1/tasks/{id} - säädä sääntöjä, AINA viimeisimmästä lukemisesta saadulla revision-arvolla.
  6. POST /v1/tasks/{id}/start - käynnistää soiton. Jokainen vastattu puhelu veloitetaan heti.
  7. POST /v1/tasks/{id}/pause milloin tahansa ajon aikana, POST /v1/tasks/{id}/start jatkaa taas.
  8. Katkoksen jälkeen (tauko kesken puhelun, vanhentunut claim, puhelu, jonka hinta on vielä tuntematon, tai epävarma soitto, jossa puhelu on löytynyt) POST /v1/tasks/{id}/reconcile täsmäyttää tilan todellisiin puheluihin; tällainen tehtävä, jolla on työtä jäljellä, päätyy tilaan paused, vaikka jotkin yhteystiedot odottaisivat tilassa review, ja sen voi käynnistää uudelleen kutsulla start. Käynnissä olevaa tehtävää tai muuta syytä (variables_limit, epäonnistunut laskun tai kalenterin tarkistus, epävarma soitto, jossa puhelua ei löytynyt) reconcile ei muuta; tarkistettavat yhteystiedot käsitellään kutsulla resolve.
  9. Tarkistukseen päätynyt yhteystieto (items[].status: "review") käsitellään kutsulla POST /v1/tasks/{id}/items/{itemId}/resolve arvolla action: "retry" tai "skip". Tavallisen syyn kohdalla retry palauttaa yhteystiedon odottavien joukkoon ja tehtävän tilaan paused; skip sulkee sen ja tehtävä siirtyy tilaan paused, jos työtä on jäljellä, tai tilaan completed, jos kaikki yhteystiedot on käsitelty tai ohitettu. Tilassa paused oleva tehtävä jatketaan sitten kutsulla POST /v1/tasks/{id}/start.
  10. Kun yhteystiedolla on reviewReason: "dial:destination_auto_blocked", numero on estetty automaattisesti 30 päiväksi toistuvien vastaamattomien puhelujen jälkeen eikä pelkkä retry poista estoa - yhteystieto päätyisi heti uudelleen tilaan review. Poista ensin esto (POST /v1/dnc/{e164}/unblock, MCP:ssä unblock_destination, numero haetaan kentästä items[].phone) ja tee sen jälkeen resolve arvolla action: "retry". Kun kyseessä on dial:on_dnc, numero poistetaan ensin soittokieltolistalta (DELETE /v1/dnc/{e164}), muuten yhteystieto ohitetaan. Tilin oman numeron, toisen volai-tilin numeron, virheellisen numeron, Tšekin ja Slovakian ulkopuolisen numeron ja lisämaksullisen numeron (dial:cannot_call_own_number, dial:cannot_call_volai_number, dial:invalid_number, dial:unsupported_country, dial:blocked_destination) kohdalla uusi yritys ei auta: käytä vain skip.
  11. Kun yhteystiedolla on reviewReason: "billing_unknown", alkuperäinen puhelu on voinut jo toteutua, vain hintaa ei vielä tunneta. Kutsu ensin reconcile ja tarkista siihen liittyvä puhelu. retry merkitsee, että yhteystieto yritetään uudelleen, mutta ei salli uutta puhelua, ennen kuin alkuperäinen hinta on saatu; sen jälkeen tehtävä siirtyy tilaan paused ja vaatii uuden start-kutsun. skip estää lisäpuhelut; alkuperäinen puhelu pysyy liitettynä ja sen varaus lasketaan edelleen mukaan budjettiin, kunnes hinta on saatu. Jos työtä on jäljellä, tehtävä siirtyy skipin jälkeen suoraan tilaan paused ja sen voi käynnistää; ilman lisätyötä se odottaa tilassa needs_attention ja päätyy tilaan completed, kun hinta on saatu. Puhelua, jota ei koskaan soitettu (moottori hylkäsi sen), ei koskaan veloiteta ja se päätyy heti arvoon 0.
  12. Yhteystieto, joka on sillä välin ostanut tai peruuttanut tilauksensa, ohitetaan ilman puhelua kutsulla resolve arvoilla action: "skip", reason: "customer_purchased" tai "unsubscribed", revision, vakaa operationId ja evidenceRef, joka osoittaa oston tai tilauksen peruutuksen perusteeseen (ei koskaan puhelinnumeroon tai sähköpostiin). Se onnistuu tilassa pending olevalle yhteystiedolle tehtävässä, joka on tilassa draft, sekä tiloissa pending/failed olevalle tehtävässä, joka on tilassa paused ilman ratkaisematonta puhelua; yritykset, hinnat ja soittokieltolista säilyvät. GET /v1/tasks/{id} näyttää sen jälkeen perusteen kentässä items[].resolution (reason, operationId, evidenceRef, resolvedAt); saman bodyn voi toistaa turvallisesti, eri reason tai eri evidenceRef samalle yhteystiedolle antaa 409 revision_conflict. Ohitus ei kirjoita numeroa soittokieltolistalle: jos yhteystiedolle ei saa enää koskaan soittaa, se lisätään kutsulla POST /v1/dnc.
  13. DELETE /v1/tasks/{id} lopuksi, jos tehtävää ei ole koskaan ajettu tai se on jo valmis ja tietue halutaan poistaa.

Lähes jokainen kirjoittava kutsu (PATCH, start, pause, DELETE) ottaa revision-arvon tehtävän viimeisimmästä lukemisesta - sama optimistinen samanaikaisuus kuin agenttiluonnoksissa. Poikkeama palauttaa revision_conflict: lue tehtävä uudelleen (GET) ja toista ajantasaisella revision-arvolla. reconcile on poikkeus - revision on siinä valinnainen.

MCP

Samat työkalut kuin RESTissä (list_tasks, get_task, create_task, update_task, pause_task, resolve_task_item, reconcile_task, start_task) - paitsi yksi ero käynnistyksessä.

start_task vahvistaa luvut

MCP:n start_task ottaa lisäksi confirmedRecipients ja confirmedBudgetHal - niiden on täsmättävä tarkasti vastaanottajien todelliseen määrään ja tehtävän budjettiin, muuten palautetaan validation todellisine arvoineen eikä MITÄÄN käynnistetä. Vieras tekoälyagentti ei siis voi yhden väärin ymmärretyn ohjeen takia vahingossa käynnistää maksullista kampanjaa keksityillä luvuilla - REST POST .../start ei sisällä tätä mekanismia, koska siinä tilin omistaja kutsuu itse omalla avaimellaan.

delete_task ja CSV-esikatselu eivät ole MCP:ssä - poistaminen on edelleen RESTissä ja portaalissa (peruuttamaton toimenpide, jossa nimi kirjoitetaan vahvistukseksi), CSV-esikatselu on vain lomakkeen yksi vaihe.

Virheet

  • task_not_found - Tilillä ei ole tehtävää tällä id-arvolla.
  • task_not_editable - Tehtävä on käynnissä tai valmis (running/completed) tai tilassa needs_attention ilman jatkamismahdollisuutta - sääntöjä ei voi nyt muuttaa. Sama koodi palautetaan myös kutsusta POST .../items/{itemId}/resolve käynnissä olevalle tehtävälle: tilassa review oleva yhteystieto ilmestyy jo silloin, kun tehtävä soittaa muille yhteystiedoille ja on vielä running - odota, kunnes se siirtyy tilaan needs_attention, tai keskeytä se (POST .../pause).
  • items_immutable - Vastaanottajalistaa ei voi korvata sen jälkeen, kun vähintään yksi soittoyritys on tehty tai yhteystieto on ohitettu arvolla reason (osto tai tilauksen peruutus).
  • budget_too_low - Budjetti ei kata edes yhtä enimmäispituista yritystä - korota budgetHal-arvoa tai laske maxDurationSecs-arvoa.
  • task_not_startable - Tehtävä ei ole tilassa draft/ready/paused tai sillä ei ole odottavaa vastaanottajaa.
  • task_needs_attention - Ennen seuraavaa käynnistystä tarvitaan POST .../reconcile - jokin (agentin versio, moottori) on muuttunut ajon aikana.
  • agent_not_ready - Agentin luonnosta ei ole julkaistu tai julkaistua versiota ei ole testattu - julkaise se (POST /v1/agents/{id}/draft/publish) ja testaa sitten julkaistu versio (POST /v1/agents/{id}/simulate) ennen käynnistystä.
  • agent_version_changed - Agentin kokoonpano muuttui KESKEN käynnissä olevan tehtävän - testaa ja käynnistä uudelleen kutsulla reconcile.
  • engine_required - Tehtävän agentti ei ole volain moottorissa (useForOutboundTasks: true) - lähtevät kampanjat vaativat nykyisin moottorin, eivät ElevenLabsia.
  • engine_contract_unavailable - Moottori ei tällä hetkellä ilmoita tukevansa lähtevien tehtävien muuttujia ja kattoja - yritä käynnistää myöhemmin uudelleen.
  • window_closed - Asetetun soittoikkunan ulkopuolella - odota, kunnes se aukeaa, tai muuta callingWindow.
  • task_not_running - Tauko onnistuu vain käynnissä olevalle tehtävälle.
  • item_not_resolvable - Yhteystieto ei ole tilassa review - ratkaisu (retry/skip) onnistuu vain tarkistusta odottavalle yhteystiedolle ja vain tehtävälle, joka ei ole käynnissä. Poikkeus on ohitus arvolla reason (customer_purchased, unsubscribed): se vaatii passiivisen pending-yhteystiedon tehtävässä, joka on tilassa draft, tai pending/failed tilassa paused, ilman ratkaisematonta puhelua.
  • task_not_deletable - Vain tehtävä, jolla ei ole kohdetta tilassa in_progress, tiloissa draft/ready/paused/completed/needs_attention voidaan poistaa.
  • revision_conflict - Tehtävää on sillä välin muutettu - lue se uudelleen (GET) ja toista ajantasaisella revision-arvolla.

Täydellinen virhekoodien taulukko jokaiselle endpointille löytyy osiosta Tehtävät REST API -referenssissä.