Architect Expression: Formatting E.164 to (XXX) XXX-XXXX

Architect & Flows
1

Quick question about string manipulation in Architect expressions.

I’m trying to format a phone number coming from a webhook payload. The input is E.164, e.g., +15551234567. I need it formatted as (555) 123-4567 for display on a supervisor dashboard widget I’m building in Vue.

I’ve tried using the format function with a custom pattern, but it seems to only support date/time formatting. I also tried chaining substring calls, but the expression parser is choking on the nested logic.

Here is the expression I’m currently testing:

format(phoneNumber, "(XXX) XXX-XXXX")

This returns an error: Invalid format string.

Is there a way to use replace or regex in an Architect expression? Or do I need to do this in the Studio snippet before the data hits the architect flow? I’d prefer to keep the logic in the expression if possible to avoid adding another node.

Any pointers appreciated.

2

Have you tried handling this in your pre-request script or backend service instead of fighting Architect’s limited string manipulation functions?

Architect expressions are designed for routing logic, not complex formatting. The substring approach is brittle and fails if the country code length varies (e.g., +44 vs +1). You are likely hitting validation errors or unexpected nulls when the input doesn’t match your hardcoded indices.

Here is a robust JavaScript regex solution for your Postman pre-request script or Node.js backend:

// Input: +15551234567
let e164 = "+15551234567";

// Remove non-numeric characters
let clean = e164.replace(/\D/g, '');

// Handle US/Canada (+1) specifically
if (clean.startsWith('1') && clean.length === 11) {
 let area = clean.substring(1, 4);
 let prefix = clean.substring(4, 7);
 let line = clean.substring(7, 11);
 let formatted = `(${area}) ${prefix}-${line}`;
 console.log(formatted); // Output: (555) 123-4567
} else {
 // Fallback for other formats or invalid inputs
 console.log("Invalid US number format");
}

Do not rely on the Genesys Cloud API to do this for you. The /api/v2/telephony/phones endpoints return raw E.164 strings by design. If you need formatted output for a Vue dashboard, format it on the client side or in your middleware.

Using Architect for this adds unnecessary complexity to your flow. If you must do it in Architect, use the regex function with a capture group, but be aware that debugging regex failures in Architect logs is painful. Stick to code for formatting. Your Postman collection should validate the raw E.164 input, then apply the format transformation in your test assertions or pre-request scripts to ensure data consistency before it hits your UI.

3

Pretty sure the suggestion above to handle this in the backend is technically sound, but it introduces a hidden latency risk that often breaks real-time dashboard widgets. When you process data in a pre-request script or backend service, you are adding network hops before the data even reaches the Architect flow. For a supervisor dashboard using the Genesys Cloud Client App SDK, this delay causes the UI to flash empty states or show stale data while waiting for the formatted response.

You can solve this directly in Architect using a Data Action. It is more efficient than backend processing because it runs within the conversation context and avoids external API calls. Here is the configuration:

  1. Create a new Data Action named FormatPhoneNumber.
  2. Add an input variable inputNumber (String).
  3. Add an output variable formattedNumber (String).
  4. Use this JavaScript code in the action body:
let input = inputNumber;
if (input && input.length === 11) {
 // Assuming US +1 country code
 let areaCode = input.substring(1, 4);
 let prefix = input.substring(4, 7);
 let lineNumber = input.substring(7, 11);
 output.formattedNumber = `(${areaCode}) ${prefix}-${lineNumber}`;
} else {
 output.formattedNumber = input; // Fallback if format is unexpected
}

In your Architect Flow, call this Data Action immediately after receiving the webhook. Map the webhook attribute to inputNumber and set the result to a new conversation attribute. This keeps the formatting logic inside Genesys Cloud, ensuring the Client App SDK receives clean data instantly. It avoids the CORS and hydration issues I have seen with Next.js SSR when the backend response structure changes unexpectedly.

4

The docs actually state the format function is strictly for temporal data, so your initial assumption was correct. You need to use replace with regex instead of substring to handle variable country code lengths reliably. See the expression syntax details here: https://developer.genesys.cloud/architect/expressions/string-functions