telnyx-code-examples/build-conversational-workflow-nodejs at main · team-telnyx/telnyx-code-examples

name	build-conversational-workflow
title	Build a Conversational Workflow
description	Build a Telnyx Conversational Workflow for inbound auto insurance claim intake with structured branches, backend tools, and priority follow-up.
language	nodejs
framework	express
telnyx_products	Voice AI
channel	voice

Build a Telnyx Conversational Workflow for inbound auto insurance first notice of loss intake. The workflow asks structured questions, branches for urgent cases, calls backend tools, and returns a claim or fallback reference to the caller.

Telnyx API Endpoints Used

This example is configured in the Telnyx Portal as a Conversational Workflow. The local Express app exposes webhook tool endpoints that Telnyx calls from workflow tool nodes:

Create Claim Intake Tool: POST /tools/create-claim-intake
Log Fallback Tool: POST /tools/log-claim-intake-fallback
Flag Priority Follow-Up Tool: POST /tools/flag-priority-follow-up

Architecture

  Inbound PSTN call
        │
        ▼
  ┌────────────────────────────┐
  │ Telnyx Conversational       │
  │ Workflow                    │
  └─────────────┬──────────────┘
                │ nodes + branches
                ▼
  ┌────────────────────────────┐
  │ Auto claim intake flow      │
  │ safety, caller, loss fields │
  └─────────────┬──────────────┘
                │ workflow tool calls
                ▼
  ┌────────────────────────────┐
  │ Express tool server         │
  │ /tools/create-claim-intake  │
  └─────────────┬──────────────┘
                │ JSON result
                ▼
     claim reference or fallback reference

Workflow lifecycle

Caller reaches the Telnyx phone number assigned to the workflow.
The workflow confirms this is a new auto claim.
The workflow checks for injury, danger, or unsafe vehicle status.
The workflow collects caller, policy, vehicle, and incident details.
The workflow calls create_claim_intake when required fields are present.
The workflow calls log_claim_intake_fallback when the intake cannot be completed.
The workflow calls flag_priority_follow_up when priority_flag is true.

Why Telnyx

Telnyx is an AI Communications Infrastructure platform that puts voice, AI, SIP, messaging, and programmable communications on one private, global network. Conversational Workflows let you build structured voice experiences with visible branches and tool calls, so operational processes like insurance claim intake are easier to audit than a single large prompt.

Why This Example Uses Insurance

Insurance first notice of loss is a useful workflow pattern because it has realistic business constraints:

the caller may be stressed
the workflow must collect specific fields
urgent cases need early branching
backend records should only be created after required information is present
the voice experience must not promise coverage, payment, repairs, liability, legal advice, or medical advice

The same structure can be reused for scheduling, support triage, lead qualification, patient intake, and service dispatch.

Environment Variables

Copy .env.example to .env and fill in:

Variable	Type	Example	Required	Description	Where to get it
`TELNYX_API_KEY`	`string`	`KEY_your_telnyx_api_key_here`	no	Telnyx API key for Portal/API automation; the local mock tool server does not call Telnyx directly	Portal
`CLAIM_TOOL_SECRET`	`string`	`dev-secret`	yes	Shared secret expected in the `x-tool-secret` header from Telnyx workflow tools	Choose your own value
`PORT`	`number`	`8787`	no	Port the Express tool server listens on	-

Setup

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/build-conversational-workflow-nodejs
cp .env.example .env    # fill in CLAIM_TOOL_SECRET
npm install
npm test
node server.js          # starts on http://localhost:8787

Workflow Configuration

Expose your local server:
In the Telnyx Portal, create a Conversational Workflow named auto claim intake conversational workflow.
Build the nodes and branches from GUIDE.md.
Configure tool nodes with your ngrok base URL:
- POST https://<id>.ngrok.io/tools/create-claim-intake
- POST https://<id>.ngrok.io/tools/log-claim-intake-fallback
- POST https://<id>.ngrok.io/tools/flag-priority-follow-up
Add the shared header to each tool:
```
x-tool-secret: dev-secret
```
Assign an inbound Telnyx phone number to the workflow and call it.

API Reference

`POST /tools/create-claim-intake`

Creates a mock claim intake when the workflow has collected required fields.

curl -X POST http://localhost:8787/tools/create-claim-intake \
  -H "content-type: application/json" \
  -H "x-tool-secret: dev-secret" \
  -d '{
    "caller_name": "jane sample",
    "caller_phone": "+15551234567",
    "loss_type": "auto",
    "loss_date": "2026-06-15",
    "loss_location": "mission street and 5th street, san francisco",
    "loss_description": "rear-ended while stopped",
    "priority_flag": false,
    "consent_to_continue": true
  }'

Response:

{
  "success": true,
  "claim_intake_id": "aci_123",
  "priority_flag": false,
  "next_step": "claims team follow-up"
}

`POST /tools/log-claim-intake-fallback`

Records a fallback when the caller is misdirected, information is incomplete, or the primary tool cannot be used.

`POST /tools/flag-priority-follow-up`

Creates a mock priority follow-up task for urgent cases.

`GET /health`

Health check endpoint for monitoring.

curl http://localhost:8787/health