Activities
Create Activity
Create a new activity assigned to a commerce.
POST /api/activities
Create a new activity (TASK or MESSAGE) with commerce assignment, target resolution, and attribute resolution.
Auth: Required — CREATE_ACTIVITY permission
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 time for execution |
user_status | string | No | User status context |
score | integer | No | Priority score |
assignment_reason | string | No | Reason for the assignment |
target_criteria | array | No | Override target resolution criteria (objects with type, config, priority) |
attribute_keys | string[] | No | Attribute key names to resolve via policies |
attributes | array | No | Caller-provided attribute values (objects with key, value, fallback) |
Example
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",
"commerceAssignment": {
"commerceId": "880e8400-e29b-41d4-a716-446655440000"
}
}Error Responses
| Status | Description |
|---|---|
400 | Validation error |
404 | Commerce not found |
409 | Idempotency key already exists |