Zum Hauptinhalt springen

Voice Call

Category: Integration
Node id: voice-call
Maturity: beta
Risk tier: B

Standards: HIPAA, GDPR

Places an outbound phone call in which a Hydra agent holds a spoken conversation, then suspends the pipeline until the call ends and returns the transcript and the structured outcome the call was made to collect.

What it does​

  • Outbound PSTN calls with a Hydra agent holding the conversation
  • Engine-agnostic: vendor-run or Hydra-run conversation behind the same ports
  • Hydra tools bridged into the live call with tenancy, PHI guard and audit intact
  • Structured outcome capture against a declared JSON Schema
  • Warm transfer to a human, always available under the clinical profile
  • Recording gated behind a spoken consent announcement
  • Suspend/resume execution so a long call does not hold an executor goroutine
  • Per-item overrides so one node serves a whole call list

Use cases​

  • Call patients to confirm tomorrow's appointments and record the confirmation
  • Follow up after discharge to collect symptom answers and escalate to a nurse when needed
  • Chase a contracting authority about a tender deadline and capture the answer
  • Qualify an inbound lead and write the result back to CRM

Runtime​

  • Performance tier: slow
  • Execution mode: trigger
  • Default timeout: 720 seconds

Input ports​

NameTypeRequiredDescription
totextYesDestination phone number in E.164 format
inputjsonNoWhole request object from an upstream input node (its output port to this input port). The executor merges it key by key, so phone, patient_id, patient_name and language arrive under their own names; the fields that are not set stay untouched. Lets a pipeline run from the input node's defaults when Studio triggers it without inputs.
contexttextNoPer-call context appended to the agent's instructions (patient first name, appointment time, tender reference)
first_messagetextNoPer-call override of the agent's opening line
languagetextNoPer-call language override (BCP-47 or ISO 639-1)
timezonetextNoIANA time zone the person being called is in, e.g. Europe/Madrid. Sets the greeting and tells the agent the hour.
patient_idtextNoPatient this call concerns. Stored on the call record and available to bridged tools; never placed in the prompt sent to a conversation vendor.
outcome_schemajsonNoJSON Schema of the information the call must collect, overriding the configured one

Output ports​

NameTypeRequiredDescription
session_idtextNoCall session identifier, for the call record and audit trail
statustextNoTerminal call status: completed, transferred, no_answer, busy, rejected, failed or canceled
answeredbooleanNoWhether the call was picked up at all
transcripttextNoVerbatim conversation transcript, one turn per line
turnsjsonNoStructured turn records with roles and any tools invoked
outcomejsonNoStructured information captured during the call, keyed by outcome_schema field name
completebooleanNoFalse when a required outcome_schema field was never captured
durationnumberNoCall duration in seconds
successbooleanNoTrue only for a completed or transferred call
escalation_requestedbooleanNoThe agent asked for a human at some point, whether or not the transfer then succeeded. Branch on this to file a callback, not on status alone: a transfer that fails at the carrier leaves status 'completed' while the patient has been promised a call.
identity_confirmedbooleanNoThe person on the line was confirmed to be the patient (from the captured outcome). Nothing clinical should be documented when this is false.
documentablebooleanNoanswered AND identity_confirmed AND the caller said something. The only condition under which a clinical note may be drafted from this call.

Settings​

Set at least one of: agent_id, prompt.

Basic​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Caller IDfromstringYesNumber the call is placed from, in E.164 format. Must belong to the organization.
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 call, or appended to a named agent's own instructions.
Opening Linefirst_messagestringNoWhat the agent says when the call connects. Empty waits for the other party to speak first.
LanguagelanguagestringNoBCP-47 or ISO 639-1 language for the conversation (for example es-ES, ca, en)
Time ZonetimezonestringNoIANA zone the person being called lives in (Europe/Madrid). Decides the {{GREETING}} in the opening line and what the agent is told about the hour. Empty falls back to the deployment default, then to the destination country when it keeps a single civil time.
Voicevoice_idstringNoProvider voice identifier for the agent's speech
Risk ProfileprofileenumNostandardstandard, clinicalstandard for administrative and business calls; clinical for patient-facing calls, which always keep a transfer-to-human path
Outcome Schemaoutcome_schemajsonNoJSON Schema of the information this call must collect. Required fields that are never captured mark the call incomplete.
Transfer Destinationtransfer_tostringNoNumber a call is warm-transferred to when the agent escalates to a human
Wait For Completionwait_for_completionbooleanNotrueSuspend the pipeline until the call ends. Disable for fire-and-forget calls.

Advanced​

