Aller au contenu principal

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​

NameTypeRequiredDescription
totextYesPatient's phone number in E.164 format
inputjsonNoWhole 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.
contexttextNoPer-conversation context appended to the agent's instructions (patient first name, discharge date, appointment)
first_messagetextNoPer-conversation override of the opening message
languagetextNoPer-conversation language override (BCP-47 or ISO 639-1)
timezonetextNoIANA time zone the patient is in, for the greeting in the opening message
patient_idtextNoPatient this conversation concerns. Stored on the thread and available to the agent's tools; never sent to the carrier.
outcome_schemajsonNoJSON Schema of the information the conversation must collect, overriding the configured one

Output ports​

NameTypeRequiredDescription
session_idtextNoThread identifier, for the conversation record and audit trail
statustextNoTerminal status: completed, transferred (escalated to a person), canceled (superseded) or failed
answeredbooleanNoWhether the patient replied at all
transcripttextNoVerbatim conversation transcript, one message per line
turnsjsonNoStructured message records with roles and any tools invoked
outcomejsonNoStructured values captured during the conversation, keyed as the outcome schema names them
completebooleanNoWhether every required outcome field was captured
missingjsonNoRequired outcome fields that were never captured; absent when complete
escalation_requestedbooleanNoThe agent asked for a person; the pipeline owes the patient a contact
escalation_reasontextNoWhat triggered the escalation, when there was one
identity_confirmedbooleanNoThe person replying was confirmed as the patient
documentablebooleanNoReplied, identified and said something: the only case a clinical note may be drafted from
durationnumberNoSeconds from the first reply to the end of the conversation
successbooleanNoThe conversation ended normally or by hand-over, whatever was captured
reasontextNoWhy the conversation ended, when the status alone does not say

Settings​

Set at least one of: agent_id, prompt.

Basic​

SettingNameTypeRequiredDefaultAllowed valuesDescription
SenderfromstringYesNumber the message is sent from, in E.164 format. Must belong to the organization.
ChannelchannelenumNosmssms, whatsappsms or whatsapp
Agentagent_idstringNoHydra agent that holds the conversation. Its prompt, language and tools are read from the stored definition.
PromptprompttextNoInline conversation instructions. Used alone for a one-off conversation, or appended to a named agent's own instructions.
Opening Messagefirst_messagestringNoThe first message sent. {{GREETING}} is replaced with a greeting for the patient's local time.
LanguagelanguagestringNoBCP-47 or ISO 639-1 language for the conversation (for example es-ES, ca, en)
Time ZonetimezonestringNoIANA zone the patient lives in (Europe/Madrid). Decides the {{GREETING}} in the opening message.
Risk ProfileprofileenumNostandardstandard, clinicalstandard for administrative conversations; clinical for patient-facing ones
Outcome Schemaoutcome_schemajsonNoJSON Schema of the information this conversation must collect. Required fields that are never captured mark it incomplete.
Escalation Contacttransfer_tostringNoRecorded with an escalation so the pipeline knows whom to route it to
Wait For Completionwait_for_completionbooleanNotrueSuspend the pipeline until the conversation ends. Disable to send the opening message and move on.

Advanced​

SettingNameTypeRequiredDefaultAllowed valuesDescription
CarriercarrierstringNoMessaging carrier. Empty uses the configured default.
Reply Timeout (hours)reply_timeout_hoursnumberNo24min 1; max 168How long the pipeline waits for the conversation to end before giving up

Errors​

CodeDescription
SERVICE_NOT_CONFIGUREDNo messaging carrier is configured on this deployment
DESTINATION_REQUIREDThe to input was missing or empty
INSTRUCTIONS_REQUIREDNeither agent_id nor prompt was supplied
SEND_FAILEDThe 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.