Guias

Tarefas

Uma tarefa liga a uma lista de destinatários com um único agente, segundo regras que define à partida - orçamento, janela de chamadas, número de tentativas. Nada é marcado enquanto não iniciar a tarefa por si.

O que é uma tarefa

Uma tarefa (task_...) é uma campanha de chamadas efetuadas: um agente no motor da volai, uma lista de destinatários com número de telefone e variáveis opcionais para o prompt de sistema, e regras (orçamento, janela de chamadas, máximo de tentativas e duração da chamada). Existem três tipos consoante a finalidade - invoice (lembrete de pagamento), appointment (confirmação de marcação) e custom (tudo o resto) - nos dois primeiros, quando source é integration, cada destinatário traz ainda uma referência à fatura ou ao evento (externalRefs) que o agente menciona durante a chamada.

Estados e transições

Na prática, uma tarefa passa sempre de `draft` diretamente para `running` (`start`); a eliminação (`DELETE`) só funciona nos estados assinalados.

A condição exata de eliminação: o estado é um dos assinalados E nenhum item tem status: "in_progress" (uma chamada que começou a ser marcada e ainda não terminou) - caso contrário, task_not_deletable.

Importação de destinatários (CSV)

POST /v1/tasks/csv-preview analisa um CSV e devolve-o com os erros de cada linha - NADA é guardado, é apenas uma pré-visualização antes de criar ou atualizar uma tarefa. O formulário de nova tarefa no portal chama a mesma função.

• O separador é detetado automaticamente (vírgula ou ponto e vírgula) a partir da primeira linha.
• Tem de existir uma coluna phone - não importam as maiúsculas, os espaços à volta nem dois pontos finais, e são aceites também telefon, tel ou mobile; a pré-visualização devolve sempre a coluna como phone. Funciona igualmente uma simples lista de números sem cabeçalho (um por linha, uma só coluna). Caso contrário, todo o CSV falha com um único erro phone no cabeçalho.
• Todas as outras colunas são variáveis para o prompt de sistema do agente ({{column_name}}) - no máximo 20 colunas, nome até 64 carateres, valor até 512 carateres.
• O número de telefone é normalizado da mesma forma que em todo o resto da API (normalizePhone) - um número inválido ou vazio é um erro apenas NESSA linha, o resto do CSV continua a ser processado.
• Uma célula que pareça uma fórmula de folha de cálculo (começa por =, +, - ou @) é rejeitada - proteção contra injeção de CSV quando o ficheiro é aberto no Excel.
• No máximo 1000 linhas por CSV (o mesmo limite do número de destinatários de uma tarefa) e 1 MB de texto bruto; a tarefa completa, incluindo as suas variáveis, tem de caber em 2 MB, caso contrário a criação devolve validation.

A resposta contém headers, delimiter, rows (cada linha com os seus próprios erros), validRows (apenas as linhas corretas, exatamente no formato que recipients em POST /v1/tasks espera) e uma matriz resumo errors. Envie validRows diretamente como recipients ao criar ou atualizar a tarefa.

Orçamento e janela de chamadas

Orçamento

budgetHal é o LIMITE de despesa de toda a tarefa, em cêntimos de coroa (heller). Na criação tem de cobrir pelo menos uma tentativa com a duração máxima (caso contrário, budget_too_low); no início, antes de CADA marcação é reservado o preço máximo possível da tentativa (reservedBudgetHal), e apenas uma chamada atendida o converte em spentHal. A reserva é o preço de uma chamada com a duração exata de maxDurationSecs (o troço da chamada e o troço do agente, cada um arredondado por excesso ao heller, tal como na faturação), e uma chamada terminada pelo limite de duração é faturada, no máximo, por maxDurationSecs, mesmo que termine uma fração de segundo depois. Uma tarefa nunca gasta mais do que o budgetHal que lhe atribuiu.

Janela de chamadas

callingWindow é {timezone: "Europe/Prague", start, end, days} - atualmente o único fuso horário suportado é o de Praga, start/end no formato HH:MM (o fim inclui todo esse minuto: uma janela 09:00-18:00 ainda permite uma chamada às 18:00:59, e uma janela que termine às 23:59 cobre o dia inteiro) e days são números de 0 a 6 (0 = domingo). Sem janela, aplicam-se os dias úteis das 9:00 às 18:00. Fora da janela, start devolve window_closed - aguarde pela reabertura ou altere a janela com PATCH. O campo opcional expiresAt é o prazo da campanha como timestamp Unix positivo, inteiro seguro, em milissegundos. É verificado no início e antes de cada marcação, incluindo a primeira. Nesse prazo ou depois dele, nenhuma nova chamada é iniciada e nenhuma tentativa é consumida; uma chamada em curso termina normalmente. O horizonte de repetições de lorela_enterprise (retryMaxAgeDays, 5 por omissão) conta, por seu lado, N × 24 horas a partir da primeira tentativa contabilizada, e não a partir da criação da tarefa.

