Receiving Activities (Dispatch)
How Reten dispatches activities to the configured provider endpoint in real time.
The Push (Dispatch) mode allows Reten to send activities directly to the configured provider endpoint in real time, without requiring your system to periodically poll the API.
Dispatch requires the tenant to have at least one provider configured on the platform. Available providers are registered by the Reten team. If you need to onboard a new provider, contact Reten.
Concept
When a tenant administrator configures dispatch for a specific provider and channel, Reten automatically sends new activities to the provider's registered endpoint. The flow is:
- An activity is created in Reten (manually from the Reten app or by the Reten Growth Engine)
- Reten evaluates the active dispatch configurations for the tenant and channel
- Reten builds the payload with the activity data
- Reten sends the payload to the provider's endpoint via HTTP POST
- The provider processes the activity and can submit results back to Reten via
POST /api/integration/activity-results/tasks
Configuration
Reten Environments
| Environment | Admin Panel | API Base URL |
|---|---|---|
| Development | app-development.reten.ai | https://api-development.reten.ai |
| Staging | app-staging.reten.ai | https://api-staging.reten.ai |
| Production | app.reten.ai | https://api.reten.ai |
Use the admin panel URL to manage API keys and dispatch configurations. Replace BASE_URL in code examples with the API base URL for your environment.
Dispatch is configured from the tenant's administration panel:
- Navigate to Activities → Dispatch Configuration
- Click Create configuration
- Select the provider and channel
- Enter the provider's endpoint URL
- Configure the provider's authentication credentials
- Activate the configuration
Dispatch configuration is the responsibility of the tenant administrator. You will need the provider's endpoint URL and the authentication credentials it requires.
Activity payload
When Reten sends an activity to the provider's endpoint, the HTTP POST request body contains an object with the following structure.
This is the default payload structure. If the provider requires a different format, the tenant administrator can configure a payload mapping to transform the fields before sending — the provider does not need to adapt its interface to this format.
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"activityOrigin": "ACTIVITY",
"projectId": "3f6c2b1a-8d4e-4f7a-9b2c-5e1d0a7f6c34",
"type": "TASK",
"status": "READY",
"score": 85,
"channel": "SALESMAN",
"scheduledAt": "2026-04-15T09:00:00.000Z",
"occurredAt": null,
"createdAt": "2026-04-15T08:30:00.000Z",
"lifecycleStatus": "READY",
"lifecycleStatusLabel": "Lista",
"lifecycleStatusDetail": null,
"canForceRetryDispatch": false,
"commerceExternalId": "COM-001",
"commerceName": "Farmacia Central",
"reason": {
"code": "CHURN_RISK",
"label": "Riesgo de fuga"
},
"userStatus": null,
"commerceAssignment": {
"commerceExternalId": "COM-001",
"assignmentReason": "Asignación por ruta",
"commerce": {
"externalId": "COM-001",
"name": "Farmacia Central"
}
},
"activityDetails": {
"type": "TASK",
"assignedRouteCode": "RUTA-NORTE-01",
"assignedOperatorExternalId": "OP-042",
"assignedRoute": {
"code": "RUTA-NORTE-01",
"name": "Ruta Norte"
},
"assignedOperator": {
"externalId": "OP-042",
"name": "Carlos Pérez",
"type": "SALESMAN"
}
},
"activityResult": null
}At dispatch time, status is READY on the first attempt and on a forced retry, and RETRYING on automatic retries (see Retry behavior). The example shows a first attempt.
The payload structure is identical to the response from the List Activities endpoint — see that reference for a detailed description of each field.
Key payload fields
| Field | Recommended use |
|---|---|
id | Store as a reference to submit results via activity_id |
commerceExternalId | Identify the commerce in the provider's system |
commerceName | Display to the operator |
activityDetails.assignedOperatorExternalId | Assign to the corresponding operator in the provider's system |
activityDetails.assignedRoute | Route context for planning |
scheduledAt | Scheduled date for the activity |
score | Priority score — useful for routing or ranking in the provider's system |
reason | Context on why the activity was created |
Retry behavior
If the provider's endpoint does not respond with a 2xx code, Reten automatically retries the delivery:
| Dispatch status | Description | Action |
|---|---|---|
| Activity is fully resolved and ready to act on. If the client has a provider configured to dispatch activities, the system's next action attempts the dispatch; otherwise the activity stays READY and an operator can act on it from the internal platform. | Activity ready for dispatch | Pending delivery |
| Activity was delivered to the external provider. This applies only when the client has a dispatch provider configured for the activity; clients that operate exclusively from Reten's internal platform never pass through this state. Having a dispatch provider does not prevent the result from being recorded internally: the outcome can arrive either from the external provider or from the internal platform. | Sent successfully (2xx response) | Complete |
| At least one dispatch attempt has failed; the system will retry automatically. Each retry keeps the activity in this state. It moves to DISPATCHED when an attempt succeeds, or to FAILED when the available retries run out. | Temporary failure — retrying | Reten retries automatically |
| Activity reached a failed terminal state through one of two paths: (a) dispatch attempts ran out without success; or (b) an end-of-day closing process detected an activity left retrying and marked it FAILED with result NOT_EXECUTED. Although terminal, a FAILED activity can be recovered manually via a dedicated endpoint that retries it once; the attempt can end in DISPATCHED, RETRYING, or FAILED again. | All retries exhausted | Requires manual intervention (force-retry-dispatch) |
The provider's endpoint must respond with an HTTP 2xx code (e.g., 200 OK) to confirm receipt. Any other code is considered a failure and triggers the retry process.
Payload mapping
The tenant administrator can configure a payload mapping that transforms the object structure before sending it to the provider's endpoint. This allows adapting field names and structure to what the provider's system expects, without requiring additional changes.
The mapping is configured during the creation or editing of the dispatch configuration from the administration panel.
Next step
Once the provider receives activities via dispatch, your system can submit results back to Reten via POST /api/integration/activity-results/tasks. Use the id field from the received payload as activity_id when submitting the result.
Submit these results with a tenant key. Dispatch sends the activities of every project of the tenant, and a project key only reaches its own project: with it, the result of an activity of another project responds 404 — Actividad no encontrada. See Key scope.