Reporting Task Outcomes Back to the Conversation

An agent can start a background task from a conversation, for example when a user asks for a longer piece of work in Slack or WhatsApp. With task notifications, the task reports back to the conversation that created it when it finishes. The agent then runs one more turn in that conversation and tells the user what happened, in the same channel the request came from.

Notifications are opt-in per task. Tasks created without them behave exactly as before.

Turning Notifications On

Notifications are enabled with the optional notify field of the Create Task abilities in the ChatBotKit task catalogue:

• task/create
• task/create[by-bot-id]
• task/create[contact]
• task/create[contact][by-bot-id]

When the agent calls one of these abilities with notify set to true, the platform stores the current conversation on the task as the place to report to. The ability result includes notify: true when this worked, and notify: false when there was no conversation to report to (for example when the ability ran outside a conversation) or the chain limit described below was reached.

The field is described to the model as something to use for background work the user is waiting on, so the agent decides when to set it. You can steer this in the bot's backstory, for example by asking it to always request a notification for long-running work.

The /api/v1/task/create endpoint has no notify field. Notifications are set up from inside a conversation, through the abilities.

When a Notification Is Sent

A notification is sent each time a run of the task ends with one of these statuses:

• completed - the run finished. The outcome carries the run summary, or the task description when no summary was produced.
• failed - the run failed, including runs stopped by the platform's iteration or time limits. The outcome carries the error message or the limit that was hit.
• aborted - the run was stopped before it could finish, for example because it was canceled, the task has no bot, or the account is over its limits. The outcome carries the reason, such as Task aborted: Task execution canceled.

For recurring tasks this means one notification per run. A task that is deleted before its run finishes does not send a notification.

Outcome summaries are limited to 4,000 characters.

What Happens in the Conversation

The task outcome is added to the originating conversation as an activity message (_getTaskNotification) with the task ID, run ID, task name, status and summary. The agent then runs one turn on that conversation with an instruction to tell the user what happened, using the conversation so far for context, and not to start the same task again unless the user asked for it.

The reply is delivered through the channel's normal send path, so it is formatted the same way as the bot's other replies on that channel. Each notification runs one agent turn, which uses the bot's model like any other reply. If the account is over its conversation limits, no reply is sent.

Supported Channels

Messaging Windows

WhatsApp, Messenger and Instagram only allow free-form messages within 24 hours of the user's latest message. Outside that window the notification is not sent. It is stored on the conversation instead (see below), so the agent can report the outcome the next time the user writes.

Outcomes Stored for Later

In these cases the platform cannot message the user, so the outcome is added to the conversation without sending anything:

• Widget - the widget cannot receive messages from the server. The agent sees the outcome the next time the user writes in the widget.
• Twilio voice calls - a call cannot be messaged after it ends.
• Discord integrations set to reply ephemerally - an ephemeral reply is only possible within 15 minutes of the interaction, and posting to the channel would make a private reply public.
• WhatsApp, Messenger and Instagram outside the 24-hour window, as described above.

Each skipped delivery is recorded in the event log as a task.notify.skipped event with the reason, the task and the conversation.

Conversations That Are Not Notified

Nothing is sent or stored when the conversation:

• did not come through one of the channel integrations above, for example conversations created through the API or with the trigger integration, voice and realtime avatar sessions, and meeting integrations;
• was created before the platform started recording the reply address for its channel, so there is no address to reply to;
• belongs to a different account than the task.

Limits and Safeguards

• Rate limit: a conversation receives at most 10 task notifications per hour. Further notifications in that hour are dropped.
• No duplicates: repeated attempts to report the same run and status are deduplicated.
• Ordering: on channels with ordered processing, a notification is queued behind the conversation's incoming messages, so it does not interleave with a reply the bot is already writing.
• Chained tasks: the agent can start a new task with notify while it is reporting a task outcome, and that task reports back as well. A task started while reporting that second outcome cannot report back, which stops endless task loops.