> ## Documentation Index
> Fetch the complete documentation index at: https://docs.periskope.app/llms.txt
> Use this file to discover all available pages before exploring further.

# The Task Object

> A task in the workspace. Tasks are either standalone to-dos (type: todo) or linked to a chat, message or ticket via association. Tasks belong to the workspace as a whole, not to a specific phone.

<ResponseExample>
  ```json The Task Object theme={null}
  {
    "task_id": "task-aaaaaaaaaaaa",
    "title": "Call back the customer about the renewal quote",
    "type": "message",
    "status": "open",
    "priority": 2,
    "assignee": "user@example.com",
    "created_by": "api",
    "last_updated_by": "api",
    "created_at": "2026-01-15T09:30:00.000Z",
    "last_updated_at": "2026-01-15T09:30:00.000Z",
    "due_date": "2026-01-20T17:00:00.000Z",
    "remind_at": "2026-01-20T09:00:00.000Z",
    "notes": "Customer prefers a call after 3pm IST",
    "chat_id": "120363000000000000@g.us",
    "association": {
      "type": "message",
      "chat_id": "120363000000000000@g.us",
      "message_id": "false_120363000000000000@g.us_AAAAAAAAAAAAAAAAAAAA",
      "ticket_id": "ACM-042"
    },
    "completed_metadata": {
      "completed_at": "2026-01-21T10:15:00.000Z",
      "completed_by": "user@example.com"
    }
  }
  ```
</ResponseExample>

**Attributes**

<ParamField path="task_id" type="string">
  Unique id of the task (task-xxxxxxxxxxxxxxxx). Use this value as the task\_id path parameter when fetching or updating the task.
</ParamField>

<ParamField path="title" type="string">
  Title of the task, up to 500 characters
</ParamField>

<ParamField path="type" type="string">
  Kind of task: 'todo' for a standalone task, or 'chat', 'message' or 'ticket' for a task linked to that object. Immutable after creation. One of: `todo`, `chat`, `message`, `ticket`.
</ParamField>

<ParamField path="status" type="string">
  Lifecycle status of the task: 'open', 'inprogress' or 'closed' One of: `open`, `inprogress`, `closed`.
</ParamField>

<ParamField path="priority" type="integer">
  Priority of the task: 1 (low), 2 (medium) or 3 (high)
</ParamField>

<ParamField path="assignee" type="string">
  Email of the workspace member the task is assigned to. null when the task is unassigned.
</ParamField>

<ParamField path="created_by" type="string">
  Who created the task: a member's email, or "api" when created via the API without a created\_by
</ParamField>

<ParamField path="last_updated_by" type="string">
  Who last changed the task: a member's email, or "api" for API changes without a last\_updated\_by
</ParamField>

<ParamField path="created_at" type="string">
  When the task was created, as an ISO 8601 timestamp
</ParamField>

<ParamField path="last_updated_at" type="string">
  When the task was last updated, as an ISO 8601 timestamp
</ParamField>

<ParamField path="due_date" type="string">
  When the task is due, as an ISO 8601 UTC timestamp. null when no due date is set.
</ParamField>

<ParamField path="remind_at" type="string">
  When a reminder for the task fires, as an ISO 8601 UTC timestamp. null when no reminder is set.
</ParamField>

<ParamField path="notes" type="string">
  Free-form notes on the task. null when none were set.
</ParamField>

<ParamField path="chat_id" type="string">
  Id of the chat the task is linked to (directly, or through its message or ticket). null for todo tasks.
</ParamField>

<ParamField path="association" type="object">
  The chat, message or ticket the task is linked to. null for todo tasks.

  <Expandable title="properties">
    <ParamField path="type" type="string">
      Kind of object the task is linked to: 'chat', 'message' or 'ticket'. Mirrors the task's type. One of: `chat`, `message`, `ticket`.
    </ParamField>

    <ParamField path="chat_id" type="string">
      Id of the chat the linked object belongs to — \<countrycode>\<number>@c.us for 1-1 chats, \<group-id>@g.us for group chats. Present for every association kind; the chat itself for chat tasks, the chat of the message or ticket otherwise. null when the chat could not be resolved.
    </ParamField>

    <ParamField path="message_id" type="string">
      message\_id of the linked message. Present only when type is 'message'.
    </ParamField>

    <ParamField path="ticket_id" type="string">
      ticket\_id of the linked ticket. Present only when type is 'ticket'.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="completed_metadata" type="object">
  Completion details, recorded when the task moves to status 'closed' and cleared when it is reopened. null while the task is open or inprogress.

  <Expandable title="properties">
    <ParamField path="completed_at" type="string">
      When the task was closed, as an ISO 8601 timestamp
    </ParamField>

    <ParamField path="completed_by" type="string">
      Who closed the task: a member's email, or "api" for API changes without an actor
    </ParamField>
  </Expandable>
</ParamField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.