How to use it
- Read the newest notes and their open
needs_youitems. The brief shows the facts behind them: sales against the store’s normal, ads, the growth goal, alerts and approvals waiting. - Act on each item with the other
dtc_*tools, only after the merchant agrees when it spends money or messages customers. - Resolve it:
doneonly after the action really happened,dismissedwhen the merchant chose not to act. It then leaves the owner’s card and bell.resolved_byrecordsagent:<connection name>. - Follow up. Book a later look (“see if sales came back after pausing the ad set”), 1 to 168 hours ahead. After a change, ask for a fresh check and read the notes again about a minute later.
- Tasks. When the owner asks for something on a schedule (“every Monday, tell me how my ads did”), add a task instead of remembering it yourself. It runs on PlatformDTC’s side even when your agent is offline, and the answer lands in the owner’s notes and email.
Tasks
A task is something the owner (or you, for them) asked the heartbeat to do once or on repeat. The owner sees and manages the same list in the Tasks tab on Home.- When a task is due, the heartbeat always answers it with a note, even when everything is normal. The
note is emailed at the time picked, unless the owner turned emails off. An
hourlytask’s answer is emailed only when something is urgent (it is always on Home), and a store can have at most 3 of them. The task’slast_run_atandlast_note_idpoint at the answer. - A repeating task moves to its next time after each run. Resuming one starts from its next time (a
missed run is not made up). A one-time task whose time passed while paused needs a new
at. - Tasks can read sales and orders, ads, the monthly goal, payments, disputes, support messages and approvals waiting. They report; they don’t take actions.
- A task can also watch a web page: put the link in
check(“every morning, tell me about new reviews on https://www.trustpilot.com/review/example.com”). Each run reads that page fresh (up to 3 links across the tasks due at once) and answers with what it says: star rating, new reviews and what customers wrote, prices. If the page can’t be read, the answer says so. To read a page right now yourself, usedtc_read_web_page. - Up to 20 tasks per store, counting the owner’s and every agent’s (one-off follow-up checks count too).
The heartbeat’s own checks are separate (at most 3) and show
created_by: "heartbeat".
What you get back
- State:
store_id,settings(enabled,watch,email_mode=daily|urgent|off),last_checked_at,next_check_at,checking(a check was asked for and hasn’t finished),notes(newest first),followups(the store’s tasks: open soonest first, then paused) andtimezone(the store’s time zone,UTCwhen not set; task times are in it). - Note:
id,trigger,urgency(now|today|fyi),headline,summary,items,created_at. - Item:
id(i1,i2, …, stable within the note),kind(needs_you|opportunity|done|heads_up),title,detail,dollars_per_day(only when the facts give the numbers, elsenull),evidence(the brief facts it rests on),action(label, app-relativehref),status. - Followup (a task):
id,due_at(next run),check,created_by(owner|heartbeat|agent:<connection name>),status(open|paused),repeat,time,weekday,last_run_at,last_note_id,answer_items(the ids of the items in that note that answered this task; one note can answer several tasks) andmetrics(the measured numbers those items rest on:label,value,unit=usd|count|per_dollar|stars, without_offorstars, andcompare,compare_label,change_pct,goodwhere they apply). Both are absent until the task has an answer.
watch up to 2000 characters, check 3–300 characters, in_hours 1–168. The brief is
rate-limited to 6 calls a minute per store. A check answers checking: true at once; the note, if there
is one, lands within about a minute. When nothing matters, a check leaves no note.
MCP
The tools are on the same server as every otherdtc_* tool, https://api.platformdtc.com/mcp
(see Connect your own AI agent). A plain curl with a bearer key
works without a session:
result.content[0].text.
Agent Gateway
Agent keys (sq_agt_*) or a user token. Responses use the { "data": … } envelope; every non-GET takes an
Idempotency-Key. See Authentication.
A2A
Other agents (Google ADK, LangGraph, CrewAI or any A2A client) can find and talk to the store’s heartbeat over the Agent2Agent protocol.
Send a data part
{"skill": "<id>", …arguments}. A message with only text is store-pulse.
working: poll GetTask (v1.0) or tasks/get (v0.3).
A v1.0 SendMessage waits by default (configuration.returnImmediately: true returns at once); v0.3 waits
only with configuration.blocking: true.
- Idempotency:
messageIdis the key. The samemessageIdagain returns the first task and does nothing twice. - Cancel: a check can’t be called back once asked for, so
CancelTaskalways answers-32002(the check finishes on its own). - Not offered: streaming and push notifications.
- Errors: JSON-RPC errors, code
-32000, carrying the HTTP status the gateway uses: 401 (no or bad token), 403 (store or permission), 429 (rate limit). Another store’s task id answers-32001. - Retention: tasks untouched for 30 days are deleted.