> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agi.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# phone_task_message

> Steer a running task, or answer a task that handed control back.

Sends text into a task. It has two distinct modes, with different success signals:

1. **Steering a running task** - the message is added to the active task as
   extra guidance.
2. **Answering a completed `needs_user_control` task** - the phone handed a
   sensitive step back to the user (a login, a confirmation, a CAPTCHA); this
   call answers it and dispatches a **continuation task**.

## Parameters

<ParamField body="session_id" type="string" required>
  The active session that owns the task.
</ParamField>

<ParamField body="task_id" type="string" required>
  The running task to steer, or the completed `needs_user_control` task to
  answer.
</ParamField>

<ParamField body="text" type="string" required>
  The guidance or answer to deliver.
</ParamField>

## Mode 1: steer a running task

```json theme={null}
{
  "session_id": "session-uuid",
  "task_id": "task-uuid",
  "text": "Use the second option."
}
```

* Keep monitoring the **same** `task_id` - a message to a running task does
  not create a new task.
* **Success signal:** `delivered_to_device`. A `false` value means the message
  was recorded in task history but not delivered, usually because the task
  already completed.

## Mode 2: answer a needs\_user\_control task

When a task completes with `terminal: "needs_user_control"`, inspect
`error.control_type` and `error.prompt` to see what the phone needs, collect
the user's answer - or let them complete the step directly on the device -
then send the reply. If the user handled the step on the phone, send a short
acknowledgement:

```json theme={null}
{
  "session_id": "session-uuid",
  "task_id": "task-uuid",
  "text": "I completed the requested step on the phone. Continue."
}
```

* **Success signal:** the presence of `continuation_task_id` in the response.
  Here `delivered_to_device: false` is **not** a failure - the original task
  is already completed.
* Monitor the `continuation_task_id`, not the completed original task; it
  will not become `running` again.
* A continuation task can itself finish with `needs_user_control`; repeat the
  monitor-and-answer loop until a terminal outcome no longer requests control.
* Repeating the same answer is safe, but a different second answer is
  rejected.

<Warning>
  Never forward sensitive values (passwords, payment details) through task
  messages when the user can complete the step on the device themselves -
  that is exactly what the `needs_user_control` handoff is for. See
  [Security](/guides/best-practices/security).
</Warning>

## Related

* [`phone_task_monitor`](/api-reference/tools/phone-task-monitor) - catches the `needs_user_control` handoff
* [Task lifecycle](/guides/concepts/task-lifecycle#human-in-the-loop-handoffs) - the handoff loop end-to-end