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.
draftstart ei ole koskaan ajettu. Muokattavissa (PATCH), voidaan poistaa.readydraft- 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.runningPATCH 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}.pausedPOST .../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.completedneeds_attentionagent_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
phoneon pakollinen - isoilla ja pienillä kirjaimilla, nimen ympäröivillä välilyönneillä ja sen perässä olevalla kaksoispisteellä ei ole väliä, ja myöstelefon,teltaimobilhyvä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äphoneotsikon 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ä:
- Tehtävän agentin on oltava JULKAISTU ja julkaistun version TESTATTU (
POST /v1/agents/{id}/draft/publish, sen jälkeenPOST /v1/agents/{id}/simulate) - muuten myöhempistartpalauttaaagent_not_ready. - Valinnaisesti
POST /v1/tasks/csv-preview- tarkistaa vastaanottajien CSV:n ennen tehtävän luomista. POST /v1/tasks- luo tehtävän tilaandraft. Mitään ei soiteta.GET /v1/tasks/{id}- lueissues(dry-run-validointi) ja tarkista, että tehtävä on valmis käynnistettäväksi.- Tarvittaessa
PATCH /v1/tasks/{id}- säädä sääntöjä, AINA viimeisimmästä lukemisesta saadullarevision-arvolla. POST /v1/tasks/{id}/start- käynnistää soiton. Jokainen vastattu puhelu veloitetaan heti.POST /v1/tasks/{id}/pausemilloin tahansa ajon aikana,POST /v1/tasks/{id}/startjatkaa taas.- 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}/reconciletäsmäyttää tilan todellisiin puheluihin; tällainen tehtävä, jolla on työtä jäljellä, päätyy tilaanpaused, vaikka jotkin yhteystiedot odottaisivat tilassareview, ja sen voi käynnistää uudelleen kutsullastart. Käynnissä olevaa tehtävää tai muuta syytä (variables_limit, epäonnistunut laskun tai kalenterin tarkistus, epävarma soitto, jossa puhelua ei löytynyt)reconcileei muuta; tarkistettavat yhteystiedot käsitellään kutsullaresolve. - Tarkistukseen päätynyt yhteystieto (
items[].status: "review") käsitellään kutsullaPOST /v1/tasks/{id}/items/{itemId}/resolvearvollaaction: "retry"tai"skip". Tavallisen syyn kohdallaretrypalauttaa yhteystiedon odottavien joukkoon ja tehtävän tilaanpaused;skipsulkee sen ja tehtävä siirtyy tilaanpaused, jos työtä on jäljellä, tai tilaancompleted, jos kaikki yhteystiedot on käsitelty tai ohitettu. Tilassapausedoleva tehtävä jatketaan sitten kutsullaPOST /v1/tasks/{id}/start. - Kun yhteystiedolla on
reviewReason: "dial:destination_auto_blocked", numero on estetty automaattisesti 30 päiväksi toistuvien vastaamattomien puhelujen jälkeen eikä pelkkäretrypoista estoa - yhteystieto päätyisi heti uudelleen tilaanreview. Poista ensin esto (POST /v1/dnc/{e164}/unblock, MCP:ssäunblock_destination, numero haetaan kentästäitems[].phone) ja tee sen jälkeenresolvearvollaaction: "retry". Kun kyseessä ondial: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ä vainskip. - Kun yhteystiedolla on
reviewReason: "billing_unknown", alkuperäinen puhelu on voinut jo toteutua, vain hintaa ei vielä tunneta. Kutsu ensinreconcileja tarkista siihen liittyvä puhelu.retrymerkitsee, että yhteystieto yritetään uudelleen, mutta ei salli uutta puhelua, ennen kuin alkuperäinen hinta on saatu; sen jälkeen tehtävä siirtyy tilaanpausedja vaatii uudenstart-kutsun.skipestää 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ä siirtyyskipin jälkeen suoraan tilaanpausedja sen voi käynnistää; ilman lisätyötä se odottaa tilassaneeds_attentionja päätyy tilaancompleted, kun hinta on saatu. Puhelua, jota ei koskaan soitettu (moottori hylkäsi sen), ei koskaan veloiteta ja se päätyy heti arvoon 0. - Yhteystieto, joka on sillä välin ostanut tai peruuttanut tilauksensa, ohitetaan ilman puhelua kutsulla
resolvearvoillaaction: "skip",reason: "customer_purchased"tai"unsubscribed",revision, vakaaoperationIdjaevidenceRef, joka osoittaa oston tai tilauksen peruutuksen perusteeseen (ei koskaan puhelinnumeroon tai sähköpostiin). Se onnistuu tilassapendingolevalle yhteystiedolle tehtävässä, joka on tilassadraft, sekä tiloissapending/failedolevalle tehtävässä, joka on tilassapausedilman 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, erireasontai erievidenceRefsamalle yhteystiedolle antaa409 revision_conflict. Ohitus ei kirjoita numeroa soittokieltolistalle: jos yhteystiedolle ei saa enää koskaan soittaa, se lisätään kutsullaPOST /v1/dnc. 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 tilassaneeds_attentionilman jatkamismahdollisuutta - sääntöjä ei voi nyt muuttaa. Sama koodi palautetaan myös kutsustaPOST .../items/{itemId}/resolvekäynnissä olevalle tehtävälle: tilassareviewoleva yhteystieto ilmestyy jo silloin, kun tehtävä soittaa muille yhteystiedoille ja on vielärunning- odota, kunnes se siirtyy tilaanneeds_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 arvollareason(osto tai tilauksen peruutus).budget_too_low- Budjetti ei kata edes yhtä enimmäispituista yritystä - korotabudgetHal-arvoa tai laskemaxDurationSecs-arvoa.task_not_startable- Tehtävä ei ole tilassadraft/ready/pausedtai sillä ei ole odottavaa vastaanottajaa.task_needs_attention- Ennen seuraavaa käynnistystä tarvitaanPOST .../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 kutsullareconcile.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 muutacallingWindow.task_not_running- Tauko onnistuu vain käynnissä olevalle tehtävälle.item_not_resolvable- Yhteystieto ei ole tilassareview- ratkaisu (retry/skip) onnistuu vain tarkistusta odottavalle yhteystiedolle ja vain tehtävälle, joka ei ole käynnissä. Poikkeus on ohitus arvollareason(customer_purchased,unsubscribed): se vaatii passiivisenpending-yhteystiedon tehtävässä, joka on tilassadraft, taipending/failedtilassapaused, ilman ratkaisematonta puhelua.task_not_deletable- Vain tehtävä, jolla ei ole kohdetta tilassain_progress, tiloissadraft/ready/paused/completed/needs_attentionvoidaan poistaa.revision_conflict- Tehtävää on sillä välin muutettu - lue se uudelleen (GET) ja toista ajantasaisellarevision-arvolla.
Täydellinen virhekoodien taulukko jokaiselle endpointille löytyy osiosta Tehtävät REST API -referenssissä.
Liittyvää
MCP-palvelin
Yhdistä Claude Code, Codex CLI, Codex desktop, Cursor ja muut tekoälyeditorit.
REST API
Täydellinen kuvaus jokaisesta päätepisteestä: numerot, puhelut, tekstiviestit, tekstiviestien matkapuhelinnumerot, agentit ja niiden luonnokset, työkalut, tallenteet, webhookit, soittokieltolista, välitys, tili, tehtävät, saldo, asiakirjat, kalenterit ja integraatiot.
Puheagentti
Järjestelmäkehote, työkalut, siirto ihmiselle, tallenteet ja jäsennelty puhelutieto.