Fraud Alert Verification Agent

Call customers automatically when a transaction is flagged, walk through a verification flow, and escalate to a human or block the card if verification fails.

DifficultyAdvanced

TrackDeveloper Track

ChannelsVoice (Outbound)

IntegrationsTransaction monitoring system (API)Customer contact databaseEscalation email

What you'll build

An agent that receives a flagged transaction from your transaction monitoring system, places an outbound call to the customer, walks through a structured verification flow, and — depending on the outcome — marks the transaction safe or escalates to a human fraud analyst and instructs the customer to block their card. A pattern like this can handle hundreds of outbound fraud calls per day with no human in the loop for verified transactions.

Customer journey

When your transaction monitoring system flags a suspicious charge, your backend triggers the agent to call the cardholder. The agent walks through a verification script, marks the transaction safe if the customer confirms it, or escalates to a fraud analyst and instructs a card block if verification fails.

Loading diagram…

See Deploying and testing channels for connect and test steps per channel.

Prerequisites

BimpeAI account with an API key (sk_…)
Read Anatomy of a workflow agent first — this recipe skips steps covered there
A transaction monitoring system and customer contact database connected in the Console dashboard (see Step 4)
An outbound voice phone number configured in the Console dashboard (see Step 4)
Escalation email configured under Settings → Agent (the Escalation Email field) in the Console dashboard

Steps

1. Find or create the workflow

import { BimpeAI } from "@bimpeai/sdk";

const bimpe = new BimpeAI({ apiKey: process.env.BIMPEAI_API_KEY! });

const page = await bimpe.workflows.list({ scope: "public", search: "fraud verification" });
const workflow = page.data[0];
console.log(workflow.id, workflow.name);

import os
from bimpeai import BimpeAI

client = BimpeAI(api_key=os.environ["BIMPEAI_API_KEY"])

page = client.workflows.list(scope="public", search="fraud verification")
workflow = page.data[0]
print(workflow.id, workflow.name)

Or build a new workflow from scratch with workflows.create instead of finding one. name and system_prompt are required; it returns the new Workflow whose id you bind the agent to. See Anatomy of a workflow agent for the full set of optional fields like rules and flows.

const workflow = await bimpe.workflows.create({
  name: "Fraud alert verification agent",
  system_prompt: "You call cardholders when a transaction is flagged, walk through a structured verification flow, and escalate to a human fraud analyst or instruct the customer to block their card when verification fails.",
});
console.log(workflow.id);

workflow = client.workflows.create(
    name="Fraud alert verification agent",
    system_prompt="You call cardholders when a transaction is flagged, walk through a structured verification flow, and escalate to a human fraud analyst or instruct the customer to block their card when verification fails.",
)
print(workflow.id)

2. Create the agent

const agent = await bimpe.agents.create(
  {
    name: "Fraud alert verification agent",
    description: "Calls cardholders to verify flagged transactions and escalates failed checks.",
    workflow_id: workflow.id,
  },
  { idempotencyKey: "create-fraud-alert-agent-v1" },
);

console.log(agent.id);

agent = client.agents.create(
    name="Fraud alert verification agent",
    description="Calls cardholders to verify flagged transactions and escalates failed checks.",
    workflow_id=workflow.id,
    idempotency_key="create-fraud-alert-agent-v1",
)

print(agent.id)

3. Add knowledge bases (optional)

Knowledge bases are optional; an agent whose workflow and integrations already cover everything it needs to say can skip this step. This recipe uses one to ground the agent in the details it must quote accurately.

The fraud response policy gives the agent consistent verification questions and block instructions regardless of the transaction type.

// Fraud response policy
await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Fraud response policy",
  content:
    "A transaction is flagged when it exceeds 3× the customer's 30-day average spend, " +
    "originates from a new country, or matches a known fraud merchant pattern.\n" +
    "Verification questions to ask in order:\n" +
    "1. Did you make a purchase of [amount] at [merchant] on [date]?\n" +
    "2. Were you in [location] at that time?\n" +
    "3. Is your card still in your possession?\n" +
    "If the customer says no to question 1 or 2, or yes to losing the card:\n" +
    "- Advise them to block the card immediately in their banking app.\n" +
    "- Tell them a fraud analyst will call back within 60 minutes.\n" +
    "- Do not attempt to block the card yourself — this is handled by the card management team.",
});

// Block instructions
await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Card block instructions",
  content:
    "To block a card via banking app: open the app → Cards → select the card → Freeze card.\n" +
    "To block via telephone banking: call the number on the back of the card.\n" +
    "A temporary freeze stops new transactions but does not cancel the card.\n" +
    "A permanent block requires a replacement card to be issued (5–7 business days).",
});

