Send Message
Category: Integration
Node id: message-send
Maturity: beta
Risk tier: B
Standards: HIPAA, GDPR
Opens an SMS or WhatsApp conversation in which a Hydra agent holds the exchange, then suspends the pipeline until the conversation ends and returns the transcript and the structured outcome it was opened to collect. The voice-call node's sibling: same agents, same outcome schema, same rules on what may be recorded.
What it does
- Outbound SMS and WhatsApp conversations with a Hydra agent holding the exchange
- The same agent definitions, tools and outcome schema as the voice-call node
- Structured outcome capture gated on the patient's own messages
- Escalation to a person recorded as a terminal outcome the pipeline can route
- Suspend/resume execution across replies that may take hours
- Carrier webhook signature verification on every inbound message
Use cases
- Follow up after discharge over WhatsApp and collect symptom answers at the patient's pace
- Confirm tomorrow's appointment by SMS and record the confirmation
- Reach a patient who does not answer calls, with the same questions and the same record
Runtime
- Performance tier:
slow
Input ports
| Name | Type | Required | Description |
|---|---|---|---|
to | text | Yes | Patient's phone number in E.164 format |
input | json | No | Whole request object from an upstream input node. The executor merges it key by key, so phone, patient_id, patient_name and language arrive under their own names. |
context | text | No | Per-conversation context appended to the agent's instructions (patient first name, discharge date, appointment) |
first_message | text | No | Per-conversation override of the opening message |
language | text | No | Per-conversation language override (BCP-47 or ISO 639-1) |
timezone | text | No | IANA time zone the patient is in, for the greeting in the opening message |
patient_id | text | No | Patient this conversation concerns. Stored on the thread and available to the agent's tools; never sent to the carrier. |
outcome_schema | json | No | JSON Schema of the information the conversation must collect, overriding the configured one |
Output ports
| Name | Type | Required | Description |
|---|---|---|---|
session_id | text | No | Thread identifier, for the conversation record and audit trail |
status | text | No | Terminal status: completed, transferred (escalated to a person), canceled (superseded) or failed |
answered | boolean | No | Whether the patient replied at all |
transcript | text | No | Verbatim conversation transcript, one message per line |
turns | json | No | Structured message records with roles and any tools invoked |
outcome | json | No | Structured values captured during the conversation, keyed as the outcome schema names them |
complete | boolean | No | Whether every required outcome field was captured |
missing | json | No | Required outcome fields that were never captured; absent when complete |
escalation_requested | boolean | No | The agent asked for a person; the pipeline owes the patient a contact |
escalation_reason | text | No | What triggered the escalation, when there was one |
identity_confirmed | boolean | No | The person replying was confirmed as the patient |
documentable | boolean | No | Replied, identified and said something: the only case a clinical note may be drafted from |
duration | number | No | Seconds from the first reply to the end of the conversation |
success | boolean | No | The conversation ended normally or by hand-over, whatever was captured |
reason | text | No | Why the conversation ended, when the status alone does not say |
Settings
Set at least one of: agent_id, prompt.
Basic
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Sender | from | string | Yes | Number the message is sent from, in E.164 format. Must belong to the organization. | ||
| Channel | channel | enum | No | sms | sms, whatsapp | sms or whatsapp |
| Agent | agent_id | string | No | Hydra agent that holds the conversation. Its prompt, language and tools are read from the stored definition. | ||
| Prompt | prompt | text | No | Inline conversation instructions. Used alone for a one-off conversation, or appended to a named agent's own instructions. | ||
| Opening Message | first_message | string | No | The first message sent. {{GREETING}} is replaced with a greeting for the patient's local time. | ||
| Language | language | string | No | BCP-47 or ISO 639-1 language for the conversation (for example es-ES, ca, en) | ||
| Time Zone | timezone | string | No | IANA zone the patient lives in (Europe/Madrid). Decides the {{GREETING}} in the opening message. | ||
| Risk Profile | profile | enum | No | standard | standard, clinical | standard for administrative conversations; clinical for patient-facing ones |
| Outcome Schema | outcome_schema | json | No | JSON Schema of the information this conversation must collect. Required fields that are never captured mark it incomplete. | ||
| Escalation Contact | transfer_to | string | No | Recorded with an escalation so the pipeline knows whom to route it to | ||
| Wait For Completion | wait_for_completion | boolean | No | true | Suspend the pipeline until the conversation ends. Disable to send the opening message and move on. |
Advanced
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Carrier | carrier | string | No | Messaging carrier. Empty uses the configured default. | ||
| Reply Timeout (hours) | reply_timeout_hours | number | No | 24 | min 1; max 168 | How long the pipeline waits for the conversation to end before giving up |
Errors
| Code | Description |
|---|---|
SERVICE_NOT_CONFIGURED | No messaging carrier is configured on this deployment |
DESTINATION_REQUIRED | The to input was missing or empty |
INSTRUCTIONS_REQUIRED | Neither agent_id nor prompt was supplied |
SEND_FAILED | The carrier refused the opening message |
Runtime notes
- The node suspends the execution while the conversation runs and resumes when the agent ends it, escalates, or the reply timeout passes — it does not block an executor goroutine
- answered=false means the patient never replied: the opening message was sent and nothing came back before the timeout
- answered=true with complete=false means the patient replied but not every required answer was captured — treat it as a follow-up, not a success
- A required answer is recorded only after the patient writes something new, one per message, and the agent cannot end the conversation while required answers are missing: the same rules as on a call
- transfer_to_human on a thread records an escalation and ends the conversation as transferred; nobody is connected live, so the pipeline must route the escalation to a person
- One thread per pair of numbers: opening a new conversation with a patient who has one open closes the old one as canceled
- WhatsApp: outside a 24-hour customer-service window the carrier requires an approved template; this node sends plain text, so the first message must fall inside that window or the carrier rejects it
- The thread lives in the voice service's session store; on this deployment that store is in memory, so a restart loses open conversations
See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.
Quelque chose n'est pas clair ? Envoyez vos commentaires sur la documentation par courriel.