When a customer calls your business, you have less than a second to decide how to handle them. Are they a known customer? A first-time caller? Or a potential fraud risk? Most systems punt on this question entirely -- the caller gets a generic IVR, punches through a menu tree, and eventually reaches an agent who asks them to verify their identity from scratch.
This walkthrough builds something different: a caller identity pipeline that runs a Number Lookup before the call is even answered, scores the caller's trust level, and passes the result to an AI Assistant that adapts its behaviour in real time. Trusted callers get greeted by name with full account access. Suspicious callers get a formal security flow. One codebase, one API key, four Telnyx products.
Full source: phone-identity-voice-agent-nodejs
What Does It Do
An inbound call arrives. The server immediately fires a Number Lookup request to the Telnyx API, pulling carrier data, CNAM (caller name), line type, porting history, and -- when available -- caller identity with a confidence score. A trust engine scores the result from 0 to 100, then classifies the caller as verified, standard, or suspicious.
That classification drives three things: the AI greeting, the security posture, and the account access level. All of this happens in the ~500 ms between when the phone rings and when the AI speaks its first word.
Inbound Call
|
v
+-------------------+ +------------------+ +------------------+
| Call Control | --> | Number Lookup | --> | Risk Engine |
| (answer webhook) | | (carrier, CNAM, | | (score 0-100, |
| | | identity, port) | | trust level) |
+-------------------+ +------------------+ +------------------+
|
v
+------------------+
| AI Assistant |
| (dynamic vars: |
| greeting, mode, |
| account access) |
+------------------+
Telnyx Products Used
| Product | Role | API Endpoint |
|---|---|---|
| Number Lookup | Carrier, CNAM, caller identity, porting status | GET /v2/number_lookup/{phone} |
| Call Control | Answer, hang up, manage call flow via webhooks | POST /v2/calls/{id}/actions/{action} |
| AI Assistants | Voice agent with template variables filled per call | POST /v2/calls/{id}/actions/ai_assistant_start |
| Voice API | Inbound call routing to your webhook endpoint | Portal: Call Control Application |
One API key authenticates all four products.
Prerequisites
- Node.js 22+
- A Telnyx account with an API key
- A Telnyx phone number with voice capability
- A Call Control Application (webhook URL pointed at your server)
- An AI Assistant configured with template variables
Step 1: Clone and Install
git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/phone-identity-voice-agent-nodejs
npm install
cp .env.example .env
Step 2: Configure the Environment
Edit .env with your Telnyx credentials:
TELNYX_API_KEY=KEYxxxxxxxxxxxxxxxx
TELNYX_PHONE_NUMBER=+1xxxxxxxxxx
TELNYX_ASSISTANT_ID=assistant-xxxxxxxx
TELNYX_PUBLIC_KEY=xxxxx (optional, for webhook signature verification)
| Variable | Source |
|---|---|
TELNYX_API_KEY | Portal > API Keys |
TELNYX_PHONE_NUMBER | Portal > Numbers > Buy a Number |
TELNYX_ASSISTANT_ID | Portal > AI Assistants > Create |
TELNYX_PUBLIC_KEY | Portal > API Keys > Public Key |
The AI Assistant needs three template variables in its instructions: {{caller_context}}, {{behavior_instructions}}, and {{greeting_text}}. These get filled dynamically on every call based on the Number Lookup result.
Step 3: The Number Lookup and Risk Engine
The core of the system lives in lookup.js. When a call arrives, the server calls the Number Lookup API with three data types:
const url = `${API}/number_lookup/${encodeURIComponent(phone)}?type=carrier&type=caller-name&type=caller-identity`;
The response includes carrier name and type, CNAM (registered caller name), caller identity with a confidence score, porting status, and postal address when available.
The risk engine starts at 100 and deducts points for red flags:
| Signal | Deduction | Example |
|---|---|---|
| No identity data | -40 | No caller identity record |
| Low confidence (< 60) | -40 | Identity score below threshold |
| No caller name | -15 | No CNAM registered |
| VoIP line type | -20 | Non-fixed VoIP number |
| Ported number | -10 | Number recently transferred |
| No address on file | -10 | No postal address |
The final score maps to a trust level: verified (70+), standard (40-69), or suspicious (below 40).
Step 4: Dynamic AI Behaviour
The trust level drives the AI Assistant's behaviour through dynamic variables:
Verified caller (score 70+): The AI greets the caller by first name -- "Hi, am I speaking with Sarah?" -- skips verification entirely, and grants full account access. The caller_context variable tells the AI who the caller is; the behavior_instructions variable tells it to be warm and conversational.
Standard caller (score 40-69): The AI gives a neutral greeting and asks the caller to verify through their banking app before accessing account details.
Suspicious caller (score below 40): The AI uses a formal greeting, requires full identity verification (name, date of birth, account number), and blocks sensitive operations like wire transfers and card freezes.
const aiBody = {
assistant: {
id: assistantId,
dynamic_variables: {
caller_context: vars.callerContext,
behavior_instructions: vars.behaviorInstructions,
greeting_text: vars.greetingText,
},
},
};
await fetch(`${API}/calls/${ccid}/actions/ai_assistant_start`, {
method: "POST",
headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
body: JSON.stringify(aiBody),
});
Step 5: Run and Test
node server.js
Expose your local server with ngrok:
ngrok http 3000
Update your Call Control Application webhook URL in the Telnyx portal to https://YOUR-NGROK.ngrok.app/webhooks/call-events, then call your Telnyx number. The dashboard at http://localhost:3000 shows the identity card, trust score, risk signals, and live transcription in real time.
You can also test the Number Lookup independently:
curl http://localhost:3000/lookup/+15125551234
Production Considerations
- Webhook signature verification is built in -- set
TELNYX_PUBLIC_KEYto enable Ed25519 signature checks on every incoming webhook. - 24-hour lookup cache prevents redundant API calls for repeat callers. The cache is in-memory with automatic eviction at 500 entries.
- Edge deployment is supported -- the app includes Telnyx Edge Compute scripts for deploying to the carrier edge with sub-10ms webhook latency.
- Graceful degradation -- if Number Lookup fails, the system falls back to standard verification mode rather than blocking the call.
The Same Pattern Drives More Than Banking
The identity-first call flow is a template. Swap the bank account data for:
- Healthcare -- verify patient identity before sharing test results
- Insurance -- pre-populate claim details for known policyholders
- E-commerce -- skip order verification for recognised phone numbers
- Property management -- route tenants directly to their building's maintenance team
The trust scoring logic and dynamic variable injection work the same way regardless of the vertical.
Related Examples
- phone-number-lookup-python -- Basic Number Lookup integration
- route-phone-calls-to-ai-agent-python -- AI agent call routing
- warm-transfer-nodejs -- Warm call transfer
- ai-voice-agent-with-function-calling-python -- Voice AI with function calling
- conversation-relay-voice-bot-python -- Conversation relay bot
- number-reputation-remediation-nodejs -- Number reputation management