Skip to main content
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

​
string
required
The active session that owns the task.
​
string
required
The running task to steer, or the completed needs_user_control task to answer.
​
string
required
The guidance or answer to deliver.

​
Mode 1: steer a running task

  • 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:
  • 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.
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.