Tentativas e duração da chamada

maxAttempts é de 1 a 3 sem política (por omissão 1), ou de 1 a 4 com retryPolicy: "lorela_enterprise" (por omissão na criação 4). É o número máximo de marcações automáticas a um contacto, incluindo a primeira chamada (1 = sem repetições). Contam todas as tentativas em que a chamada poderia ter acontecido, incluindo uma chamada sem resposta, uma chamada recusada pela pessoa contactada e uma tentativa com resultado incerto. Uma tentativa que a volai rejeitou antes de marcar não conta (por exemplo um número bloqueado, o seu próprio número ou um número inválido, a lista de não contactar, um número com outra chamada em curso, limites de chamadas); essa tentativa tem items[].attempts[].countsAsAttempt: false. Também não conta uma chamada cuja rota nunca chegou a tempo ao operador, de modo que o telefone do destinatário nunca tocou (a tentativa tem errorCode: "relay_not_routed", a chamada endReason: "rejected"): o contacto recebe uma nova tentativa não antes de um minuto depois (com lorela_enterprise, segundo o seu calendário), e após a terceira tentativa assim consecutiva passa para revisão com reviewReason: "call:relay_not_routed". Também não conta uma chamada que o nosso motor de voz nunca comunicou e que encerrámos, após duas horas sem comunicação, como não marcada e gratuita (a tentativa tem errorCode: "no_provider_report"): o contacto volta à espera e recebe uma nova tentativa não antes de um minuto depois (com lorela_enterprise, segundo o seu calendário). Três tentativas não contabilizadas consecutivas, também misturadas com tentativas relay_not_routed, enviam o contacto para revisão com o reviewReason da última, ou seja, call:no_provider_report; os contactos que uma chamada destas já tinha enviado antes para revisão (call:failed, ou call:unknown com a política) não são reabertos automaticamente. Sem política, o limite aplica-se apenas às marcações automáticas: um contacto a que aplique resolve com action: "retry" depois de esgotadas as suas tentativas recebe mais uma marcação. maxDurationSecs (30-300) limita a duração de UMA chamada, após a qual esta termina automaticamente - a duração por omissão é de 120 segundos. Ative a política opcional lorela_enterprise através da API ou do MCP antes da primeira tentativa; as tarefas existentes não mudam automaticamente. A segunda tentativa ocorre, no mínimo, 8 minutos depois de começar a primeira tentativa real, entre as 08:00 e as 22:00 de Europe/Prague. A terceira usa a janela seguinte, diferente, das 08:00-09:00 ou das 17:00-19:00; a quarta usa a janela oposta no dia de calendário seguinte. A callingWindow da tarefa e os seus dias da semana continuam a aplicar-se; nenhuma repetição da política começa depois do horizonte de repetições: o retryMaxAgeDays opcional, um número inteiro de dias de 1 a 30 (5 se omitido), válido apenas com a política. O horizonte termina N × 24 horas depois da primeira tentativa contabilizada de cada contacto (dias fixos de 24 horas, pelo que, numa mudança de hora, a hora local de fim se desloca uma hora). Pode ser alterado com PATCH também depois de as tentativas terem começado (não numa tarefa running ou completed, que não pode ser editada): aumentá-lo numa tarefa em pausa devolve a failed (à espera da sua próxima tentativa) os contactos que tinham sido ignorados apenas por causa do horizonte (reviewReason: "retry_age_expired"), com um novo nextAttemptAt, quando ainda lhes resta uma tentativa e o próximo horário do calendário cai dentro do novo horizonte e antes de expiresAt; diminuí-lo não reabre nada. Só um PATCH que aumente o horizonte reabre contactos, por isso envie retryMaxAgeDays juntamente com um expiresAt prolongado num único pedido. Apenas no_answer, missed, busy, correio de voz concluído e uma chamada atendida em que a pessoa contactada não disse nada se qualificam (todos sem contacto humano). O contacto humano, a recusa e a falha do motor param as repetições automáticas; os resultados ambíguos requerem revisão. A última tentativa permitida (maxAttempts) que termine com um resultado repetível deste tipo (sem resposta, ocupado, correio de voz, ou uma chamada atendida em que a pessoa contactada não disse nada) encerra o contacto como skipped com reviewReason: "retry_policy_exhausted" (tal como retry_age_expired quando o horizonte se esgota): não há nada a rever nem a repetir. Um resultado ambíguo da última tentativa permanece em review com o mesmo motivo. Sem política nada muda: a última tentativa sem resposta continua a ser review. Uma chamada de retorno humana verificada depois de esgotadas as tentativas converte o contacto em completed. A DNC, o orçamento e os limites de chamadas continuam a aplicar-se: o bloqueio automático após 3 falhas em 24 horas pode impedir a quarta tentativa. Um PATCH sem maxAttempts preserva o limite existente. Com a política, um resolve manual com action: "retry" devolve validation; só são permitidas tentativas automáticas agendadas. Uma reserva expirada comprovadamente sem marcação pode ser restabelecida antes da primeira tentativa real: sem trabalhador ativo, intenção de envio, chamada do fornecedor, reserva, cobrança ou chamada de retorno, e apenas com rejeições comprovadas anteriores à marcação no seu histórico. A recuperação preserva o histórico e os limites e devolve o contacto a pendente numa tarefa em pausa; não marca. Os lembretes de cupões não podem ser reabertos. Uma repetição manual não pode contornar quatro tentativas, o horizonte de repetições nem a paragem após contacto humano.

