Tasks and automation

Create communication, Computer, retry, repeating, and one-off Tasks with verifiable outcomes.

GetVoiceBot Tasks represent concrete work. Use targetAccountId to scope the request and accountId to identify the Agent that owns the created Task. These IDs normally match.

Choose the Task type

Read GET /api/v2/tasks/limits before creating communication work.

Optional outbound number pools

Outbound call and text Tasks can use a managed pool of assigned numbers when an approved workflow
needs number rotation at scale. This is an optional capability that GetVoiceBot must enable and configure
for the organization; it is not a public self-service pool-management API. Contact GetVoiceBot to review
the use case and enable it. Afterward, verify the numbers assigned to the Agent with
GET /api/v2/phoneNumbers?targetAccountId=... and test representative Tasks before increasing
volume.

Create one communication goal

Use one retry-enabled Task for one logical outcome. goal.completionCriteria defines success; retryPolicy defines which unresolved outcomes should try again and when.

Do not create one Task per attempt. Inspect attemptHistory, result, logsRef, and per-attempt conversation references on the original Task.

externalTaskId is correlation data, not an idempotency key. Reconcile existing Tasks before retrying an uncertain create request.

Assign Computer work

Create type:"computer" with a provisioned Computer Agent accountId and complete taskContext. GetVoiceBot creates a dedicated linked chat for the work. Poll the Task to a terminal state, then inspect its chatRef or room messages for the work, tool calls, and final result.

Canceling stops active work when possible. Deleting a Computer Task also stops active work before removing the Task record.

Create recurring or one-off work

Create a repeating or cronOneOff Task with a nonblank title, taskContext, and cronSchedule. Use five-field cron expressions, fixed intervals of at least one minute, or an at schedule for one-off work.

Create recurring work paused when it must be reviewed before activation. Run a controlled test with /tasks/{taskId}/run, then inspect /tasks/{taskId}/runs. An accepted run is not proof of completion.

Inspect the returned run's chatRef for the Agent's complete work and tool calls. Reconcile the
destination effect before forcing another run after any timeout or uncertain result; do not infer
that an empty or delayed history response means no work started.

Repeating and one-off Task updates accept the documented title, task context, state, and timing fields. Delete the Task to remove its future execution. Do not send undocumented metadata or server-generated identifiers.

Design proactive polling safely

A common Computer Agent pattern is poll, qualify, deduplicate, fan out bounded work, and write back
only confirmed outcomes. Treat it as one explicit workflow:

1. Define the source query, timezone, maximum items per run, and what qualifies an item.
2. Preserve the source system's opaque IDs exactly and define a durable deduplication key.
3. Bound downstream Task creation by current capacity and reconcile existing Tasks before creating
   more work.
4. Make writeback ambiguity-safe: update the source only after the destination outcome is confirmed,
   and never blindly retry a write whose result is uncertain.
5. Create the repeating Task paused, force one controlled run, inspect its linked chat, Tasks, and
   destination effects, then activate it deliberately.

Every proactive Agent design should answer two separate questions: what triggers the work, and what
evidence proves one run completed correctly?

Use batches intentionally

Batch only eligible Tasks after reconciling active and prior work. Save the returned batchId; asynchronous batches must be polled to a terminal state and inspected for inserted, rejected, and failed rows.

After a timeout, conflict, or server error, query by stable correlation fields before resubmitting. A partial synchronous batch may already have created earlier items.

For complete retry policy rules and ready-to-use Task requests, use the GetVoiceBot API Skill.