# Fraud response policy
client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Fraud response policy",
    "content": (
        "A transaction is flagged when it exceeds 3× the customer's 30-day average spend, "
        "originates from a new country, or matches a known fraud merchant pattern.\n"
        "Verification questions to ask in order:\n"
        "1. Did you make a purchase of [amount] at [merchant] on [date]?\n"
        "2. Were you in [location] at that time?\n"
        "3. Is your card still in your possession?\n"
        "If the customer says no to question 1 or 2, or yes to losing the card:\n"
        "- Advise them to block the card immediately in their banking app.\n"
        "- Tell them a fraud analyst will call back within 60 minutes.\n"
        "- Do not attempt to block the card yourself — this is handled by the card management team."
    ),
})

# Block instructions
client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Card block instructions",
    "content": (
        "To block a card via banking app: open the app → Cards → select the card → Freeze card.\n"
        "To block via telephone banking: call the number on the back of the card.\n"
        "A temporary freeze stops new transactions but does not cancel the card.\n"
        "A permanent block requires a replacement card to be issued (5–7 business days)."
    ),
})

4. Connect channels and integrations (dashboard)

Telephony and integrations are connected in the dashboard

The API cannot create channel connections, but integrations can now be configured through it; see Configuring integrations. Connect telephony on the Deploy screen and your transaction monitoring system and customer contact database on the Integrations screen of the Console dashboard. The SDK lists what is active but cannot modify channel connections. Telephony conversations use the telephony channel value and are filterable through the SDK. The SDK can place outbound calls with bimpe.calls.make(agentId, { destination, is_test_call }) — is_test_call: true uses BimpeAI test telephony, while is_test_call: false requires a live telephony channel configured in the Console.

In the Console dashboard, pick your agent from the switcher at the top, then open Deploy.
Under Voice, click Set up on the Telephony card — it is an add-on with usage-based pricing. Provision or link a number under Team settings → Phone numbers, then set the agent's voice and greeting under Settings → Voice.
On the Integrations screen, open the Custom API tab and wire up your transaction monitoring system (see Configuring integrations) so the agent receives flagged transaction details at call time.
In the same Custom API tab, wire up your customer contact database so the agent can look up the customer's phone number from a transaction ID.
Under Settings → Agent, set the Escalation Email for the fraud analyst team.

Connect Telephony (outbound)

Your system calls customers for reminders, alerts, or follow-ups.

Open Deploy and click Set up on the Telephony card.
Under Team settings → Phone numbers, request or link an outbound-capable number and assign it to this agent.
Under Settings → Voice, set the outbound voice and greeting.
Place calls with calls.make and is_test_call: false, or trigger calls from your backend when events fire.

Full reference: Deploying and testing channels.

5. Test your agent

Before going live, place a test call — is_test_call: true uses BimpeAI test telephony and consumes no live minutes. Fetch the test code first to confirm telephony is enabled.

Test Telephony (outbound)

Test call: use calls.make(agentId, { destination, is_test_call: true }) — test telephony consumes no live minutes.

Confirm channels.telephony.is_enabled from getTestCode before placing live calls.

Full reference: Deploying and testing channels.

const { channels } = await bimpe.agents.getTestCode(agent.id);
console.log("Telephony enabled:", channels.telephony.is_enabled);

const call = await bimpe.calls.make(agent.id, {
  destination: "<tester-phone>",
  is_test_call: true,
});
console.log("Test call:", call.status);

test_code = client.agents.get_test_code(agent.id)
print("Telephony enabled:", test_code.channels.telephony.is_enabled)

call = client.calls.make(agent.id, {"destination": "<tester-phone>", "is_test_call": True})
print("Test call:", call.status)

See Test your agent for the other test channels and the pause-AI rule.

6. Verify and go live

const integrations = await bimpe.agents.integrations.list(agent.id);
console.log("Integrations:", integrations.map((i) => i.name));

integrations = client.agents.integrations.list(agent.id)
print("Integrations:", [i.name for i in integrations])

Both integrations must appear before enabling the agent for live fraud alerts. A missing transaction monitoring connection means the agent will have no transaction context when the call connects.

Full example

import { BimpeAI } from "@bimpeai/sdk";

const bimpe = new BimpeAI({ apiKey: process.env.BIMPEAI_API_KEY! });

// 1. Find workflow
const page = await bimpe.workflows.list({ scope: "public", search: "fraud verification" });
const workflow = page.data[0];

// 2. Create agent
const agent = await bimpe.agents.create(
  {
    name: "Fraud alert verification agent",
    description: "Calls cardholders to verify flagged transactions and escalates failed checks.",
    workflow_id: workflow.id,
  },
  { idempotencyKey: "create-fraud-alert-agent-v1" },
);

