Guides

Tasks

Give someone on the account a task from your app's server or an n8n workflow, and see what is waiting on people, on the account's Tasks board.

Tasks is the hub's board of what is waiting on the account's people: a quote to accept, an email to approve, a request with questions, and tasks people give each other. Your app's server or an n8n workflow can use it too, for example to give a member of staff a task when a customer asks for a call back.

Tasks needs the account's token (amt_pat_...), and Tasks switched on for the account. If it isn't, a call answers with an AwesomateError whose serverCode is feature_unavailable. An app's server key (ak_...) can't use Tasks.

Tasks is reaching accounts in stages, so on many accounts it isn't switched on yet.

#Give someone a task

import { createClient } from '@awesomate/sdk';

const db = createClient({ token: process.env.AWESOMATE_TOKEN! });

const t = await db.tasks.give({
  title: 'Call Sam back about the leak',
  detail: 'Asked in the portal for a call this afternoon.',
  forEmail: 'jo@brightwater.example',
  dueAt: '2026-10-06T15:00:00+11:00',
});
// t.emailed is true when Jo was sent an email about it

The task lands on that person's board straight away. When it's for someone other than the account owner, they also get an email. Leave out forEmail to give it to the owner. forEmail must be someone on the account who can act on tasks: board().people lists them.

Finish it with db.tasks.done(t.id), take it off without doing it with db.tasks.drop(t.id), or change it with db.tasks.update(t.id, { dueAt }).

#See what is waiting

const board = await db.tasks.board({ scope: 'all' });
for (const card of board.toDecide) console.log(card.from, card.question, card.dueAt);

toDecide is waiting now, later was put off with Not now, waiting is with someone else, and decided is a short record of what was decided recently. scope: 'all' shows everyone's cards, not only the owner's.

A card's main action (accepting the quote, approving the email) happens on its own page in the hub, at openPath, so that page's rules always apply. From here you can only move a card:

When board.unavailable isn't empty, part of the account couldn't be read just now, so the board may be missing cards from those places. Say so rather than treating it as everything.

#Bring a task back, and see what happened to it

A task that was done or dropped by mistake can be opened again, with the person who had it:

const board = await db.tasks.board();
const done = board.decided.find((d) => d.canBringBack);
if (done) {
  const id = done.key.replace('task:', '');
  await db.tasks.bringBack(id); // they get an email unless they brought it back themselves

  const record = await db.tasks.record(id);
  for (const step of record.steps) console.log(step.at, step.text);
  console.log(record.timings.total, record.timings.withPeople);
}

record(id) is the task's history: who gave it, who passed it on, who closed it and brought it back, and how long each person had it. The owner reads any task's record; anyone else only one they were part of. A task already open answers serverCode: 'already_open' to bringBack().

#Decisions, read only

Agents and people ask the account's people for decisions (a refund above someone's limit, a reply to approve), and these show on the Tasks page too. Your server can read them, for a report or a reminder, but never answer them: deciding is a person's tap in the hub, so every card's actions is empty here.

const decisions = await db.tasks.decisions({ scope: 'all' });
for (const d of decisions.toDecide) console.log(d.title, d.decider.label, d.expiresAt);

const first = decisions.decided[0];
if (first) {
  const history = await db.tasks.decisionRecord(first.taskId);
  for (const step of history.steps) console.log(step.at, step.text);
}

Where decisions aren't switched on yet, the call answers with serverCode: 'not_live'.

#What a card carries

type says what kind of answer a card asks for (yes_no, approve_draft, pick_one, pick_many, input, or inform), openLabel the words on its button, and ownerOnly whether only the owner may act on it. passedBy says who passed it on, and task.raisedBy names the agent when an agent asked a person to do it.

#Methods

Reading (board, record, decisions, decisionRecord) needs hosting:read; every change needs hosting:manage.