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

# Read from Contact

> Read the recent SMS exchange with the contact mid-call and write it to a variable you nominate.

## Description

Reads the recent SMS exchange between the contact and the assistant and writes it, as a plain-text transcript, to a variable you nominate. It looks at messages sent and received in a short window — roughly the last 5 minutes — so it is used mid-call to pick up a reply the contact has just texted. Returns `true` when at least one SMS is found in that window and written to your destination variable.

This is a low-level building block. It does **not** interpret or extract anything from the reply — it hands you the raw conversation so a later step can act on it. To collect and validate an email address from a texted reply, use the dedicated **[SMS | Get Valid Email](/tools/composite/sms-get-email)** composite, which runs the whole round-trip (send, wait, read, extract, validate) and publishes the result as `{{sms.email}}`.

***

## Manual Inputs

| Name                         | Data Type | Required | Description                                                                                                                                                                                        |
| ---------------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SMS sender phone number      | string    | No       | Optional Australian mobile to read messages from (`04XXXXXXXX` or `+614XXXXXXXX`). Leave blank to use the contact's own number.                                                                    |
| Messages History Destination | string    | Yes      | The variable to write the transcript into — typically a custom variable such as `{{custom.sms_history}}`. Type `/` to insert a variable reference. Without a destination the tool returns `false`. |

***

## Global Inputs

This tool automatically uses:

| Variable            | Description                                                                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{{contact.phone}}` | The contact's phone number (string, e.g. `+61412345678`) — the number whose recent exchange is read, unless you override it with a sender number above. |

It also draws on the assistant's own mobile number and the current call's team context, both supplied automatically. If any of these is missing, the tool returns `false`.

***

## Manual Outputs

| Name   | Data Type | Description                                                                        |
| ------ | --------- | ---------------------------------------------------------------------------------- |
| result | bool      | `true` if a recent SMS exchange was found and written to your destination variable |

***

## Global Outputs

This tool writes no fixed global variable. Its only outputs are the boolean `result` you route on and the message history it writes to the destination variable you nominate — see [Variables this tool writes](#variables-this-tool-writes) below.

***

## Conditions

### Success (true)

The tool returns `true` when:

* At least one SMS with the contact is found within the recent window (approximately 5 minutes)
* The transcript is written successfully to your destination variable

### Failure (false)

The tool returns `false` when:

* No SMS is found for the contact's number within the window
* No destination variable was provided, or the value given is not a writable variable reference
* The contact's mobile number is missing (and no valid sender number was supplied)
* The assistant's phone number is not configured, or the call's team context is unavailable

***

## Variables this tool writes

This tool writes a single value: the recent SMS exchange with the contact, saved to the destination variable you nominate (typically a custom variable). It does not extract or write an email address itself.

| Variable                                                            | Type   | Written                                                                                                     | Example                                                  |
| ------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| Your nominated destination variable (e.g. `{{custom.sms_history}}`) | string | On success — when at least one SMS with the contact is found in the recent window (approximately 5 minutes) | `Messages History`<br />`user: jane.citizen@example.com` |

The value is a plain-text transcript of the recent exchange: a `Messages History` heading followed by one `user:` or `assistant:` line per message, in time order. The tool keeps no fixed variable namespace of its own — it writes only to the destination you point it at. On failure it returns `false` and writes nothing (for example when no SMS is found, the destination variable is missing, or the contact's mobile number is unavailable).

To turn a texted reply into a validated email address, use the dedicated **SMS | Get Valid Email** composite: it sends the request, waits for the reply, then extracts and validates the email and publishes it as `{{sms.email}}` (string, e.g. `jane.citizen@example.com`) for you to map onto `{{contact.email}}`.

See [Variables](/flows/variables) to reference these values in later steps.

***

## Example Usage

```text theme={null}
Step 1 (Tool): SMS - Send to Contact
   Input: "Reply to this message with the reference number from your letter."

Step 2 (Voice): "I've just texted you — go ahead and reply whenever you're ready."

Step 3 (Tool): SMS - Read from Contact
   Messages History Destination: {{custom.sms_history}}

   Condition: true (success)
   -> Next: process_reply
   -> Script: "Thanks, I've got your message."

   Condition: Otherwise (failure)
   -> Next: retry_step
   -> Script: "I haven't received your text yet. Would you like to try again?"
```

On success, `{{custom.sms_history}}` holds the recent exchange as plain text, ready for a following [Code Step](/tools/code-step/overview) or [LLM tool](/tools/llm/overview) to read the reply and act on it.

***

## Best Practices

1. **Send first, then read** — Text the contact with [Send to Contact](/tools/sms/send) before reading, so there is a fresh reply within the window
2. **Give them time to reply** — Set a patient silence tolerance and, if needed, speak a short holding line before the read step
3. **Nominate a clear destination** — Point the transcript at a purpose-named custom variable such as `{{custom.sms_history}}`
4. **Collecting an email? Use the composite** — For a validated email address, use the **SMS | Get Valid Email** composite rather than parsing the transcript yourself
5. **Handle the no-reply path** — Route the **Otherwise** condition to a retry or a fallback that collects the detail another way

***

## Next Steps

* [Send to Contact](/tools/sms/send) — Send an SMS to the contact during the call.
* [SMS Tools Overview](/tools/sms/overview) — How the SMS tools work together, and the variables each one writes.
* [Tool Steps](/flows/steps-tool) — Learn how to configure tool steps.
* [Variables](/flows/variables) — See all available variables.