// 3. Add knowledge bases
await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Fraud response policy",
  content:
    "Verification questions:\n" +
    "1. Did you make a purchase of [amount] at [merchant] on [date]?\n" +
    "2. Were you in [location] at that time?\n" +
    "3. Is your card still in your possession?\n" +
    "If denied: advise card block and escalate to fraud analyst.",
});

await bimpe.agents.knowledgeBases.create(agent.id, {
  type: "text",
  name: "Card block instructions",
  content:
    "Block via banking app: Cards → select card → Freeze card.\n" +
    "Block via telephone banking: call the number on the back of the card.",
});

// 4. Verify integrations (transaction monitoring + contact DB must be connected in dashboard)
const integrations = await bimpe.agents.integrations.list(agent.id);
console.log("Agent ID:", agent.id);
console.log("Integrations:", integrations.map((i) => i.name));

// Place an outbound verification call. is_test_call: true uses BimpeAI test telephony;
// false requires a live telephony channel configured in the dashboard. Calls can also be
// triggered from the dashboard or a transaction-monitoring webhook.
const call = await bimpe.calls.make(agent.id, {
  destination: "+447700900123",
  is_test_call: true,
});
console.log("Call started:", call.call_id);

// After a call completes, read its log via calls.retrieve; it also appears in conversations.list
// (filterable by channel: "telephony").
const conversations = await bimpe.conversations.list(agent.id, { channel: "telephony" });
console.log("Recent telephony conversations:", conversations.data.length);

import os
from bimpeai import BimpeAI

client = BimpeAI(api_key=os.environ["BIMPEAI_API_KEY"])

# 1. Find workflow
page = client.workflows.list(scope="public", search="fraud verification")
workflow = page.data[0]

# 2. Create agent
agent = client.agents.create(
    name="Fraud alert verification agent",
    description="Calls cardholders to verify flagged transactions and escalates failed checks.",
    workflow_id=workflow.id,
    idempotency_key="create-fraud-alert-agent-v1",
)

# 3. Add knowledge bases
client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Fraud response policy",
    "content": (
        "Verification questions:\n"
        "1. Did you make a purchase of [amount] at [merchant] on [date]?\n"
        "2. Were you in [location] at that time?\n"
        "3. Is your card still in your possession?\n"
        "If denied: advise card block and escalate to fraud analyst."
    ),
})

client.agents.knowledge_bases.create(agent.id, {
    "type": "text",
    "name": "Card block instructions",
    "content": (
        "Block via banking app: Cards → select card → Freeze card.\n"
        "Block via telephone banking: call the number on the back of the card."
    ),
})

# 4. Verify integrations (transaction monitoring + contact DB must be connected in dashboard)
integrations = client.agents.integrations.list(agent.id)
print("Agent ID:", agent.id)
print("Integrations:", [i.name for i in integrations])

# Place an outbound verification call. is_test_call=True uses BimpeAI test telephony;
# False requires a live telephony channel configured in the dashboard. Calls can also be
# triggered from the dashboard or a transaction-monitoring webhook.
call = client.calls.make(agent.id, {"destination": "+447700900123", "is_test_call": True})
print("Call started:", call.call_id)

# After a call completes, read its log via calls.retrieve; it also appears in conversations.list
# (filterable by channel="telephony").
conversations = client.conversations.list(agent.id, channel="telephony")
print("Recent telephony conversations:", len(conversations.data))

Deploy and go live

Go-live checklist

Store your API key in BIMPEAI_API_KEY (server-side only).
Confirm Transaction monitoring system appears in integrations.list or is connected in the dashboard.
Confirm Customer contact database appears in integrations.list or is connected in the dashboard.
Verify Telephony (outbound) is connected on the Deploy screen (agents.channels.list shows it enabled).
Set Escalation Email under Settings → Agent if humans must take over.
Switch the agent to live with updateLiveStatus / update_live_status.
Monitor the Conversations screen (or stream via SDK) after launch.
Set Escalation Email for the fraud analyst team under Settings → Agent.

After go-live

Update the fraud response policy knowledge base when new fraud patterns emerge. Trigger calls from your monitoring webhook with calls.make and is_test_call: false once telephony is live.

Variations

Add a third knowledge base entry listing high-risk merchant categories so the agent can provide more specific context during the call.
Set the agent's language with agents.update — the agent will conduct the verification call in that language.
Send a follow-up WhatsApp message after the call via conversations.send (create-or-send by channel_type + channel_user_id) with a summary of the outcome and next steps.

Fraud Alert Verification Agent

On this page