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
| Name | Type | Required | Description |
|---|---|---|---|
to | text | Yes | Destination phone number in E.164 format |
input | json | No | Whole 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. |
context | text | No | Per-call context appended to the agent's instructions (patient first name, appointment time, tender reference) |
first_message | text | No | Per-call override of the agent's opening line |
language | text | No | Per-call language override (BCP-47 or ISO 639-1) |
timezone | text | No | IANA time zone the person being called is in, e.g. Europe/Madrid. Sets the greeting and tells the agent the hour. |
patient_id | text | No | Patient this call concerns. Stored on the call record and available to bridged tools; never placed in the prompt sent to a conversation vendor. |
outcome_schema | json | No | JSON Schema of the information the call must collect, overriding the configured one |
Output ports
| Name | Type | Required | Description |
|---|---|---|---|
session_id | text | No | Call session identifier, for the call record and audit trail |
status | text | No | Terminal call status: completed, transferred, no_answer, busy, rejected, failed or canceled |
answered | boolean | No | Whether the call was picked up at all |
transcript | text | No | Verbatim conversation transcript, one turn per line |
turns | json | No | Structured turn records with roles and any tools invoked |
outcome | json | No | Structured information captured during the call, keyed by outcome_schema field name |
complete | boolean | No | False when a required outcome_schema field was never captured |
duration | number | No | Call duration in seconds |
success | boolean | No | True only for a completed or transferred call |
escalation_requested | boolean | No | The 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_confirmed | boolean | No | The person on the line was confirmed to be the patient (from the captured outcome). Nothing clinical should be documented when this is false. |
documentable | boolean | No | answered 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
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Caller ID | from | string | Yes | Number the call is placed from, in E.164 format. Must belong to the organization. | ||
| 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 call, or appended to a named agent's own instructions. | ||
| Opening Line | first_message | string | No | What the agent says when the call connects. Empty waits for the other party to speak first. | ||
| 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 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. | ||
| Voice | voice_id | string | No | Provider voice identifier for the agent's speech | ||
| Risk Profile | profile | enum | No | standard | standard, clinical | standard for administrative and business calls; clinical for patient-facing calls, which always keep a transfer-to-human path |
| Outcome Schema | outcome_schema | json | No | JSON Schema of the information this call must collect. Required fields that are never captured mark the call incomplete. | ||
| Transfer Destination | transfer_to | string | No | Number a call is warm-transferred to when the agent escalates to a human | ||
| Wait For Completion | wait_for_completion | boolean | No | true | Suspend the pipeline until the call ends. Disable for fire-and-forget calls. |
Advanced
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Carrier | carrier | string | No | Telephony carrier to place the call with. Empty uses the configured default. | ||
| Conversation Engine | engine | string | No | Engine that runs the conversation. Empty uses the configured default. | ||
| Model | model | string | No | Engine 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_duration | number | No | 600 | min 30; max 3600 | Hard limit enforced by the carrier, not only by Hydra |
| Record Call | record | boolean | No | false | Record the call audio. Requires consent_script; the announcement is played before anything else. | |
| Recording Consent Script | consent_script | text | No | Announcement played and acknowledged before recording starts, in the call language | ||
| Detect Answering Machine | machine_detection | boolean | No | false | Report when the carrier believes voicemail answered, so a reminder is not counted as delivered | |
| Speech Start Sensitivity | vad_start_sensitivity | enum | No | "", HIGH, LOW | How 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 Sensitivity | vad_end_sensitivity | enum | No | "", HIGH, LOW | How 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_ms | number | No | min 0; max 5000 | Audio 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_ms | number | No | min 0; max 10000 | Silence 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 Scheduling | capture_scheduling | enum | No | "", SILENT, WHEN_IDLE, INTERRUPT, DEFAULT | What 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 Scheduling | tool_scheduling | enum | No | "", SILENT, WHEN_IDLE, INTERRUPT, DEFAULT | The 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 Rules | live_rules | text | No | Rules 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 Captures | nudge_after_calls | number | No | min 0; max 20 | How 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 Options | engine_options | json | No | Provider-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 Transport | text_turn | enum | No | "", client, realtime | How 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
| Code | Description |
|---|---|
SERVICE_NOT_CONFIGURED | No telephony carrier or conversation engine is configured on this deployment |
DESTINATION_REQUIRED | The to input was missing or empty |
INSTRUCTIONS_REQUIRED | Neither agent_id nor prompt was supplied |
CONSENT_REQUIRED | record is enabled but no consent_script was provided |
ORIGINATE_FAILED | The carrier rejected the call (bad number, unverified caller id, no balance) |
PREPARE_FAILED | The 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..