Update Task

TypeScript

import { PeriskopeApi } from '@periskope/periskope-client';

const client = new PeriskopeApi({
  authToken: 'YOUR_API_KEY',
});

async function main() {
  const response = await client.tasks.updateTask({
    task_id: 'task-aaaaaaaaaaaa',
    title: 'Call back the customer about the renewal quote',
  });
  console.log(response);
}

main();

curl -X PATCH 'https://api.periskope.app/v1/tasks/task-aaaaaaaaaaaa' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Call back the customer about the renewal quote"
  }'

{
  "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"
  }
}

{
  "code": "UNAUTHORIZED_ERROR",
  "message": "Invalid bearer auth token",
  "status": 401
}

{
  "code": "NOT_FOUND_ERROR",
  "message": "No task matches task_id",
  "status": 404
}

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "status": 422,
  "fields": {
    "body.chat_id": {
      "message": "chat_id is required"
    }
  }
}

{
  "code": "RATE_LIMIT_ERROR",
  "message": "You can only make 100 requests per second",
  "status": 429
}

{
  "code": "UNKNOWN_ERROR",
  "message": "Internal server error",
  "status": 500
}

TypeScript

import { PeriskopeApi } from '@periskope/periskope-client';

const client = new PeriskopeApi({
  authToken: 'YOUR_API_KEY',
});

async function main() {
  const response = await client.tasks.updateTask({
    task_id: 'task-aaaaaaaaaaaa',
    title: 'Call back the customer about the renewal quote',
  });
  console.log(response);
}

main();

curl -X PATCH 'https://api.periskope.app/v1/tasks/task-aaaaaaaaaaaa' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Call back the customer about the renewal quote"
  }'

{
  "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"
  }
}

{
  "code": "UNAUTHORIZED_ERROR",
  "message": "Invalid bearer auth token",
  "status": 401
}

{
  "code": "NOT_FOUND_ERROR",
  "message": "No task matches task_id",
  "status": 404
}

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "status": 422,
  "fields": {
    "body.chat_id": {
      "message": "chat_id is required"
    }
  }
}

{
  "code": "RATE_LIMIT_ERROR",
  "message": "You can only make 100 requests per second",
  "status": 429
}

{
  "code": "UNKNOWN_ERROR",
  "message": "Internal server error",
  "status": 500
}

Authorizations

Authorization

string

header

required

Your Periskope API token, sent as Authorization: Bearer <token>. Generate one from the Periskope dashboard under Settings → API & Webhooks. API access requires an active Pro or Enterprise plan.

Path Parameters

task_id

string

required

Unique id of the task (task-xxxxxxxxxxxxxxxx), returned when the task was created

Minimum string length: 1

Example:

"task-aaaaaaaaaaaa"

Body

application/json

title

string

New title of the task, up to 500 characters. Cannot be null or empty.

Required string length: 1 - 500

Example:

"Call back the customer about the renewal quote"

status

enum<string> | null

New status of the task: 'open', 'inprogress' or 'closed'. Pass null or an empty string to reset it to 'open'. Moving the task to 'closed' records completed_metadata with the completion time and actor; moving it out of 'closed' clears it.

Available options:

open,

inprogress,

closed,

null

Example:

"closed"

priority

integer | null

New priority of the task: 1 (low), 2 (medium) or 3 (high). Accepts a number or a numeric string. Pass null or an empty string to reset the priority to 1.

Required range: 1 <= x <= 3

Example:

3

assignee

string | null

Email of the workspace member to reassign the task to. Must match an existing member of the workspace. Pass null or an empty string to unassign the task.

Example:

"user@example.com"

due_date

string | null

New due date, as an ISO 8601 timestamp (other common date formats are accepted and normalized to UTC ISO 8601). Pass null or an empty string to clear the due date.

Example:

"2026-01-20T17:00:00Z"

notes

string | null

New notes for the task. Pass null or an empty string to clear them.

Example:

"Customer prefers a call after 3pm IST"

remind_at

string | null

New reminder time, as an ISO 8601 timestamp (other common date formats are accepted and normalized to UTC ISO 8601). Pass null or an empty string to clear the reminder.

Example:

"2026-01-20T09:00:00Z"

last_updated_by

string | null

Email of the workspace member to record as the author of this update. Must match an existing member of the workspace. Defaults to "api".

Example:

"user@example.com"

Response

The updated task

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.

task_id

string

Unique id of the task (task-xxxxxxxxxxxxxxxx). Use this value as the task_id path parameter when fetching or updating the task.

Example:

"task-aaaaaaaaaaaa"

title

string

Title of the task, up to 500 characters

Example:

"Call back the customer about the renewal quote"

type

enum<string>

Kind of task: 'todo' for a standalone task, or 'chat', 'message' or 'ticket' for a task linked to that object. Immutable after creation.

Available options:

todo,

chat,

message,

ticket

Example:

"message"

status

enum<string>

Lifecycle status of the task: 'open', 'inprogress' or 'closed'

Available options:

open,

inprogress,

closed

Example:

"open"

priority

integer

Priority of the task: 1 (low), 2 (medium) or 3 (high)

Example:

2

assignee

string

Email of the workspace member the task is assigned to. null when the task is unassigned.

Example:

"user@example.com"

created_by

string

Who created the task: a member's email, or "api" when created via the API without a created_by

Example:

"api"

last_updated_by

string

Who last changed the task: a member's email, or "api" for API changes without a last_updated_by

Example:

"api"

created_at

string

When the task was created, as an ISO 8601 timestamp

Example:

"2026-01-15T09:30:00.000Z"

last_updated_at

string

When the task was last updated, as an ISO 8601 timestamp

Example:

"2026-01-15T09:30:00.000Z"

due_date

string

When the task is due, as an ISO 8601 UTC timestamp. null when no due date is set.

Example:

"2026-01-20T17:00:00.000Z"

remind_at

string

When a reminder for the task fires, as an ISO 8601 UTC timestamp. null when no reminder is set.

Example:

"2026-01-20T09:00:00.000Z"

notes

string

Free-form notes on the task. null when none were set.

Example:

"Customer prefers a call after 3pm IST"

chat_id

string

Id of the chat the task is linked to (directly, or through its message or ticket). null for todo tasks.

Example:

"120363000000000000@g.us"

association

object

The chat, message or ticket the task is linked to. null for todo tasks.

Show child attributes

completed_metadata

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.

Show child attributes

API

Chat APIs

Group Settings APIs

Message APIs

Scheduled Message APIs

Call APIs

Media APIs

Contact APIs

Ticket APIs

Custom Property APIs

Task APIs

Queue APIs

Phone APIs

Notes APIs

Reaction APIs

Knowledge Base APIs

Member APIs

AI APIs

Webhook APIs

Webhooks

Authorizations

Path Parameters

Body

Response