Referencia de Funciones CEL
Referencia completa de todas las funciones integradas disponibles en las expresiones CEL de AutoTalk. Las funciones están organizadas por categoría.
Core
get(obj, path, default?)
Accede de forma segura a una propiedad anidada a través de una ruta con puntos.
get(contact, "address.city") // "São Paulo"
get(contact, "address.zip", "00000-000") // retorna el predeterminado si falta
get(null, "name") // null
get(step(0), "data.results.0.title") // ruta profunda con índice de array
| Param | Tipo | Descripción |
|---|---|---|
obj | any | Objeto a acceder (seguro para null) |
path | string | Ruta con puntos (ej.: "a.b.c") |
default | any | Valor retornado si la ruta no existe (predeterminado: null) |
has(obj, path?)
Verifica si un valor o una ruta anidada existe y no es null/undefined.
has(contact, "platformId") // true si contact.platformId está definido
has(myVar) // true si myVar no es null/undefined
has(obj, "a.b.c") // true si la ruta completa resuelve a no-null
coalesce(...vals)
Retorna el primer valor no-null y no-undefined. Variádica — acepta hasta 5 argumentos. Si necesitas más, anida las llamadas: coalesce(a, b, c, d, coalesce(e, f)).
coalesce(get(contact, "customAttributes.nickname"), contact.name, "Guest") // el primer no-null gana
coalesce(0, 42) // 0 (no es null!)
coalesce(false, true) // false (no es null!)
coalesce("", "fallback") // "" (no es null!)
coalesce() solo omite null y undefined. Valores como 0, false y "" son válidos y se retornan.
now(tz?)
Retorna la fecha/hora actual como una string ISO 8601.
now() // "2024-01-15T14:30:00.000Z"
format_datetime(now(), "YYYY-MM-DD") // "2024-01-15"
El resultado siempre se expresa en UTC (sufijo Z), incluso cuando se pasa el argumento opcional de zona horaria. Para mostrar la hora actual en una zona horaria específica, formatéala — ej.: format_datetime(now(), "HH:mm", "America/Sao_Paulo").
present(val)
Verifica si un valor está significativamente presente. Retorna false para null, undefined, strings vacías/solo espacios y arrays vacíos. Los números y booleanos siempre se consideran presentes.
present(contact.platformId) // true si es una string no vacía
present("") // false
present(" ") // false (solo espacios)
present(0) // true
present([]) // false
present([1, 2]) // true
present(x) reemplaza el patrón común size(trim(coalesce(x, ""))) > 0.
blank(val)
Inverso de present(). Retorna true para null, undefined, strings vacías/solo espacios y arrays vacíos.
blank(contact.platformId) // true si es null o vacío
blank("hello") // false
blank(0) // false
Utilidades
pluck(arr, path)
Extrae una propiedad de cada objeto de un array.
pluck(contacts, "name") // ["Alice", "Bob", "Carol"]
pluck(tools, "tool.function.name") // ruta profunda soportada
slice(arr, start, end?)
Corta un array de forma segura. Retorna [] para entradas que no son arrays. Admite índices negativos.
slice(results, 0, 5) // primeros 5 elementos
slice(results, -3) // últimos 3 elementos
slice(results, 1, -1) // todos excepto el primero y el último
slice(null, 0, 2) // [] (seguro para no-arrays)
defaults(obj, fallbacks)
Fusiona valores de respaldo en un objeto para las claves que son null/undefined. Fusión superficial.
defaults(response, {"status": "unknown", "retryable": false})
// Completa status y retryable solo si son null/undefined en response
Como coalesce(), solo se reemplazan los valores null/undefined. 0, false y "" se mantienen.
url_params(base, params)
Construye una URL con parámetros de query. Omite los valores null y vacíos. Codifica automáticamente.
url_params("https://api.example.com/search", {"q": query, "page": 1, "lang": null})
// "https://api.example.com/search?q=hello&page=1" (lang omitido)
truncate(str, maxLen, suffix?)
Trunca una string a una longitud máxima con un sufijo opcional.
truncate("Hello World", 5) // "Hello"
truncate("Hello World", 8, "...") // "Hello..."
truncate(null, 10) // "" (seguro para null)
truncate("Hi", 100) // "Hi" (sin necesidad de truncar)
| Param | Tipo | Descripción |
|---|---|---|
str | any | Valor a truncar (convertido a string, null retorna "") |
maxLen | number | Longitud máxima del resultado (incluyendo el sufijo) |
suffix | string | Se agrega al truncar (predeterminado: "") |
El sufijo se incluye dentro de maxLen: truncate("Hello World", 8, "...") retorna "Hello..." (8 caracteres).
tpl(template, vars)
Interpolación simple de strings. Reemplaza los marcadores {key} con valores de un objeto.
tpl("Hello {name}!", {"name": "Alice"}) // "Hello Alice!"
tpl("*{title}*\n{domain}\n{url}", article) // texto formateado del artículo
tpl("{address.city}, {address.country}", contact) // soporte de ruta con puntos
tpl("Hi {name}", {"name": null}) // "Hi " (null → vacío)
| Param | Tipo | Descripción |
|---|---|---|
template | string | String de plantilla con marcadores {key} |
vars | object | Objeto con valores para interpolar |
join_present(separator, ...values)
Une valores con un separador, omitiendo los valores en blanco. Usa las mismas reglas que present(): null, strings vacías/solo espacios y arrays vacíos se omiten. 0 y false se mantienen. Acepta como máximo 5 argumentos en total — el separador más hasta 4 valores.
join_present(", ", "Alice", "Bob", "Carol") // "Alice, Bob, Carol"
join_present(" - ", title, null, author) // "Title - Author" (null omitido)
join_present(" ", "Hello", "", "World") // "Hello World" (vacío omitido)
join_present(" | ", 0, false, "text") // "0 | false | text" (0/false mantenidos)
join_present(" - ", prefix, text) reemplaza el patrón (present(prefix) ? prefix + " - " : "") + text.
encode_uri(str)
Codifica una string para URL. Los caracteres reservados de URI (&, =, ?, /, #) no se escapan, así que solo es adecuada para codificar una URL completa — no para valores individuales de parámetros de query.
encode_uri("hello world") // "hello%20world"
encode_uri("a&b=c") // "a&b=c" (caracteres reservados preservados)
Para agregar parámetros de query a una URL de forma segura, usa url_params() — codifica cada valor de parámetro por ti.
format_currency(currency, locale, amount)
Formatea un número como moneda. Los tres argumentos son obligatorios, en este orden: código de moneda, locale y, por último, el importe.
format_currency("USD", "en-US", 1234.5) // "$1,234.50"
format_currency("BRL", "pt-BR", 99.9) // "R$ 99,90"
String
CEL incluye funciones de string integradas. La mayoría funciona tanto en estilo receptor como en estilo función:
"hello".contains("ell") // true (estilo receptor)
contains("hello", "ell") // true (estilo función)
| Función | Descripción | Ejemplo |
|---|---|---|
contains(str, sub) | Verifica si la string contiene la substring | "hello".contains("ell") |
startsWith(str, prefix) | Verifica el prefijo | "hello".startsWith("he") |
endsWith(str, suffix) | Verifica el sufijo | "hello".endsWith("lo") |
matches(str, pattern) | Coincidencia por expresión regular | "abc123".matches("^abc[0-9]+$") → true |
size(x) | Longitud de una string, lista o mapa | size("hello") → 5, size([1, 2, 3]) → 3 |
split(str, sep) | Divide en array | split("a,b,c", ",") → ["a","b","c"] |
lowerAscii(str) | Minúsculas | lowerAscii("HELLO") → "hello" |
upperAscii(str) | Mayúsculas | upperAscii("hello") → "HELLO" |
trim(str) | Elimina espacios | trim(" hi ") → "hi" |
substring(str, start, end?) | Extrae substring | substring("hello", 1, 4) → "ell" |
replace(str, old, new) | Reemplaza ocurrencias | replace("aab", "a", "x") → "xxb" |
indexOf(str, sub) | Primer índice de la substring | indexOf("hello", "l") → 2 |
lastIndexOf(str, sub) | Último índice de la substring | lastIndexOf("hello", "l") → 3 |
charAt(str, index) | Carácter en el índice | charAt("hello", 0) → "h" |
join(list, sep?) | Une un array en una string | join(["a","b"], ",") → "a,b" |
Math
| Función | Descripción | Ejemplo |
|---|---|---|
math_add(a, b) | Suma | math_add(5, 3) → 8 |
math_subtract(a, b) | Resta | math_subtract(10, 3) → 7 |
math_multiply(a, b) | Multiplicación | math_multiply(4, 3) → 12 |
math_divide(a, b) | División | math_divide(10, 3) → 3.333... |
math_round(n, decimals?) | Redondeo | math_round(3.456, 2) → 3.46 |
math_floor(n) | Piso | math_floor(3.7) → 3 |
math_ceil(n) | Techo | math_ceil(3.1) → 4 |
math_abs(n) | Valor absoluto | math_abs(-5) → 5 |
math_pow(base, exp) | Potencia | math_pow(2, 3) → 8 |
math_sqrt(n) | Raíz cuadrada | math_sqrt(16) → 4 |
math_sin(n) | Seno (radianes) | math_sin(0) → 0 |
math_cos(n) | Coseno (radianes) | math_cos(0) → 1 |
math_tan(n) | Tangente (radianes) | math_tan(0) → 0 |
math_log(n, base?) | Logaritmo (natural por defecto) | math_log(8, 2) → 3 |
math_exp(n) | e elevado a la potencia n | math_exp(0) → 1 |
math_max(arr) | Máximo | math_max([1,5,3]) → 5 |
math_min(arr) | Mínimo | math_min([1,5,3]) → 1 |
math_mean(arr) | Promedio | math_mean([1,2,3]) → 2 |
math_median(arr) | Mediana | math_median([1,2,10]) → 2 |
math_std(arr) | Desviación estándar (muestral) | math_std([2,4,6]) → 2 |
math_variance(arr) | Varianza (muestral) | math_variance([2,4,6]) → 4 |
math_dot(a, b) | Producto punto de dos vectores | math_dot([1,2,3], [4,5,6]) → 32 |
math_norm(arr) | Norma euclidiana (longitud del vector) | math_norm([3,4]) → 5 |
math_clamp(val, min, max) | Restringe al rango | math_clamp(15, 0, 10) → 10 |
math_evaluate(expr) | Evalúa una string con una expresión matemática | math_evaluate("2 + 3 * 4") → 14 |
math_clamp(val, min, max)
Restringe un número dentro de un rango.
math_clamp(page, 1, 100) // asegura que page esté entre 1 y 100
math_clamp(-5, 0, 10) // 0 (por debajo del mínimo)
math_clamp(15, 0, 10) // 10 (por encima del máximo)
DateTime
| Función | Descripción |
|---|---|
now(tz?) | Fecha/hora actual como una string ISO 8601 (siempre expresada en UTC) |
format_datetime(d, fmt, tz?, locale?) | Formatea una fecha/hora. Acepta cualquier string de formato de dayjs — ej.: "DD/MM/YYYY", "YYYY-MM-DD HH:mm:ss", "HH:mm" — más una zona horaria y un locale opcionales ("en", "pt-BR", "es") |
add_datetime(d, n, unit) | Agrega tiempo. Unidades: "years", "months", "weeks", "days", "hours", "minutes", "seconds", "milliseconds" |
diff_datetime(d1, d2, unit) | Diferencia entre dos fechas/horas |
zoned_datetime(dateStr, timeStr, tz, format?) | Construye una fecha/hora con zona horaria a partir de strings separadas de fecha y hora, ej.: zoned_datetime("2024-01-15", "14:30", "America/Sao_Paulo"). Para convertir o mostrar una fecha/hora ya existente, usa format_datetime |
is_before(d1, d2) | ¿d1 antes de d2? |
is_after(d1, d2) | ¿d1 después de d2? |
is_between(d, start, end) | ¿d entre start y end? |
is_same_date(d1, d2, unit?, tz?) | ¿d1 y d2 son iguales en la unidad dada? (unidad predeterminada: "millisecond") — ej.: is_same_date(a, b, "day") verifica el mismo día calendario |
is_same_or_before(d1, d2, unit?, tz?) | ¿d1 igual o antes que d2? |
is_same_or_after(d1, d2, unit?, tz?) | ¿d1 igual o después que d2? |
JSON
| Función | Descripción |
|---|---|
json_parse(str) | Convierte una string JSON en un objeto |
json_stringify(obj) | Serializa un objeto en una string JSON |
TOON
TOON es un formato de serialización de datos compacto y legible para humanos.
| Función | Descripción |
|---|---|
toon_encode(value) | Codifica un valor a una string TOON |
toon_decode(str) | Parsea una string TOON de vuelta a un valor |
toon_encode({"name": "Alice", "age": 30}) // "name: Alice\nage: 30"
toon_decode("name: Alice\nage: 30") // {"name": "Alice", "age": 30}
BSON / ObjectId
| Función | Descripción |
|---|---|
object_id(value?) | Crea o normaliza una instancia de ObjectId (una nueva si no hay argumento). Usa object_id_to_string() para obtener la string hexadecimal |
object_id_is_valid(id) | Verifica si la string es un ObjectId válido |
object_id_to_string(id) | Convierte un ObjectId a su string hexadecimal |
bson_serialize(value, encoding?) | Serializa un valor a bytes BSON, devueltos como una string base64 (predeterminado) o "hex" |
bson_deserialize(str, encoding?) | Decodifica una string BSON en base64 (predeterminado) o "hex" de vuelta a un valor |
ejson_stringify(value, relaxed?) | Serializa un valor a una string de MongoDB Extended JSON (modo relaxed por defecto) |
ejson_parse(str, relaxed?) | Parsea una string de MongoDB Extended JSON a un valor |
bson_serialize({"a": 1}) // "DAAAABBhAAEAAAAA" (base64)
bson_serialize({"a": 1}, "hex") // "0c0000001061000100000000"
bson_deserialize("DAAAABBhAAEAAAAA") // {"a": 1}
ejson_stringify({"a": 1}) // "{\"a\":1}"
Específicas de Workflow
Estas funciones solo están disponibles en las expresiones de workflow y de agentes (no en el CEL de formularios).
step(N)
Accede a la salida del paso N del workflow (indexado desde 0).
step(0) // objeto completo de salida del paso
step(0).data // payload de datos del paso
step(0).status // código de estado HTTP (para pasos HTTP)
step_ok(N)
Verifica si el paso N se completó exitosamente. Retorna true cuando executionContext.status es "completed" Y el estado HTTP es 200 (o null para pasos no-HTTP).
// Antes: verboso
get(step(0), "executionContext.status") == "completed" && (get(step(0), "status") == null || get(step(0), "status") == 200)
// Después: una llamada a función
step_ok(0)
step_data(N, path?, default?)
Obtiene datos del paso N en una ruta con puntos opcional. Retorna el predeterminado (o null) si no existe.
// Antes
get(step(0), "data.title", null)
// Después
step_data(0, "title")
step_data(0, "results.0.name", "Unknown")
step_data(1, "choices.0.message.content")
step_error(N)
Obtiene la información de error de un paso fallido. Retorna {code, user_message, retryable} o null.
// Antes
coalesce(get(step(0), "executionContext.safeError.code"), "UNKNOWN")
// Después
step_error(0) // {code: "TIMEOUT", user_message: "...", retryable: true}
get(step_error(0), "code", "UNKNOWN") // "TIMEOUT"
step_has_content(N, path)
Verifica si el paso N se completó exitosamente Y tiene datos presentes (no-null, no-vacío) en la ruta dada. Combina step_ok(N) && present(step_data(N, path)) en una sola llamada.
// Antes: dos verificaciones
step_ok(0) && present(step_data(0, "articles"))
// Después: una llamada a función
step_has_content(0, "articles")
getContext()
Obtiene el objeto de contexto de ejecución del workflow.
getTool()
Obtiene el objeto de contexto de la herramienta que se está ejecutando actualmente — el mismo contexto del que leen los auxiliares step(N). No toma argumentos; cualquier argumento que se pase se ignora.
getRoot()
Obtiene el contexto raíz del workflow.