Activities Guide

Activities are the core domain object in Reten. An activity is a unit of work or communication assigned to a commerce (business/store).

Activity Types

Type	Description	Requires
TASK	Actionable items executed by field operators	Route + operator assignment via task details
MESSAGE	Communications sent to commerces via a channel	Channel configuration only

Channels

Activities are dispatched through channels representing different communication methods:

Channel	Code	Description
Salesman	`SALESMAN`	In-person visit by a field salesperson
Call Center	`CALLCENTER`	Phone call from a call center agent
WhatsApp	`WHATSAPP`	WhatsApp message
Email	`EMAIL`	Email communication
SMS	`SMS`	SMS text message
Push	`PUSH`	Push notification

Activity Lifecycle

Activities follow a strict status machine:

                           ┌──► DISPATCHED ──────► COMPLETED
                           │        │
READY ─┬──────────────────►┤        └──────────► FAILED
       │                   │
       ├──► UNRESOLVED ────┘  (retry-resolution succeeds → READY)
       │
       ├──────────────────────────────────────► CANCELED
       │
       └──────────────────────────────────────► FAILED

Status Values

Status	Description
`READY`	Created and waiting to be dispatched
`UNRESOLVED`	Created but target user or attribute resolution failed — requires retry or manual intervention
`DISPATCHED`	Sent to an external provider/channel
`COMPLETED`	Successfully finished
`CANCELED`	Manually canceled by an admin
`FAILED`	Failed during dispatch or execution

Valid Transitions

From	To	Trigger
`READY`	`UNRESOLVED`	Target user or attribute resolution fails during creation
`READY`	`DISPATCHED`	Successful dispatch to provider
`READY`	`CANCELED`	Manual cancellation
`READY`	`FAILED`	Max dispatch attempts (3) exceeded
`UNRESOLVED`	`READY`	Successful retry via `PATCH /api/activities/:id/retry-resolution`
`DISPATCHED`	`COMPLETED`	Result received with `COMPLETED` or `TRANSFERRED` status
`DISPATCHED`	`FAILED`	Result received with `NOT_EXECUTED` status

Key Properties

Each activity has:

Commerce assignment — 1:1 link to a target commerce
Channel — Communication method
Status — Current lifecycle state
Idempotency key — Unique per tenant, prevents duplicate creation
Scheduling — scheduled_at and optional suggested_execution_time timestamps
Dispatch tracking — dispatch_config_id, provider_activity_id, dispatch_attempt_count
Target users — Resolved contact persons within the commerce
Attributes — Key-value data resolved via configurable policies

What's Next

Reading Activities — List and filter activities
Submitting Results — Submit task execution outcomes
Activity Injection — How Reten dispatches activities
Managing Activities — Create, cancel, and retry activities