Create a new task

Creates communication, scheduled, or Computer Agent work. Computer Tasks run only on provisioned Computer Agents and preserve their complete work in a linked conversation.

OpenAPI

````yaml post /api/v2/tasks
openapi: 3.0.0
info:
version: 2.0.0
title: GetVoiceBot API
description: GetVoiceBot API Documentation
servers:
- url: https://api.getvoicebot.com
description: GetVoiceBot Production
variables:
baseUrl:
default: api.getvoicebot.com
description: Production API Root
security: []
tags:
- name: Agents
- name: Inbound Email
description: Control which senders may create inbound email work for an Agent.
- name: Features
description: Inspect capabilities available within an account hierarchy.
- name: Conversation Logs
description: Query conversation activity and calculate account-level metrics.
- name: Computer Agents
description: Set up, configure, inspect, and manage GetVoiceBot Computer Agents.
- name: Computer Agent Sessions
description: View and reset Computer Agent sessions.
- name: Accounts
- name: Agent Templates
description: Create, manage, and apply reusable Agent configurations.
paths:
/api/v2/tasks:
post:
tags:
- Tasks
summary: Create a new task
description: >-
Creates communication, scheduled, or Computer Agent work. Computer Tasks
run only on provisioned Computer Agents and preserve their complete work
in a linked conversation.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TaskCreate'
responses:
'201':
description: Task created successfully
'400':
description: Invalid Task, goal, or retry policy
'401':
description: Unauthorized
'409':
description: An active retryable Task already exists for this agent and contact
'500':
description: Internal Server Error
security:
- apiKeyAuth: []
components:
schemas:
TaskCreate:
oneOf:
- $ref: '#/components/schemas/TaskCallCreate'
- $ref: '#/components/schemas/TaskTextCreate'
- $ref: '#/components/schemas/TaskEmailCreate'
- $ref: '#/components/schemas/TaskPingCreate'
- $ref: '#/components/schemas/TaskComputerCreate'
- $ref: '#/components/schemas/TaskRepeatingCreate'
- $ref: '#/components/schemas/TaskCronOneOffCreate'
discriminator:
propertyName: type
mapping:
call:
$ref: '#/components/schemas/TaskCallCreate'
text:
$ref: '#/components/schemas/TaskTextCreate'
email:
$ref: '#/components/schemas/TaskEmailCreate'
ping:
$ref: '#/components/schemas/TaskPingCreate'
computer:
$ref: '#/components/schemas/TaskComputerCreate'
repeating:
$ref: '#/components/schemas/TaskRepeatingCreate'
cronOneOff:
$ref: '#/components/schemas/TaskCronOneOffCreate'
TaskCallCreate:
type: object
required:
- type
- target
properties:
type:
type: string
enum:
- call
target:
type: string
description: >-
Phone number, email address, or supported GetVoiceBot username for this
Task type.
example: '+15551234567'
accountId:
type: integer
description: Agent account that performs the Task.
example: 1234
title:
type: string
context:
type: string
description: Contact context supplied to the Agent.
taskContext:
type: string
description: Instructions for the Agent performing this Task.
example: Confirm whether the customer wants a renewal quote.
scheduledFor:
type: integer
description: Unix timestamp for the first attempt or Computer Agent run.
example: 1712350000
externalTaskId:
type: string
description: Reusable caller-defined correlation ID; not an idempotency key.
contactListName:
type: string
goal:
$ref: '#/components/schemas/TaskGoal'
retryPolicy:
$ref: '#/components/schemas/TaskRetryPolicy'
meta:
type: object
description: >-
Metadata retained for filtering and reporting; it is not added to
the Agent prompt.
greeting:
type: string
description: >-
Call greeting. Prefix with prompt: to generate it from an
instruction.
waitToGreet:
type: boolean
TaskTextCreate:
type: object
required:
- type
- target
properties:
type:
type: string
enum:
- text
target:
type: string
description: >-
Phone number, email address, or supported GetVoiceBot username for this
Task type.
example: '+15551234567'
accountId:
type: integer
description: Agent account that performs the Task.
example: 1234
title:
type: string
context:
type: string
description: Contact context supplied to the Agent.
taskContext:
type: string
description: Instructions for the Agent performing this Task.
example: Confirm whether the customer wants a renewal quote.
scheduledFor:
type: integer
description: Unix timestamp for the first attempt or Computer Agent run.
example: 1712350000
externalTaskId:
type: string
description: Reusable caller-defined correlation ID; not an idempotency key.
contactListName:
type: string
goal:
$ref: '#/components/schemas/TaskGoal'
retryPolicy:
$ref: '#/components/schemas/TaskRetryPolicy'
meta:
type: object
description: >-
Metadata retained for filtering and reporting; it is not added to
the Agent prompt.
message:
type: string
description: Initial text message.
TaskEmailCreate:
type: object
required:
- type
- target
properties:
type:
type: string
enum:
- email
target:
type: string
description: >-
Phone number, email address, or supported GetVoiceBot username for this
Task type.
example: '+15551234567'
accountId:
type: integer
description: Agent account that performs the Task.
example: 1234
title:
type: string
context:
type: string
description: Contact context supplied to the Agent.
taskContext:
type: string
description: Instructions for the Agent performing this Task.
example: Confirm whether the customer wants a renewal quote.
scheduledFor:
type: integer
description: Unix timestamp for the first attempt or Computer Agent run.
example: 1712350000
externalTaskId:
type: string
description: Reusable caller-defined correlation ID; not an idempotency key.
contactListName:
type: string
goal:
$ref: '#/components/schemas/TaskGoal'
retryPolicy:
$ref: '#/components/schemas/TaskRetryPolicy'
meta:
type: object
description: >-
Metadata retained for filtering and reporting; it is not added to
the Agent prompt.
message:
type: string
description: Initial email body.
TaskPingCreate:
type: object
required:
- type
properties:
type:
type: string
enum:
- ping
target:
type: string
description: >-
Phone number, email address, or supported GetVoiceBot username for this
Task type.
example: '+15551234567'
accountId:
type: integer
description: Agent account that performs the Task.
example: 1234
title:
type: string
context:
type: string
description: Contact context supplied to the Agent.
taskContext:
type: string
description: Instructions for the Agent performing this Task.
example: Confirm whether the customer wants a renewal quote.
scheduledFor:
type: integer
description: Unix timestamp for the first attempt or Computer Agent run.
example: 1712350000
externalTaskId:
type: string
description: Reusable caller-defined correlation ID; not an idempotency key.
contactListName:
type: string
goal:
$ref: '#/components/schemas/TaskGoal'
retryPolicy:
$ref: '#/components/schemas/TaskRetryPolicy'
meta:
type: object
description: >-
Metadata retained for filtering and reporting; it is not added to
the Agent prompt.
TaskComputerCreate:
type: object
additionalProperties: false
required:
- type
- accountId
- taskContext
properties:
type:
type: string
enum:
- computer
accountId:
type: integer
description: Agent account that performs the Task.
example: 1234
title:
type: string
taskContext:
type: string
description: Instructions for the Agent performing this Task.
example: Confirm whether the customer wants a renewal quote.
scheduledFor:
type: integer
description: Unix timestamp for the first attempt or Computer Agent run.
example: 1712350000
externalTaskId:
type: string
description: Reusable caller-defined correlation ID; not an idempotency key.
meta:
type: object
description: Caller metadata. System-managed provider fields are reserved.
TaskRepeatingCreate:
type: object
additionalProperties: false
required:
- type
- accountId
- title
- taskContext
- cronSchedule
properties:
type:
type: string
enum:
- repeating
accountId:
type: integer
description: Agent account that performs the Task.
example: 1234
title:
type: string
taskContext:
type: string
description: Instructions for the Agent performing this Task.
example: Confirm whether the customer wants a renewal quote.
state:
type: string
enum:
- active
- paused
default: active
cronSchedule:
$ref: '#/components/schemas/TaskCronSchedule'
TaskCronOneOffCreate:
type: object
additionalProperties: false
required:
- type
- accountId
- title
- taskContext
- cronSchedule
properties:
type:
type: string
enum:
- cronOneOff
accountId:
type: integer
description: Agent account that performs the Task.
example: 1234
title:
type: string
taskContext:
type: string
description: Instructions for the Agent performing this Task.
example: Confirm whether the customer wants a renewal quote.
state:
type: string
enum:
- active
- paused
default: active
cronSchedule:
$ref: '#/components/schemas/TaskCronSchedule'
TaskGoal:
type: object
nullable: true
description: >-
Task-specific outcome definition. Omit or pass null to inherit the
organization default.
required:
- completionCriteria
properties:
completionCriteria:
type: string
description: Criteria evaluated after a connected conversation.
description:
type: string
description: Optional goal label.
TaskRetryPolicy:
type: object
nullable: true
description: >-
Task-specific cadence. Omit or pass null to inherit the organization
default. Use delaysSeconds or steps, never both.
required:
- retryOn
properties:
delaysSeconds:
type: array
minItems: 1
maxItems: 10
description: Delays after each attempt, each from 60 seconds through 30 days.
items:
type: integer
minimum: 60
maximum: 2592000
steps:
type: array
minItems: 1
maxItems: 10
description: >-
Strictly increasing offsets from the first attempt for
channel-specific retries.
items:
type: object
required:
- offsetSeconds
- channel
properties:
offsetSeconds:
type: integer
minimum: 60
maximum: 7776000
channel:
type: string
enum:
- call
- text
- email
target:
type: string
description: Required when changing between phone and email channels.
responseTimeoutSeconds:
type: integer
minimum: 60
maximum: 604800
content:
type: object
description: Channel-specific content override, up to 32 KB.
retryOn:
type: array
minItems: 1
items:
type: string
enum:
- busy
- delivery_failed
- goal_incomplete
- no_answer
- no_response
- no_speech
- rejected
- transient_failure
- voicemail
responseTimeoutSeconds:
type: integer
minimum: 60
maximum: 604800
TaskCronSchedule:
oneOf:
- type: object
additionalProperties: false
required:
- kind
- at
properties:
kind:
type: string
enum:
- at
at:
type: string
format: date-time
- type: object
additionalProperties: false
required:
- kind
- everyMs
properties:
kind:
type: string
enum:
- every
everyMs:
type: integer
minimum: 60000
- type: object
additionalProperties: false
required:
- kind
- expr
properties:
kind:
type: string
enum:
- cron
expr:
type: string
example: 0 * * * *
tz:
type: string
example: America/Chicago
securitySchemes:
apiKeyAuth:
type: apiKey
in: query
name: token
description: GetVoiceBot API Token

````

Open the app All docs