Débito global

Fluxo para um agente

Uma execução típica, por esta ordem:

1. O agente da tarefa tem de estar PUBLICADO e a versão publicada TESTADA (POST /v1/agents/{id}/draft/publish e depois POST /v1/agents/{id}/simulate) - caso contrário, um start posterior devolve agent_not_ready.
2. Opcionalmente POST /v1/tasks/csv-preview - verifica o CSV dos destinatários antes de criar a tarefa.
3. POST /v1/tasks - cria a tarefa no estado draft. Nada é marcado.
4. GET /v1/tasks/{id} - leia issues (validação em simulação) e confirme que a tarefa está pronta para começar.
5. Se necessário, PATCH /v1/tasks/{id} - ajuste as regras, SEMPRE com a revision da última leitura.
6. POST /v1/tasks/{id}/start - inicia a marcação. Cada chamada atendida é faturada de imediato.
7. POST /v1/tasks/{id}/pause em qualquer momento durante a execução; POST /v1/tasks/{id}/start volta a retomá-la.
8. Após uma interrupção (uma pausa a meio de uma chamada, uma reserva expirada, uma chamada com preço ainda desconhecido, ou uma marcação incerta cuja chamada foi encontrada), POST /v1/tasks/{id}/reconcile reconcilia o estado com as chamadas reais; uma tarefa assim, com trabalho por fazer, fica em paused mesmo que alguns contactos aguardem em review, de modo que o start a possa retomar. Uma tarefa em execução e outros motivos (variables_limit, uma verificação de fatura ou de calendário falhada, uma marcação cuja chamada não é encontrada) não são alterados por reconcile; decida os contactos em revisão com resolve.
9. Decida um contacto que acabou em revisão (items[].status: "review") com POST /v1/tasks/{id}/items/{itemId}/resolve e action: "retry" ou "skip". Para um motivo habitual ao nível do item, retry devolve o contacto a pendente e a tarefa a paused; skip encerra o contacto e a tarefa passa a paused se ainda houver trabalho, ou a completed se todos os contactos estiverem concluídos ou ignorados. Retome uma tarefa paused com POST /v1/tasks/{id}/start.
10. Quando um contacto tem reviewReason: "dial:destination_auto_blocked", o número fica bloqueado automaticamente durante 30 dias após repetidas chamadas sem resposta, e só retry não o desbloqueia - o contacto voltaria logo para review. Levante primeiro o bloqueio (POST /v1/dnc/{e164}/unblock, no MCP unblock_destination, retire o número de items[].phone) e só depois faça resolve com action: "retry". Para dial:on_dnc, retire primeiro o número da lista de não contactar (DELETE /v1/dnc/{e164}); caso contrário, ignore o contacto. Para o número da própria conta, um número de outra conta da volai, um número inválido, um número fora da Chéquia e da Eslováquia e uma linha de tarifa especial (dial:cannot_call_own_number, dial:cannot_call_volai_number, dial:invalid_number, dial:unsupported_country, dial:blocked_destination), outra tentativa não ajuda: use apenas skip.
11. Quando um contacto tem reviewReason: "billing_unknown", a chamada original pode já ter acontecido, mas o seu preço ainda é desconhecido. Chame primeiro reconcile e inspecione a chamada associada. retry regista que o contacto deve ser tentado de novo, mas nenhuma nova chamada é permitida até o preço original ficar acertado; a tarefa passa então a paused e precisa de um novo start. skip impede outra chamada; a chamada original continua associada e a sua reserva continua a contar para o orçamento até o preço ficar acertado. Quando ainda há trabalho, a tarefa passa diretamente a paused após skip e pode ser iniciada; sem trabalho restante, aguarda em needs_attention e passa a completed assim que o preço ficar acertado. Uma chamada que nunca foi marcada (o motor recusou-a) nunca é faturada e fica acertada de imediato a 0.
12. Para ignorar um contacto sem chamada porque entretanto comprou ou cancelou a subscrição, envie resolve com action: "skip", reason: "customer_purchased" ou "unsubscribed", revision, um operationId estável e um evidenceRef que aponte para o registo da compra ou do cancelamento (nunca para um número de telefone ou e-mail). Funciona num contacto pending de uma tarefa draft e em pending/failed numa tarefa paused sem chamada por acertar, e preserva tentativas, custos e a lista de não contactar. GET /v1/tasks/{id} mostra então o comprovativo em items[].resolution (reason, operationId, evidenceRef, resolvedAt); repetir o mesmo corpo é seguro, ao passo que um reason ou evidenceRef diferente para o mesmo contacto devolve 409 revision_conflict. O skip não adiciona o número à lista de não contactar: faça-o com POST /v1/dnc se o contacto nunca mais deva ser chamado.
13. DELETE /v1/tasks/{id} no fim, se a tarefa nunca correu ou já terminou e pretende eliminar o registo.

