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

# Messages

> Conversational messaging with patient personas or portal chat agents.

The Messages simulator stands in for conversational messaging endpoints in healthcare: SMS appointment reminders, patient-facing chat, portal inbox messages, follow-up outreach. Your agent sends messages to the simulator, the simulator replies as the configured persona (a patient, a front-desk agent, a nurse line), and the full exchange is captured as interaction evidence.

## How your agent connects

Every message exchange is mediated by HTTP on the direct-service surface. The simulator is stateful per sandbox: earlier messages are available via the list endpoint, and each send records the outbound message for later evidence.

<Note>
  The Message simulator is not currently mounted on the run-scoped `/v1/benchmark-runs/{id}/messages/*` surface. During a benchmark run, resolve the Message sandbox from the `sandboxes` list on the run response and call the direct `/sandboxes/{id}/messages` endpoints with an organization API key.
</Note>

## Endpoints

| Method | Endpoint                                        | Description                                                                            |
| ------ | ----------------------------------------------- | -------------------------------------------------------------------------------------- |
| `POST` | `/sandboxes/{sandbox_id}/messages`              | Send a message (SMS or email) to a patient                                             |
| `GET`  | `/sandboxes/{sandbox_id}/messages`              | List messages for this sandbox (optional `patient_id`, `channel`, `direction` filters) |
| `GET`  | `/sandboxes/{sandbox_id}/messages/{message_id}` | Retrieve a specific message                                                            |

See [Send message](/api-reference/messages/send), [List messages](/api-reference/messages/list), and [Get message](/api-reference/messages/get).

## Driving the rollout

Send an outbound message (direct-service path):

```bash theme={null}
curl -X POST "https://api.verial.ai/sandboxes/$MESSAGE_SANDBOX_ID/messages" \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "patient_id": "patient-123",
    "body": "Hi John, this is a reminder of your follow-up appointment on Friday at 10am. Reply YES to confirm."
  }'
```

Response (single message record):

```json theme={null}
{
  "id": "msg_01H...",
  "channel": "sms",
  "patient_id": "patient-123",
  "direction": "outbound",
  "status": "delivered",
  "to": "+15551234567",
  "body": "Hi John, ...",
  "sent_at": "2026-04-23T17:00:00.000Z",
  "delivered_at": "2026-04-23T17:00:00.000Z"
}
```

List the conversation so far:

```bash theme={null}
curl "https://api.verial.ai/sandboxes/$MESSAGE_SANDBOX_ID/messages?patient_id=patient-123" \
  -H "Authorization: Bearer $VERIAL_API_KEY"
```

## Configuration

At create time you configure the persona the simulator should speak as and any scripted behavior (required disclosures, topics the persona will or won't discuss).

```bash theme={null}
curl -X POST https://api.verial.ai/simulators \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "type": "Message",
  "name": "Patient Reminder Line",
  "config": {
    "persona": {
      "role": "patient",
      "name": "John Smith",
      "traits": ["hard_of_hearing", "prefers_text_messages"]
    },
    "constraints": [
      "Will only confirm appointment if the agent correctly references the provider name."
    ]
  }
}
JSON
```

## Verification

There is no dedicated messages check type in the current criterion catalog. Messaging evidence is scored in two ways:

* **Interaction evidence.** Every message sent and received is logged as an interaction. The full conversation is attached to criterion-run evidence for review.
* **Cross-simulator criteria.** If the messaging exchange is expected to produce downstream state (for example the patient confirms an appointment, which should appear as a confirmed FHIR Appointment), the `fhir-resource-state` or `portal-state-match` criterion on that downstream resource is what scores correctness.

For transcript-style phrase assertions analogous to `voice-transcript`, prefer the voice simulator until a dedicated message-transcript check ships.

## Next Steps

<CardGroup cols={2}>
  <Card title="Voice" icon="phone" href="/guides/simulators/voice">
    For voice-native conversations with `voice-transcript` assertions.
  </Card>

  <Card title="Messages API reference" icon="code" href="/api-reference/messages/send">
    Direct-access messaging endpoints for authoring.
  </Card>

  <Card title="Interactions" icon="clipboard-list" href="/guides/concepts/interactions">
    How message history and other evidence are recorded.
  </Card>

  <Card title="Simulators overview" icon="server" href="/guides/simulators/overview">
    Lifecycle, provisioning, and configuration patterns.
  </Card>
</CardGroup>