Look up the caller and branch inside the call flow

Voicedata-driven call routing (CRM lookup)

Have the call itself fetch the caller's record from your API, branch on a field of the reply, and still reach a human when the lookup fails.

Also called CRM lookup during a call, screen pop routing, route by customer tier, database-driven IVR

swmlcall-fabricserverless

The claim

Routing on data usually means a server of yours in the call path: SignalWire fetches a document from you, you call your database, you answer. The request method removes that hop. The hosted document calls your API itself, and the next verb reads the answer.

Why it holds

Three parts. request sends the caller’s number to your endpoint and, with save_variables true, parses the JSON reply into variables. switch then branches on request_response.tier, one of those parsed fields. Around both, a cond checks request_result, so a CRM that is slow or down sends the call to the main line instead of dropping it.

How it works

service.add_verb("request", {
    "url": CRM_URL, "method": "POST",
    "headers": {"Content-Type": "application/json",
                "Authorization": f"Bearer {CRM_TOKEN}"},
    "body": {"phone": "%{call.from}"},
    "save_variables": True,          # parse the reply into request_response.*
    "connect_timeout": 3, "timeout": 5,
})

main = service.get_document()["sections"]["main"]
main.append({"cond": [
    {"when": "request_result == 'success'",
     "then": [{"switch": {"variable": "request_response.tier",
                          "case": {"gold": [gold_leg], "standard": [standard_leg]},
                          "default": [standard_leg]}}]},
    {"else": [{"play": {"url": f"say:{APOLOGY}"}}, standard_leg]},
]})

The request reference describes save_variables as “Store parsed JSON response as variables” and gives request_result as “Either success or failed”. It references a saved field as ${request_response.<field>}. switch.variable takes the name on its own, the way the IVR recipes pass prompt_value.

Two defaults are worth changing. timeout and connect_timeout are both 0, meaning no timeout, so a hung CRM would hold the call open. This document sets five and three seconds and then handles the failure.

cond takes an array, and add_verb takes a dictionary, so add_verb("cond", [...]) returns False and adds nothing. The array is appended to the document instead. get_document() hands back the live document, so the hangup added after it still lands last. Every other verb goes through add_verb, which validates it against the bundled schema as it is added.

The whole document is hosted as a Call Flow, the same relayml and flow_data pair build-an-ivr-without-a-server uses, so nothing of yours is in the call.

Limitations

The verifier proves the document and the requests. Whether the platform substitutes %{call.from} into the body and resolves request_response.tier at runtime is live behaviour, described in the request reference and not asserted here.

Your endpoint is in the call path even though your call server is not. Its latency is the caller’s silence, which is what the two timeouts bound.

The record is fetched once, at the start. A branch that needs fresh data later in the call makes a second request; each one overwrites request_response.

What to change first

Delete save_variables and run the verifier. The document still validates, because the field is optional, and the assertion fails. On a real call the switch would find no request_response.tier and take its default, so every caller reaches the main line and nothing errors.

Where this sits

Before this

Build an IVR without a server

Route calls by dialed number or time Dial destinations in order or all at once, with a failure path Host a TwiML bin without a server

python/app.py

"""Look up the caller and branch inside the call flow.

The call fetches the caller's record itself. `request` with `save_variables`
true parses your API's JSON into `request_response.<field>`; `switch` then
branches on one of those fields, and a `cond` around it sends the call to a
human when the lookup fails. The document is hosted as a Call Flow, so no
server of yours is in the call path.

Written against signalwire-sdk 3.0.1 (SWMLService, RestClient.fabric).

    python app.py deploy
    python app.py point <resource_id> +15551230000
"""
import os
import sys

from dotenv import load_dotenv
from signalwire import SWMLService
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

# reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE from the env
client = RestClient()

# your system of record: the endpoint the call asks about the caller
CRM_URL = os.getenv("CRM_URL", "https://crm.example.com/lookup")
CRM_TOKEN = os.getenv("CRM_TOKEN", "replace-me")

# where each tier lands. An unknown tier is treated as standard.
DESKS = {"gold": os.getenv("GOLD_NUMBER", "+15550100001"),
         "standard": os.getenv("STANDARD_NUMBER", "+15550100002")}
APOLOGY = "One moment, I could not look up your account."

