Messages

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.

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.

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, List messages, and Get message.

Driving the rollout

Send an outbound message (direct-service path):

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):

{
  "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:

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

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

Voice

For voice-native conversations with voice-transcript assertions.

Messages API reference

Direct-access messaging endpoints for authoring.

Interactions

How message history and other evidence are recorded.

Simulators overview

Lifecycle, provisioning, and configuration patterns.

Getting Started

Core Concepts

Simulators

Observability

Guides

How your agent connects

Endpoints

Driving the rollout

Configuration

Verification

Next Steps

Voice

Messages API reference

Interactions

Simulators overview

​How your agent connects

​Endpoints

​Driving the rollout

​Configuration

​Verification

​Next Steps

Voice

Messages API reference

Interactions

Simulators overview

How your agent connects

Endpoints

Driving the rollout

Configuration

Verification

Next Steps