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

MethodEndpointDescription
POST/sandboxes/{sandbox_id}/messagesSend a message (SMS or email) to a patient
GET/sandboxes/{sandbox_id}/messagesList 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.