# The spec pairs relayml with flow_data: provide both or omit both.
FLOW_DATA = {"generated_by": "signalwire-recipes",
             "recipe": "look-up-the-caller-and-branch-inside-the-call-flow"}


def build(service=None):
    """The routing document, each verb validated as it is added."""
    service = service or SWMLService(name="crm-router", route="/router")
    service.reset_document()
    service.add_verb("answer", {})
    # %{call.from} is substituted at runtime; the schema accepts ${...} too
    service.add_verb("request", {
        "url": CRM_URL,
        "method": "POST",
        "headers": {"Content-Type": "application/json",
                    "Authorization": f"Bearer {CRM_TOKEN}"},
        "body": {"phone": "%{call.from}"},
        # without this the response is not parsed into request_response.<field>
        "save_variables": True,
        "connect_timeout": 3,
        "timeout": 5,
    })
    # cond takes an array and add_verb takes a dict, so this one is appended.
    # get_document() hands back the live document, so order is preserved.
    main = service.get_document()["sections"]["main"]
    main.append({"cond": [
        {"when": "request_result == 'success'",
         "then": [{"switch": {
             "variable": "request_response.tier",
             "case": {tier: [{"connect": {"to": number, "timeout": 25}}]
                      for tier, number in DESKS.items()},
             # a record with a tier you do not know is still a customer
             "default": [{"connect": {"to": DESKS["standard"], "timeout": 25}}],
         }}]},
        # the lookup failed or timed out: reach a human anyway
        {"else": [{"play": {"url": f"say:{APOLOGY}"}},
                  {"connect": {"to": DESKS["standard"], "timeout": 25}}]},
    ]})
    service.add_verb("hangup", {})
    return service


def deploy(title="Ridgeline Cycles router"):
    """Host the document as a Call Flow. Returns the resource."""
    return client.fabric.call_flows.create(
        title=title, relayml=build().get_document(), flow_data=FLOW_DATA)


def number_id(e164):
    """`filter_number` is a contains match, so compare the number exactly."""
    for item in client.phone_numbers.list(filter_number=e164).get("data", []):
        if item.get("number") == e164:
            return item["id"]
    raise LookupError(f"{e164} is not a number on this project")


def point_number(resource_id, e164):
    """Route inbound calls on the number to the hosted flow."""
    return client.fabric.resources.assign_phone_route(
        resource_id, phone_route_id=number_id(e164), handler="calling")


if __name__ == "__main__":
    args = sys.argv[1:]
    if args[:1] == ["deploy"]:
        flow = deploy()
        print(flow["id"])
    elif len(args) == 3 and args[0] == "point":
        print(point_number(args[1], args[2]))
    else:
        print("usage: python app.py deploy | python app.py point <resource_id> <e164>")

/**
 * Look up the caller and branch inside the call flow.
 *
 * The call fetches the caller's record itself. `request` with `save_variables`
 * true parses your API's JSON into `request_response.<field>`; `switch` then
 * branches on one of those fields, and a `cond` around it sends the call to a
 * human when the lookup fails. The document is hosted as a Call Flow, so no
 * server of yours is in the call path.
 *
 * Written against @signalwire/sdk 2.0.5 (SWMLService, RestClient.fabric).
 *
 *     npm start deploy
 *     npm start point <resource_id> +15551230000
 */
import "dotenv/config";
import { RestClient, SWMLService } from "@signalwire/sdk";

// reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE
export const client = new RestClient();

// your system of record: the endpoint the call asks about the caller
export const CRM_URL = process.env["CRM_URL"] ?? "https://crm.example.com/lookup";
const CRM_TOKEN = process.env["CRM_TOKEN"] ?? "replace-me";

// where each tier lands. An unknown tier is treated as standard.
export const DESKS: Record<string, string> = {
  gold: process.env["GOLD_NUMBER"] ?? "+15550100001",
  standard: process.env["STANDARD_NUMBER"] ?? "+15550100002",
};
export const APOLOGY = "One moment, I could not look up your account.";

// The spec pairs relayml with flow_data: provide both or omit both.
export const FLOW_DATA = {
  generated_by: "signalwire-recipes",
  recipe: "look-up-the-caller-and-branch-inside-the-call-flow",
};

