Managing Activities

This page covers creating and canceling activities. These operations are typically used by internal systems or admin users.

Creating Activities

Generic Activity (TASK or MESSAGE)

Use POST /api/activities to create any activity type.

Request Body

Field	Type	Required	Description
`type`	string	Yes	`TASK` or `MESSAGE`
`reason`	string	Yes	Reason for creating the activity
`channel`	string	Yes	`SALESMAN`, `CALLCENTER`, `WHATSAPP`, `EMAIL`, `SMS`, `PUSH`
`commerce_id`	UUID	Yes	Target commerce ID
`idempotency_key`	string	Yes	Unique key per tenant (prevents duplicates)
`scheduled_at`	ISO 8601	Yes	When the activity should be executed
`suggested_execution_time`	ISO 8601	No	Suggested execution time
`user_status`	string	No	Caller-defined user status
`score`	integer	No	Priority score
`assignment_reason`	string	No	Reason for commerce assignment
`target_criteria`	array	No	Target user resolution criteria (overrides config)
`attribute_keys`	string[]	No	Attribute key names to resolve via policies
`attributes`	array	No	Caller-provided attribute values

curl -X POST https://api.reten.ai/api/activities \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "MESSAGE",
    "reason": "Monthly promotion",
    "channel": "WHATSAPP",
    "commerce_id": "880e8400-e29b-41d4-a716-446655440000",
    "idempotency_key": "msg-2025-01-15-001",
    "scheduled_at": "2025-01-16T09:00:00.000Z",
    "attribute_keys": ["commerce_info"]
  }'

import axios from 'axios';

const response = await axios.post(
  'https://api.reten.ai/api/activities',
  {
    type: 'MESSAGE',
    reason: 'Monthly promotion',
    channel: 'WHATSAPP',
    commerce_id: '880e8400-e29b-41d4-a716-446655440000',
    idempotency_key: 'msg-2025-01-15-001',
    scheduled_at: '2025-01-16T09:00:00.000Z',
    attribute_keys: ['commerce_info'],
  },
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

Response `201 Created`

{
  "id": "ee0e8400-e29b-41d4-a716-446655440000",
  "type": "MESSAGE",
  "channel": "WHATSAPP",
  "status": "READY",
  "idempotencyKey": "msg-2025-01-15-001",
  "scheduledAt": "2025-01-16T09:00:00.000Z"
}

Task Activity (with Route & Operator)

Use POST /api/activities/tasks when creating a TASK that requires route and operator assignment.

Additional Fields (beyond base activity)

Field	Type	Required	Description
`assigned_route_id`	UUID	Yes	Assigned route
`assigned_operator_id`	UUID	Yes	Assigned operator

curl -X POST https://api.reten.ai/api/activities/tasks \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Monthly visit",
    "channel": "SALESMAN",
    "commerce_id": "880e8400-e29b-41d4-a716-446655440000",
    "idempotency_key": "task-2025-01-15-001",
    "assigned_route_id": "dd0e8400-e29b-41d4-a716-446655440000",
    "assigned_operator_id": "cc0e8400-e29b-41d4-a716-446655440000",
    "scheduled_at": "2025-01-16T09:00:00.000Z"
  }'

const response = await axios.post(
  'https://api.reten.ai/api/activities/tasks',
  {
    reason: 'Monthly visit',
    channel: 'SALESMAN',
    commerce_id: '880e8400-e29b-41d4-a716-446655440000',
    idempotency_key: 'task-2025-01-15-001',
    assigned_route_id: 'dd0e8400-e29b-41d4-a716-446655440000',
    assigned_operator_id: 'cc0e8400-e29b-41d4-a716-446655440000',
    scheduled_at: '2025-01-16T09:00:00.000Z',
  },
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

Canceling Activities

Use PATCH /api/activities/:id/cancel to cancel an activity. Only activities in READY status can be canceled.

Requirements

Activity must be in READY status
Requires CANCEL_ACTIVITY permission (SUPER_ADMIN, ADMIN)

curl -X PATCH https://api.reten.ai/api/activities/ee0e8400-e29b-41d4-a716-446655440000/cancel \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>"

const response = await axios.patch(
  `https://api.reten.ai/api/activities/${activityId}/cancel`,
  null,
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);
// response.data → { id: "...", status: "CANCELED" }

Retrying Resolution

When an activity ends in UNRESOLVED status (target users or attributes failed to resolve), use PATCH /api/activities/:id/retry-resolution to retry.

Requirements

Activity must be in UNRESOLVED status
Requires CREATE_ACTIVITY permission

curl -X PATCH https://api.reten.ai/api/activities/ee0e8400-e29b-41d4-a716-446655440000/retry-resolution \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>"

const response = await axios.patch(
  `https://api.reten.ai/api/activities/${activityId}/retry-resolution`,
  null,
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);
// On success: activity transitions to READY
// On failure: activity remains UNRESOLVED

Activity Creation Flow

When an activity is created, the following steps execute within a single database transaction:

Validate the commerce exists and the idempotency key is unique
Create the activity record with READY status
Create the commerce assignment (1:1)
Resolve target users — Determine which commerce user should handle the activity
Resolve attributes — Attach key-value data (commerce info, promotions, etc.)
Create task details — For TASK type: link route and operator
Record a CREATED status event
Check resolution — If target users or attributes are unresolved, transition to UNRESOLVED and record a RESOLUTION_FAILED event

Required Permissions

Operation	Permission	Roles
Create activities	`CREATE_ACTIVITY`	SUPER_ADMIN, ADMIN, FDE
Cancel activities	`CANCEL_ACTIVITY`	SUPER_ADMIN, ADMIN
Retry resolution	`CREATE_ACTIVITY`	SUPER_ADMIN, ADMIN, FDE