Task

Introduction

Task is the Agent's proactive messaging capability: the Agent initiates the conversation with the user instead of waiting for the user to speak first.

This differs from a regular conversation. A regular conversation is "the user asks → the Agent answers", whereas a task is "the platform sends a message to the Agent on the user's behalf according to the conditions you set → the Agent generates a reply → the reply is pushed to the user". The "trigger message" you fill in for a task is essentially a message sent to the Agent on behalf of the user. The Agent generates a reply just as it would for a real user message, and what the end user sees is the Agent's reply, not the trigger message itself.

Typical use cases:

Prerequisites

• Tasks are only sent to users who have already had a conversation with the Agent. For each user, the platform finds their "most recently active" conversation on the target channel and injects the message into that conversation. Users with no conversation history will not receive task messages (recorded as NO_CONVERSATION in the execution details).
• If the target channel is a third-party integration (such as WhatsApp, Telegram, LINE, etc.), make sure the corresponding integration is correctly configured and enabled under "Integrations". A disabled integration or invalid credentials will cause delivery to fail (CHANNEL_CONFIG_INVALID / CHANNEL_AUTH_FAILED).
• Task execution calls the Agent's LLM to generate a reply, and consumes Credits as usual.

Entry Point

Go to DevSpace → Agent → select an Agent → "Tasks" in the left menu.

The task list supports searching by task name and filtering by Status, Trigger, and Target. List fields:

Creating a Task

Click New task in the upper right corner and complete the configuration in the drawer on the right.

1. Basic Information

Note: Selecting All users will prompt a confirmation dialog, because it means broadcasting to all users on every channel of this Agent. Please make sure the target conversation scope is set appropriately to avoid sending messages by mistake.

Supported Target Channels

Tip: Some channels do not yet support server-side proactive push due to platform protocol restrictions (such as Discord, DingTalk, and SoBot). They are grayed out in the channel dropdown with the reason shown. For owned channels (Web / Widget, etc.), the reply is written directly into the conversation, and the user will see it the next time they open the chat window. For IM channels and help desk platforms, the reply is proactively pushed to the user through the corresponding platform's API.

2. Trigger

The trigger determines "when to send". There are three types:

Active - Scheduled

Initiated by the platform according to the schedule you set. Suitable for regular broadcasts and one-time notifications.

Times are calculated in the time zone selected for the task. A scheduled task is in the WAITING state after creation and moves to RUNNING when the first execution time is reached. A Once task automatically changes to COMPLETED after it finishes executing.

Active - Event

Triggered by your business system calling the platform via a Webhook. Suitable for integration with business events such as orders, payments, and tickets.

When creating the task, select an authentication method and fill in the credentials. The platform automatically generates a unique Webhook URL (viewable in the task details after creation):

Webhook Call Example

The Webhook URL has the form {platform domain}/bot/proactive-task/webhook/{webhookPath}. Always use the full address shown in the task details.

                      
                      POST {Webhook URL}
Content-Type: application/json
Authorization: Basic base64(username:password)

{
  "idempotency_key": "order-20260903-0001",
  "target": {
    "channel": "TELEGRAM",
    "user_id": "customer_123"
  },
  "variables": {
    "order_no": "SO-20260903-0001",
    "eta": "Sept 5"
  }
}

                    

Note: A successful Webhook request only means "received and queued for sending". Check the execution history for the actual delivery result. Authentication failure, a stopped task, or a target channel outside the task's configured target channels will all return a permission error. Each Webhook URL is rate-limited to 120 requests per minute.

Passive - User Triggered

The platform scans all target users once every minute, and users who match the rules trigger a send. Suitable for scenarios such as re-engaging inactive users and nurturing high-value users.

Rule Configuration

Click Add rule to add rules. Multiple rules can be combined with AND (all must match) or OR (any one matches).

Note: User attributes come from "Variable Management → User Attributes" and are evaluated per user (the attribute's default value is used if the user has not set one), which makes them suitable for filtering by user profile. Custom attributes come from "Variable Management → Custom Variables" and are Agent-level values that are the same for all users, which makes them suitable as "master switch" conditions. All rule fields are evaluated based on the user's most recently active conversation on the target channel.

Message Frequency

Passive triggered tasks must have frequency control set: within the configured window (N hours / N days), the same user will be triggered by this task at most once, so that users who continuously match the rules are not repeatedly disturbed.

Tip: User's last chat time is a time in the "past", so use operators of the "N units ago" kind. Operators of the "N units from now" kind only apply to future time fields (such as a subscription expiration time); applied to the last chat time, they will never match.

3. Message

Fill in the message content to be sent to the Agent "on behalf of the user". The Agent generates a reply based on this message together with its own prompt, knowledge base, and so on, and the reply is then pushed to the user.

You can use {{variable}} to reference the following variables:

Examples

• Scheduled broadcast: Please summarize today's top industry news for me in a brief and friendly tone.
• Re-engaging inactive users: I haven't been here for a few days. Please greet me and tell me what new features have been released recently.
• Event notification: My order {{event.variables.order_no}} has shipped and is expected to arrive on {{event.variables.eta}}. Please tell me the shipping information and remind me to watch for the delivery.

Tip: The trigger message is a question written for the Agent from the "user's perspective", not copy that is shown directly to the user. If you want the Agent to relay it as-is, state that explicitly in the message, for example "Please tell the user verbatim: …".

After confirming everything is correct, click Create.

Note: Each Agent can have at most 10 tasks in the WAITING / RUNNING state at the same time. Beyond that, you need to stop existing tasks or wait for them to complete first.

Task Status

Viewing Tasks and Execution History

Click View in the list to open the task details, which contain two tabs:

• Configuration: a read-only view of the task configuration. For event triggered tasks, you can view the Webhook URL and authentication information here.
• Execution History: a record of each execution, including execution time, number of targets, success / failure counts, and success rate.

Click an execution to view its execution details: success / failure statistics for each channel, along with the individual send records. Failure reasons:

Stopping and Deleting

• Stop: Tasks in the WAITING / RUNNING / ERROR state can be stopped at any time. Once stopped, the task changes to TERMINATED and cannot be resumed.
• Delete: Only tasks in the COMPLETED / TERMINATED state can be deleted. Deleting a task also removes its execution history and details.

FAQ

Q: Why did the task execute successfully, but the user saw something different from the trigger message I filled in?
The trigger message is "a question sent to the Agent on behalf of the user", and what the user sees is the reply the Agent generated in response to it. If you need precise control over the wording, explicitly instruct the Agent in the trigger message to output it verbatim.

Q: Will new users receive task messages?
No. Tasks are only sent to users who already have conversation history, and the conversation creation time must fall within the "target conversation scope".

Q: Why wasn't my scheduled task sent exactly on the hour?
The scheduler scans once every minute, and large-volume sends are pushed in batches according to the project-level rate limit, so the actual arrival time may be slightly delayed.

Q: The Webhook returns a permission error (Permission deny)?
Check the following in order: whether the Webhook URL is correct, whether the authentication credentials match, whether the task has been stopped, and whether target.channel in the request is one of the target channels configured for the task.