type Json = Record<string, unknown>;

/** The routing document, each verb validated as it is added. */
export function build() {
  const service = new SWMLService({ name: "crm-router", route: "/router" });
  service.resetDocument();
  service.addVerb("answer", {});
  // %{call.from} is substituted at runtime; the schema accepts ${...} too
  service.addVerb("request", {
    url: CRM_URL,
    method: "POST",
    headers: { "Content-Type": "application/json",
               Authorization: `Bearer ${CRM_TOKEN}` },
    body: { phone: "%{call.from}" },
    // without this the response is not parsed into request_response.<field>
    save_variables: true,
    connect_timeout: 3,
    timeout: 5,
  });
  // cond takes an array; it is appended so both surfaces build it the same way
  const document = service.getDocument() as { sections: { main: Json[] } };
  const cases: Json = {};
  for (const [tier, number] of Object.entries(DESKS)) {
    cases[tier] = [{ connect: { to: number, timeout: 25 } }];
  }
  document.sections.main.push({ cond: [
    { when: "request_result == 'success'",
      then: [{ switch: {
        variable: "request_response.tier",
        case: cases,
        // a record with a tier you do not know is still a customer
        default: [{ connect: { to: DESKS["standard"], timeout: 25 } }],
      } }] },
    // the lookup failed or timed out: reach a human anyway
    { else: [{ play: { url: `say:${APOLOGY}` } },
             { connect: { to: DESKS["standard"], timeout: 25 } }] },
  ] });
  service.addVerb("hangup", {});
  return service;
}

/** Host the document as a Call Flow. Returns the resource. */
export async function deploy(title = "Ridgeline Cycles router") {
  return client.fabric.callFlows.create({
    title, relayml: build().getDocument(), flow_data: FLOW_DATA,
  });
}

/** `filter_number` is a contains match, so compare the number exactly. */
export async function numberId(e164: string): Promise<string> {
  const page = await client.phoneNumbers.list({ filter_number: e164 });
  for (const item of (page["data"] ?? []) as { id: string; number: string }[]) {
    if (item.number === e164) return item.id;
  }
  throw new Error(`${e164} is not a number on this project`);
}

/** Route inbound calls on the number to the hosted flow. */
export async function pointNumber(resourceId: string, e164: string) {
  return client.fabric.resources.assignPhoneRoute(resourceId, {
    phone_route_id: await numberId(e164), handler: "calling",
  });
}

if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/"))) {
  const [cmd, id, number] = process.argv.slice(2);
  if (cmd === "deploy") {
    console.log((await deploy())["id"]);
  } else if (cmd === "point" && id && number) {
    console.log(await pointNumber(id, number));
  } else {
    console.log("usage: npm start deploy | npm start point <resource_id> <e164>");
  }
}

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # credentials, CRM_URL, CRM_TOKEN, the two desks
python app.py deploy             # prints the call flow's resource id
python app.py point <resource_id> +15551230000

The TypeScript surface builds the same document on @signalwire/sdk, on Node 20.18.1 or newer:

cd typescript
npm ci
cp ../.env.example .env
npm start deploy
npm start point <resource_id> +15551230000

Your endpoint has to answer a POST of {"phone": "+1..."} with JSON carrying a tier. Call the number from a phone your CRM knows.

Verify it

No network, no account.

python verify.py          # from the recipe folder, not python/

The verifier builds the document and drives the REST calls through a recorder. It asserts the following.

the document validates and its verbs are answer, request, cond, hangup, in that order
the request carries the CRM URL, the bearer header, {"phone": "%{call.from}"}, save_variables true and both timeouts
the cond is a when on request_result whose then is the switch on request_response.tier with a case per desk and a default, and an else that plays the apology and still connects
the schema requires url and method on request, when and then on a cond branch, else on the last, and variable and case on switch; its variable pattern accepts ${...} and %{...}
save_variables is described as storing the parsed JSON, and both timeouts default to 0
add_verb returns False for the list-shaped cond and raises for a request with no url, leaving the document unchanged
the flow is created with title, the document as relayml and its paired flow_data, then the number is looked up by exact match and bound with handler: calling, all three documented against the vendored spec
the TypeScript surface builds the same document and sends the same three requests

Report an issue