Quase todas as chamadas de escrita (PATCH, start, pause, DELETE) usam a revision da última leitura da tarefa - a mesma concorrência otimista que nos rascunhos de agentes. Uma divergência devolve revision_conflict: leia de novo a tarefa (GET) e repita com a revision atual. reconcile é a exceção - a sua revision é opcional.

MCP

As mesmas ferramentas que no REST (list_tasks, get_task, create_task, update_task, pause_task, resolve_task_item, reconcile_task, start_task) - exceto por uma diferença no início.

start_task confirma os números

O start_task do MCP aceita adicionalmente confirmedRecipients e confirmedBudgetHal - têm de corresponder exatamente ao número real de destinatários e ao orçamento da tarefa, caso contrário devolve validation com os valores reais indicados e não inicia NADA. Assim, um agente de IA de terceiros que atue com base numa única instrução vagamente entendida não consegue lançar acidentalmente uma campanha paga com números inventados - o POST .../start do REST não tem tal mecanismo, porque aí é o titular da conta que o chama diretamente com a sua própria chave.

delete_task e a pré-visualização de CSV não existem no MCP - a eliminação permanece no REST e no portal (uma ação irreversível que exige escrever o nome), e a pré-visualização de CSV é apenas um passo de formulário.

Erros

• task_not_found - Não existe nenhuma tarefa com este id na conta.
• task_not_editable - A tarefa está em execução ou concluída, ou está em needs_attention sem forma de recuperar - as suas regras não podem ser alteradas neste momento. POST .../items/{itemId}/resolve devolve o mesmo código para uma tarefa em execução: um contacto em review aparece enquanto a tarefa ainda está running e liga aos outros - aguarde até passar a needs_attention ou ponha-a em pausa (POST .../pause).
• items_immutable - A lista de destinatários não pode ser substituída depois de ter ocorrido pelo menos uma tentativa de marcação ou de um contacto ter sido ignorado com um reason (compra ou cancelamento da subscrição).
• budget_too_low - O orçamento não cobre sequer uma tentativa com a duração máxima da chamada - aumente budgetHal ou reduza maxDurationSecs.
• task_not_startable - A tarefa não está no estado draft/ready/paused ou já não tem nenhum destinatário por contactar.
• task_needs_attention - É necessário um POST .../reconcile antes do início seguinte - algo (a versão do agente, o motor) mudou durante a execução.
• agent_not_ready - O rascunho do agente não está publicado ou a versão publicada não foi testada - publique-o (POST /v1/agents/{id}/draft/publish) e depois simule a versão publicada (POST /v1/agents/{id}/simulate) antes de iniciar.
• agent_version_changed - A configuração do agente mudou ENQUANTO a tarefa estava em execução - teste-a e reinicie através de reconcile.
• engine_required - O agente da tarefa não está no motor da volai (useForOutboundTasks: true) - atualmente as tarefas de chamadas efetuadas exigem o motor, e não a ElevenLabs.
• engine_contract_unavailable - Neste momento o motor não anuncia suporte para variáveis e limites de tarefas de chamadas efetuadas - tente iniciar novamente mais tarde.
• window_closed - Fora da janela de chamadas configurada - aguarde pela reabertura ou altere callingWindow.
• task_not_running - A pausa só funciona numa tarefa em execução.
• item_not_resolvable - O contacto não está em review - uma decisão (retry/skip) só é possível para um contacto que aguarda revisão, e apenas enquanto a tarefa não estiver em execução. O skip com um reason (customer_purchased, unsubscribed) é a exceção: exige um contacto pending inativo numa tarefa draft, ou pending/failed numa tarefa paused, sem chamada por acertar.
• task_not_deletable - Só pode ser eliminada uma tarefa sem itens em curso, nos estados draft/ready/paused/completed/needs_attention.
• revision_conflict - A tarefa mudou entretanto - leia-a de novo (GET) e repita com a revision atual.

A tabela completa de erros de cada endpoint encontra-se na secção Tasks da referência da API REST.