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",
  "type": "TASK",
  "status": "PENDING",
  "channel": "SALESMAN",
  "scheduledAt": "2026-04-15T09:00:00.000Z",
  "occurredAt": null,
  "createdAt": "2026-04-10T14:30:00.000Z",
  "lifecycleStatus": "SCHEDULED",
  "lifecycleStatusLabel": "Programada",
  "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
}

Dispatch for MESSAGE type activities will be available soon.

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
`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
`READY`	Activity ready for dispatch	Pending delivery
`DISPATCHED`	Sent successfully (`2xx` response)	Complete
`RETRYING`	Temporary failure — retrying	Reten retries automatically
`FAILED`	All retries exhausted	Requires manual intervention

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.