Create Task

TypeScript

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

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

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

main();

curl -X POST 'https://api.periskope.app/v1/tasks/create' \
  -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": "The chat, message or ticket referenced in association does not exist in the workspace",
  "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.createTask({
    title: 'Call back the customer about the renewal quote',
  });
  console.log(response);
}

main();

curl -X POST 'https://api.periskope.app/v1/tasks/create' \
  -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": "The chat, message or ticket referenced in association does not exist in the workspace",
  "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.

Body

application/json

title

string

required

Title of the task, up to 500 characters

Required string length: 1 - 500

Example:

"Call back the customer about the renewal quote"

type

enum<string> | null

Kind of task: 'todo' for a standalone task (the default when omitted or null), or 'chat', 'message' or 'ticket' for a task linked to that object. Determines which id association must carry. Immutable after creation.

Available options:

todo,

chat,

message,

ticket,

null

Example:

"message"

association

object | null

Links the task to its parent object. Required when type is 'chat', 'message' or 'ticket' and must then contain exactly one key — the one matching the type (association.chat_id, association.message_id or association.ticket_id). Must be omitted for todo tasks. Immutable after creation.

Show child attributes

Example:

{
  "message_id": "false_120363000000000000@g.us_AAAAAAAAAAAAAAAAAAAA"
}

status

enum<string> | null

Initial status of the task: 'open', 'inprogress' or 'closed'. Defaults to 'open' when omitted or null. Creating a task as 'closed' records completed_metadata with the completion time and actor.

Available options:

open,

inprogress,

closed,

null

Example:

"open"

priority

integer | null

Priority of the task: 1 (low), 2 (medium) or 3 (high). Accepts a number or a numeric string. Defaults to 1 when omitted or null.

Required range: 1 <= x <= 3

Example:

2

assignee

string | null

Email of the workspace member to assign the task to. Must match an existing member of the workspace, otherwise the request is rejected. Defaults to unassigned.

Example:

"user@example.com"

due_date

string | null

When the task is due, as an ISO 8601 timestamp (other common date formats are accepted and normalized to UTC ISO 8601). Defaults to no due date.

Example:

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

notes

string | null

Free-form notes to store on the task

Example:

"Customer prefers a call after 3pm IST"

remind_at

string | null

When to fire a reminder for the task, as an ISO 8601 timestamp (other common date formats are accepted and normalized to UTC ISO 8601). Defaults to no reminder.

Example:

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

created_by

string | null

Email of the workspace member to record as the creator (also recorded as last_updated_by). Must match an existing member of the workspace. Defaults to "api".

Example:

"user@example.com"

Response

The created 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

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

Body

Response