CumulusDocs
Open Studio
On this page

Continue a phone workflow with a cloud task

The call has ended, but the service team still needs the result recorded. A confirmed technician visit needs a CRM update; an unresolved request needs a review ticket; an uncertain reservation needs a transaction check before anyone retries it.

Build a cloud task that reads the service record and either updates the CRM or creates a review ticket. Start it with sample input first, then connect an event trigger or schedule. Your team supplies the CRM and ticket endpoints; the cloud task decides which one to call.

Build the follow-up flow

Continue work after a call
Download video

A cloud flow separating a completed-call path from scheduled review and branching on the outcome

Start with one case: a call about account DEMO-42 ended without a confirmed booking. The task reads that account's current booking state, creates a review ticket if the booking is still unresolved, and returns the ticket reference. Later, add a schedule that reviews the pending queue.

The flow accepts a completed-call event or a scheduled queue request. It reads the business record, chooses the appropriate action and returns a structured result. Each task has its own run ID, publication version, events, action receipts and usage.

Input pathReadIntended result
Resolved phone runSource run context and current business recordAn accurate CRM update
Call requiring reviewSource context and the outstanding business operationAn exception/reconciliation ticket
Confirmed bookingThe actual reservation recordThe booking outcome stored in the CRM
Unknown business outcomeThe transaction's state at the business serviceHuman review rather than repeating the write
Scheduled queue reviewYour pending-review serviceA review result under a separate task run

Define task inputs and outputs

Cloud execution modes, limits and JSON input/output schemas

Enable background in the publication for schedule/event-triggered work. Enable task too when exercising the input directly through the API: POST /api/v1/runs accepts only task or chat, not background. Define the input fields and the result your integration expects. Set a deadline and maximum turns so work cannot continue indefinitely.

In this example, work_type distinguishes phone from review_queue. A phone task carries a source_run_id, account reference and observed outcome; a scheduled request carries a queue name. Some source fields can be null. Your flow must handle missing context explicitly before calling a business endpoint.

Return string fields such as source_run_id, next_action and needs_review ("yes" or "no"). Declaring an output schema does not fill its fields: extract values or map action response fields into flow variables with matching names. Flow variables are stored as strings; declaring a numeric or boolean output property does not convert them. When the task ends, Cumulus builds its result from those named variables and checks it against the output schema. Follow the complete typed-result API example for exact schema, extraction-node and transition edits. Check the action receipt and business response before treating a returned recommendation as completed work.

Start work after a selected agent's run

Event and schedule triggers configured on the cloud agent

An event trigger mapping scoped source-run fields into the follow-up input

Choose the phone agent that should start this task, then select run.ended. A mapping copies a field from the completed run into the task input. For example, /run_id becomes source_run_id, which lets an operator find the original call:

Input fieldMapping in this exampleMeaning
work_type/channelThe source channel, phone here
source_run_id/run_idThe original run's identity
outcome/outcome/business/valueThe reported business outcome, if present; read the business service when it is unknown
account_reference/metadata/account_referenceContext supplied on the original phone run

Available source fields include the run ID, agent ID, channel, outcome, phone-run variables and metadata. Phone numbers are not included. A field that is missing maps to null, so the target input schema and flow must account for it.

Choose run.ended when the work depends on the terminal run outcome. Choose analysis.updated when it needs completed analysis. Those events represent different readiness points: a run can end before all derived output is available.

See triggers and webhooks for the trigger configuration fields. Publishing makes the trigger part of that version.

Use a schedule for the queue path

A weekday review schedule with time zone and explicit input

For scheduled work, provide a valid cron expression, time zone and input. This example passes { "work_type": "review_queue", "review_queue": "pending" }. This input omits source_run_id because the schedule has no source phone run: make that property optional in your input schema. If your schema instead requires a nullable source ID, send "source_run_id": null. An empty string is a different value; do not use it as a substitute for omission or null.

Keep the schedule input compatible with the publication's input schema. Test a daylight-saving transition, an empty queue, a slow queue service and a task that reaches its deadline. Decide which outcomes require a human notification.

Route on facts and handle uncertainty

The cloud outcome branch routing resolved, review and booking work to different actions

Read the business state before updating the CRM. For an uncertain reservation or refund, query the original transaction first. Do not repeat the write under a new idempotency key.

Use separate named actions for the CRM update and review ticket. Their endpoints validate the inputs and handle repeated writes safely. Cumulus records each action’s attempts and receipts under the task’s run ID.

To try the task before adding a trigger, publish your follow-up agent with task enabled and the input fields below. Connect its record lookup and review-ticket actions, then send this request. Use sandbox endpoints or mocks for development; test: true excludes billing and triggers but does not suppress customer HTTP actions.

Replace your-follow-up-agent-id and version: 0 with the agent ID and candidate version returned by your setup. Replace the source run ID and business references with compatible test data:

<!-- operation:runs.create -->
json
{
  "channel": "cloud",
  "agent_id": "your-follow-up-agent-id",
  "version": 0,
  "test": true,
  "mode": "task",
  "input": {
    "work_type": "phone",
    "source_run_id": "22222222-2222-4222-8222-222222222222",
    "account_reference": "DEMO-42",
    "outcome": "manual_review"
  },
  "metadata": { "workflow_reference": "DEMO-42" }
}

Use Start a run, retain the idempotency key, follow its events and wait for completion before reading the task result.

Read an output and its state

A cloud task result presented as typed fields and JSON with usage and details nearby

Open the task’s Result tab or read runs.result. Its state is pending, ready, none or expired. Use the output only when it is ready; an expired result was removed, while none means no result is available. Read runs.get separately for the run’s state, outcome.execution and outcome.reason. An API request error is returned in error; a failed admitted run is described by its outcome. Use bounded result polling to handle pending output, failure and a client deadline.

For example, a ready result could be {"source_run_id":"<original run>","next_action":"review_created","needs_review":"yes"}. Those values must come from the task's declared variables; a sentence in its transcript does not fill them automatically.

Keep both the source phone run ID and the cloud task run ID. The first locates the original phone run; the second locates the follow-up actions. Store the source ID in the task input and returned result to connect the two records.

Test before enabling the trigger

After the direct task works, publish the reviewed draft with live: true to activate its trigger. A test-only publication still requires test runs even if selected as head. See publication and recovery for the requests.

Test matching and non-matching source agents, missing metadata, unknown business outcomes, event redelivery, unavailable business services and incompatible target schemas. Use mocks for repeatable agent tests and a separate authorized integration run for the real endpoints.

Enable the trigger on a tested live publication. Review the first tasks’ source context, action receipts and results to confirm that the mapping and downstream updates work as intended.

Content version 293d3a84Customer SDKMarkdown source
Continue a phone workflow with a cloud task · Cumulus developer docs