SettingNameTypeRequiredDefaultAllowed valuesDescription
CarriercarrierstringNoTelephony carrier to place the call with. Empty uses the configured default.
Conversation EngineenginestringNoEngine that runs the conversation. Empty uses the configured default.
ModelmodelstringNoEngine model for this call (e.g. a newer Live model on a copy of a pipeline). Empty uses the deployment default.
Max Duration (seconds)max_durationnumberNo600min 30; max 3600Hard limit enforced by the carrier, not only by Hydra
Record CallrecordbooleanNofalseRecord the call audio. Requires consent_script; the announcement is played before anything else.
Recording Consent Scriptconsent_scripttextNoAnnouncement played and acknowledged before recording starts, in the call language
Detect Answering Machinemachine_detectionbooleanNofalseReport when the carrier believes voicemail answered, so a reminder is not counted as delivered
Speech Start Sensitivityvad_start_sensitivityenumNo"", HIGH, LOWHow readily the model decides the caller has started speaking. LOW ignores more line noise and echo (which cut the greeting on a real call) and misses more quiet openings. Empty: deployment default HYDRA_VOICE_VAD_START_SENSITIVITY, else HIGH.
Speech End Sensitivityvad_end_sensitivityenumNo"", HIGH, LOWHow readily the model decides the caller has stopped. LOW waits through longer pauses but, on a real call, left the agent talking over answers. Empty: HYDRA_VOICE_VAD_END_SENSITIVITY, else HIGH.
Speech Prefix Padding (ms)vad_prefix_padding_msnumberNomin 0; max 5000Audio kept before detected speech so the first syllable is not clipped. 0 or empty: HYDRA_VOICE_VAD_PREFIX_PADDING_MS, else 300.
End-of-Turn Silence (ms)vad_silence_msnumberNomin 0; max 10000Silence that ends the caller's turn. Below 200 utterances split into fragments; above 1000 the agent feels slow. 0 or empty: HYDRA_VOICE_VAD_SILENCE_MS, else 800.
Capture Result Schedulingcapture_schedulingenumNo"", SILENT, WHEN_IDLE, INTERRUPT, DEFAULTWhat the model does with a capture_structured result. WHEN_IDLE (default) answers it at the next pause, which on 3.x is what brings the model back for the next question; SILENT keeps it without any reaction (on 3.x the call stalled after every answer until the patient spoke again); INTERRUPT answers at once; DEFAULT sends no policy.
Tool Result Schedulingtool_schedulingenumNo"", SILENT, WHEN_IDLE, INTERRUPT, DEFAULTThe same policy for every other tool's result (agent tools, end_call, transfer). Default WHEN_IDLE: answered at the next pause, guaranteed; a result with no policy left a real call silent for 25 seconds.
Conversation Ruleslive_rulestextNoRules appended after the agent's instructions on every call. Empty: the built-in block (at most two consecutive tool calls without speaking; capture_structured is a silent execution, never 'lo he anotado'; short, varied or no acknowledgements; RESPOND IN the call's language). Write 'none' to append nothing, or your own text to replace the block.
Loop Nudge After N Capturesnudge_after_callsnumberNomin 0; max 20How many capture_structured calls the model may make with nothing from the caller in between before the media loop tells it, as a turn of its own, to stop calling tools and ask the next question (and again at each multiple). 0 or empty: 3.
Engine Optionsengine_optionsjsonNoProvider-specific settings, passed through to the selected engine as-is; unknown keys are ignored, so a workflow can carry options for any provider. Gemini reads proactive_audio (bool: respond only when addressed, ignore background chatter), affective_dialog (bool: adapt to the caller's tone; Google warns it can produce unexpected results) and custom_vocabulary (list of terms to bias speech recognition toward, e.g. clinic and drug names). Example: {"custom_vocabulary":["TietAI","Sintrom"]}
Text Turn Transporttext_turnenumNo"", client, realtimeHow the opening line and the loop nudge reach the model: client (default) is a complete client-content turn the model answers at once; realtime is realtime text input, whose end of turn the model infers from activity (13 s to the greeting on a real call). Empty: HYDRA_VOICE_TEXT_AS_REALTIME, else client.

Errors​

CodeDescription
SERVICE_NOT_CONFIGUREDNo telephony carrier or conversation engine is configured on this deployment
DESTINATION_REQUIREDThe to input was missing or empty
INSTRUCTIONS_REQUIREDNeither agent_id nor prompt was supplied
CONSENT_REQUIREDrecord is enabled but no consent_script was provided
ORIGINATE_FAILEDThe carrier rejected the call (bad number, unverified caller id, no balance)
PREPARE_FAILEDThe conversation engine rejected the agent configuration

Runtime notes​

  • The node suspends the execution while the call runs and resumes when the carrier reports a terminal status — it does not block an executor goroutine
  • A call that was never answered still resumes the pipeline: status is no_answer/busy/failed, answered=false and success=false, so branch on success rather than assuming a transcript exists
  • answered=true with complete=false means someone talked but the required outcome fields were never captured — treat that as a follow-up, not a success
  • Set wait_for_completion=false for fire-and-forget calls: the node returns immediately with session_id and no transcript
  • agent_id reads the conversation's prompt, language and tools from the stored agent definition; prompt alone is for one-off calls. Supplying both appends the prompt to the agent's own instructions rather than replacing them
  • Tools the agent calls during the conversation execute inside Hydra with org tenancy, PHI guard and audit — the conversation vendor never touches a record
  • profile=clinical forces a transfer-to-human tool onto the conversation that the agent definition cannot remove
  • Provider choice is a data-residency decision: an EU-resident engine is required before any patient-facing call

See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.

Etwas unklar? Senden Sie Feedback zur Dokumentation per E-Mail..