Recipe: Post-discharge voice follow-up call
Goal: after a patient goes home, an automated assistant phones them, confirms who they are, asks a fixed set of recovery questions (pain, wound, fever, medication) and records the answers. If anything worries the patient or the assistant, a clinician callback task is created. If nobody answers, a retry task is created.
Before you start
| You need | Detail |
|---|---|
| Telephony set up by an operator | Voice runs through a carrier (Twilio is the only one implemented). It is configured by your Tietai operator with deployment settings, not in the application. If it is off, the Voice Workflows page cannot place calls. |
| A number you may call from | A caller ID in E.164 format (for example +34910000000) assigned to your organization. |
| An EU-resident voice engine for clinical calls | A call with the clinical profile is refused on an engine that processes outside the EU. |
| An organization-owned agent | A base-template agent will not run. Copy voice-clinical-followup into your organization first (Create an agent). |
| A FHIR server for the Tasks | In the ready-made definition the two Task nodes take their server and token from the placeholders {{FHIR_BASE_URL}} and {{FHIR_BEARER_TOKEN}}. Check that they resolve in your deployment, or no Task is written |
| Permissions | Apps → Voice Workflows appears only with the voice-screening permission. Editing the workflow in Studio needs workflow permissions. |
| The right to call this number | Nothing in the platform checks consent to be called. Only consent to record is enforced. Confirm the right to call before you place a call. |
Place a call with the ready-made workflow
The development environment has two ready-made workflows: Post-Discharge Voice Follow-Up and Wearables Wellness Check-In (they are saved pipelines, not part of every organization automatically; the list below shows only the pipelines of your organization that contain a voice-call node).
- Open Apps → Voice Workflows.
- Under Workflows (
Pipelines of your organisation that place a call), choose Post-Discharge Voice Follow-Up. If the list is empty, the page says "No workflow with a voice-call node yet. Build one in Studio and it appears here." - Fill in Call details. There is one field per input of the workflow, and required fields carry
*:
| Field | Example | Notes |
|---|---|---|
Patient name * | Test Patient A | Used in the greeting |
Patient id * | the FHIR Patient id | Links follow-up tasks to the patient. It is not placed in the prompt sent to the voice vendor |
Phone * | +34600000000 | E.164, with country code |
| Language | es-ES | Drives speech recognition and the voice. A wrong value gives a nonsense transcript |
| Discharge date | 2026-09-15 | Optional context |
- Choose Place call. The button is disabled until the required fields are filled.
In the Studio workflow list, the play button on a workflow card runs it with no inputs and dials the built-in demo defaults. Always use the Call details form on this page, or Run with inputs in Studio.
Follow the call
The centre card is titled Call to <number> and shows a status: Queued, Ringing, In progress, Completed, Transferred to a clinician, No answer, Busy, Rejected, Failed or Canceled. The Transcript tab shows the conversation as Assistant and Patient bubbles. Recent calls (right) lists your organization's calls; a triangle marks a call where the assistant asked for a clinician.
Review the outcome
Open the Outcome tab. It shows a warning if the assistant asked for a clinician, the answers Captured during the call, and What the workflow did next:
| What happened on the call | What the workflow does |
|---|---|
| The patient spoke and confirmed their identity | An agent drafts a clinical note from the transcript, shown as Draft clinical note with "Written by the workflow from the transcript. Review before it reaches the record." |
| An escalation was requested (chest pain, breathing difficulty, a bleeding or opening wound, a medication or "is this normal?" question, distress, a request for a person, contradictory answers) | A FHIR Task: priority urgent, code clinician-callback, linked to the patient. The assistant also transfers the call to your clinical team number |
| Nobody answered (no answer, busy, rejected, voicemail) | A FHIR Task: priority routine, code retry-call |
| Every call | An audit record (clinical_followup_call) with the outcome |
Read the tasks from your FHIR server with Task?patient=<patient id>.
Build or adapt your own
Follow the general method in Build any workflow. The voice-specific parts are below.
The nodes
| Node id | Type | Purpose |
|---|---|---|
pipeline-input | input | The form: phone, language, patient_id, patient_name, discharge_date. Required: phone, patient name, patient id |
call-patient | voice-call | Places the call and waits for it to end |
should-document then draft-note | condition, agent-run | When the call is documentable, draft a note |
needs-human, build-task, create-task | condition, transform, fhir-crud | When escalation_requested, create the urgent Task |
unreached, build-retry, create-retry | condition, transform, fhir-crud | When answered is false, create the retry Task |
audit-call | audit | Always record the call |
followup-result | output | Return the audit result and the drafted note |
Wire each condition to the node's declared ports (field, context). Keep the audit edge ungated so every call is recorded.
Settings of the voice-call node
| Setting (label) | Example | Meaning |
|---|---|---|
from (Caller ID) | {{CLINIC_CALLER_ID}} | Caller ID. It must belong to your organization |
profile (Risk Profile) | clinical | Applies the clinical safeguards (an EU engine is required) |
agent_id (Agent) | voice-clinical-followup | The organization-owned agent that conducts the call |
language (Language) | es-ES | A BCP-47 language code |
timezone (Time Zone) | Europe/Madrid | IANA zone of the person called. Decides the {{GREETING}} ("Buenos días", "Buenas tardes", "Buenas noches") in the opening line. Empty falls back to the deployment default, then to the dialled country if it has a single time zone; if the hour cannot be established the greeting names no time of day. Spain and Portugal cannot be resolved from the dial code (Canary Islands, Azores), so set it |
transfer_to (Transfer Destination) | {{CLINICAL_TEAM_NUMBER}} | Where an escalated call is transferred |
max_duration (Max Duration (seconds)) | 600 | Seconds |
machine_detection (Detect Answering Machine) | true | Default false. Report when the carrier believes voicemail answered, so it is recorded as no answer |
wait_for_completion (Wait For Completion) | true | Hold the workflow until the call ends |
record (Record Call) | false | Recording is off by default. Turning it on requires a consent_script |
first_message (Opening Line) | "Hello, this is the automated assistant of {{CLINIC_NAME}}, on behalf of your care team..." | The first sentence. The ready-made line says the caller is automated, and the agent's own instructions require that disclosure, so keep it in any line you write |
outcome_schema (Outcome Schema) | a JSON Schema | The answers you require |
Values in {{...}} such as {{CLINIC_CALLER_ID}}, {{CLINICAL_TEAM_NUMBER}} and {{CLINIC_NAME}} are filled by your deployment, or you can type the real value into the node.
Write the script
A call has four parts:
- The questions. The agent's question set: identity, a good time to talk, pain, wound, fever, medication, anything else. Start with an inline prompt on the node while you iterate and move it to the agent when it is stable.
- The required answers. The
outcome_schema. Define it first. Each field'sdescriptionis read by the model, so write it as an instruction. The ready-made version requiresidentity_confirmed,pain_controlled,wound_concernandtaking_medication. - Facts for this call. The
contextinput: short readable text about the patient, not a record dump. - The first sentence.
first_message.
To change a base-template agent you ship in voice-clinical-followup.yaml, raise its version: at boot a lower or equal version is skipped.
Choose how it starts
| Start | How |
|---|---|
| By hand | Apps → Voice Workflows → Place call |
| By API | Run the workflow with {"pipeline_id": "...", "inputs": {"phone": "...", ...}} (see the API reference) |
| On a timer | A scheduler node |
| On a FHIR event | An fhir-webhook node |
The ready-made workflow starts from its input form. A timer (a scheduler node, which Schedule in the Run menu adds for you) runs a workflow without inputs, and a run without inputs dials the input node's demo defaults. No shipped workflow fires when a patient is discharged or maps a patient's phone number from a FHIR event into the call. If you build one, test it carefully and keep a person in the loop.
Test it on yourself
- Put your own number in the form, with the right language.
- Place the call and answer. Check that the greeting says it is automated and that it asks for your identity first.
- Say "I have chest pain" and check that the call escalates and an urgent Task appears.
- Place another call and do not answer. Check that a
retry-callTask appears. - Do not count on Dry run to avoid dialling: in the Builder it saves and runs exactly like Run (it follows the Live/Test toggle). Test the wiring with your own number.
Safety rules the assistant follows
- It collects and escalates only. It does not interpret symptoms, advise or state urgency.
- Identity first. Nothing clinical is said until the person confirms who they are. A stranger receives no information. A voicemail says only the clinic name and asks for a call back.
- Anything uncertain escalates: contradictory answers, distress, or anything outside the question list.
- A person reviews the drafted note and works the Task queue.
- It reads the transcript, not the audio, so breathlessness, slurring or crying can be missed, and "I'm fine" can mask distress. Broad escalation is the mitigation.
Privacy: the patient id is not placed in the prompt sent to the voice vendor, and tools run inside Tietai with tenant isolation, the PHI guard and audit. Recordings are off by default and expire (30 days unless the deployment sets otherwise). Transcripts are kept indefinitely unless the deployment sets a transcript retention period; both settings belong to the operator.
What is not built
| Gap | Consequence |
|---|---|
| No calling window | A call can be placed at any hour, including at night |
| No automatic re-dial | retry-call Tasks accumulate and nothing consumes them. Someone must work the queue |
| No consent or do-not-call check | You must verify the right to call each number |
| No owner on the tasks | Decide who monitors clinician-callback and retry-call |
| No per-organization voice settings | Numbers and engine settings are deployment-wide |
| No inbound calls | The platform places calls; it does not answer them |
When something goes wrong
| Symptom | Cause | Fix |
|---|---|---|
voice call service is not configured on this deployment | Telephony is not enabled | Ask your operator to configure the carrier and the public base URL |
to (or phone) input is required | The workflow ran with no inputs | Use the Call details form or Run with inputs |
| The run stays waiting after the call ended | The carrier's call-end notice did not arrive, or its signature did not match | Open the run in Monitor and read the recorded error; ask your operator to check the public URL |
engine ... processes in us and cannot carry a clinical call | The clinical profile is on a non-EU engine | Your operator must configure the EU engine |
caller id ... belongs to another organization | The from number is not yours | Use a number assigned to your organization |
| A nonsense transcript | Wrong language | Set the patient's language code |
A gate fails with field 'documentable' not found in inputs | A condition is wired to an undeclared port | Wire it to the declared field or context port |
Something unclear? Send documentation feedback by email.