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.
Quelque chose n'est pas clair ? Envoyez vos commentaires sur la documentation par courriel.