> ## 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.

# Messaging

> Send messages from your phone's real apps - with your approval before anything goes out.

The phone agent can draft and send messages in the apps you actually use - WhatsApp, SMS, email - because it operates the real UI. The pattern that makes this safe is the **confirmation gate**: instruct the agent to show you the message and wait for your OK before sending.

## The basic pattern

```text theme={null}
Open WhatsApp on my phone and send Sam a message that I'm running 15
minutes late. Show me the exact message first and wait for my OK before
sending.
```

What happens:

1. The assistant starts a [`phone_run_task`](/api-reference/tools/phone-run-task)
   and waits on the monitor.
2. The agent drafts the message and pauses for your approval - either in your
   AI client's conversation, or as a `needs_user_control` handoff if the phone
   itself needs confirmation.
3. Only after your OK does the message go out.

<Warning>
  Always include the confirmation gate for anything that sends. Without it,
  you are trusting the agent's first draft with your name on it. Make "show me
  first" part of the prompt, not an afterthought.
</Warning>

## Prompt patterns that work

**Be explicit about recipient, content, and the gate:**

```text theme={null}
On my phone, open WhatsApp and message Alex Chen: "Running late, there in
20." Show me the message before sending. If there are multiple Alex
contacts, list them and ask me which one.
```

**Disambiguate up front.** Contact pickers, group chats with similar names, and multiple messaging apps are where messaging errands go wrong. Tell the agent what to do when it is unsure - ask, never guess.

**Reading is simpler than sending.** No gate needed for read-only errands:

```text theme={null}
Check WhatsApp on my phone and summarize any unread messages from today.
Don't open or mark anything as read that you don't need to, and don't reply
to anything.
```

## When the phone hands control back

If the messaging app throws something sensitive - a login screen, a verification prompt - the task completes with `terminal: "needs_user_control"` rather than the agent pushing through. Your assistant relays what is needed; you complete the step on the device or answer in chat, and the workflow continues as a continuation task. The full loop is in [Task lifecycle](/guides/concepts/task-lifecycle#human-in-the-loop-handoffs).

## Multi-message workflows

Keep related sends in one session so the workflow stays on one device:

```text theme={null}
On my phone: first check my calendar for tomorrow 9-11am. Then draft a
WhatsApp message to my team group proposing a time that's free, show it to
me, and send after I approve.
```

The assistant runs this as sequential tasks in one session - calendar read, then message draft - reusing the `session_id`. See [Session management](/guides/best-practices/session-management).

## Related

<CardGroup cols={2}>
  <Card title="Task design" icon="pen-to-square" href="/guides/best-practices/task-design">
    Confirmation gates, disambiguation, output contracts
  </Card>

  <Card title="Security" icon="lock" href="/guides/best-practices/security">
    Why sends should always be supervised
  </Card>
</CardGroup>