Skip to main content
POST

Authorizations

​
Authorization
string
header
required

Use a Bearer token to access these API endpoints. Example: "Bearer {your-token}"

Body

application/json

Request body varies by task type. See examples for 'make_call' and 'send_message' (WhatsApp template).

​
title
string
required

Task title

Example:

"Call customer"

​
description
string

Task description (optional)

Example:

"Follow-up call for appointment"

​
type
enum<string>

Task type. Required for AI tasks. Use 'make_call' for calls, 'send_message' for WhatsApp templates (then ALSO set task_data.message_type='whatsapp_template'). Optional for human-assigned tasks (assignee_email set) — omitted type creates a free-form 'custom' to-do. 'custom' is only accepted for human-assigned tasks.

Available options:
make_call,
make_whatsapp_call,
send_message,
send_sms,
send_email,
follow_up,
appointment,
survey,
notification,
webhook,
custom
​
contact_uuid
string<uuid>

Existing contact UUID (use this OR contact object, not both)

​
contact
object

Contact information. System will find existing contact by phone/email or create new one. Required if contact_uuid not provided.

​
campaign_uuid
string<uuid>

Campaign UUID (optional)

​
agent_uuid
string<uuid>

AI agent UUID. Required unless assignee_email is provided. The agent executes the task automatically.

Example:

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

​
assignee_email
string<email>

Workspace member email. When provided, the task is assigned to this member to perform manually: it never executes automatically, the member is notified when it is due, and they mark it completed. agent_uuid is not needed and auto_queue is not allowed.

Example:

"member@example.com"

​
scheduled_at
string<date-time>

When to execute the task (must be a future time). No offset = your timezone; with offset = that exact instant. Required for AI tasks. Optional for human-assigned tasks — without it the task has no due time (status 'pending') and no due notification is sent. Contact is likewise optional for human-assigned tasks.

Example:

"2026-08-08 10:00:00"

​
timezone
string

Task timezone (optional)

Example:

"UTC"

​
priority
integer

Task priority 1-10 (default: 5)

Required range: 1 <= x <= 10
Example:

8

​
expires_at
string<date-time>

Task expiration time (optional)

​
max_attempts
integer

Maximum retry attempts (default: 3)

Example:

3

​
retry_delay_minutes
integer

Minutes between retries (default: 60)

Example:

60

​
retry_strategy
enum<string>

Retry strategy (default: fixed)

Available options:
fixed,
exponential,
custom
​
task_data
object

Channel-specific payload. Required keys depend on the task type: * • make_call — none (uses the contact's phone). * • send_sms — sms_body (required; supports {{contact.field}} / {{custom.key}} merge tags). * • send_message (WhatsApp) — message_type='whatsapp_template' and template_uuid (required). * • send_email — email_subject and email_body (required; HTML; merge tags supported). The agent's address signature is appended automatically if one is configured; set email_signature_included=true only if your email_body already contains the signature.

​
metadata
object

Custom metadata (optional)

Example:
​
auto_queue
boolean

Automatically queue task for execution (default: false)

Example:

true

Response

Task created successfully