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"]
}'const response = await fetch("https://api.reten.ai/api/activities", {
method: "POST",
headers: {
"Authorization": "Bearer <token>",
"x-tenant-id": "<tenant-id>",
"Content-Type": "application/json",
},
body: JSON.stringify({
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"],
}),
});
const activity = await response.json();import requests
response = requests.post(
"https://api.reten.ai/api/activities",
headers={
"Authorization": "Bearer <token>",
"x-tenant-id": "<tenant-id>",
},
json={
"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"],
},
)
activity = response.json()Response 201 Created
{
"id": "ee0e8400-e29b-41d4-a716-446655440000",
"type": "MESSAGE",
"reason": {
"code": "monthly_promotion",
"label": "Promocion Mensual"
},
"channel": "WHATSAPP",
"status": "READY",
"userStatus": null,
"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 |