Referência de Funções CEL
Referência completa de todas as funções integradas disponíveis nas expressões CEL do AutoTalk. As funções estão organizadas por categoria.
Core
get(obj, path, default?)
Acessa com segurança uma propriedade aninhada através de um caminho pontilhado.
get(contact, "address.city") // "São Paulo"
get(contact, "address.zip", "00000-000") // retorna o padrão se ausente
get(null, "name") // null
get(step(0), "data.results.0.title") // caminho profundo com índice de array
| Param | Tipo | Descrição |
|---|---|---|
obj | any | Objeto a acessar (seguro para null) |
path | string | Caminho pontilhado (ex: "a.b.c") |
default | any | Valor retornado se o caminho estiver ausente (padrão: null) |
has(obj, path?)
Verifica se um valor ou caminho aninhado existe e não é null/undefined.
has(contact, "platformId") // true se contact.platformId estiver definido
has(myVar) // true se myVar não for null/undefined
has(obj, "a.b.c") // true se o caminho completo resolver para não-null
coalesce(...vals)
Retorna o primeiro valor não-null e não-undefined. Variádica — aceita até 5 argumentos. Se precisar de mais, aninhe as chamadas: coalesce(a, b, c, d, coalesce(e, f)).
coalesce(get(contact, "customAttributes.nickname"), contact.name, "Guest") // o primeiro não-null vence
coalesce(0, 42) // 0 (não é null!)
coalesce(false, true) // false (não é null!)
coalesce("", "fallback") // "" (não é null!)
coalesce() ignora apenas null e undefined. Valores como 0, false e "" são válidos e retornados.
now(tz?)
Retorna a data/hora atual como uma string ISO 8601.
now() // "2024-01-15T14:30:00.000Z"
format_datetime(now(), "YYYY-MM-DD") // "2024-01-15"
O resultado é sempre expresso em UTC (sufixo Z), mesmo quando o argumento opcional de fuso horário é passado. Para exibir a hora atual em um fuso horário específico, formate-a — ex.: format_datetime(now(), "HH:mm", "America/Sao_Paulo").
present(val)
Verifica se um valor está significativamente presente. Retorna false para null, undefined, strings vazias/somente espaços e arrays vazios. Números e booleanos são sempre considerados presentes.
present(contact.platformId) // true se for string não vazia
present("") // false
present(" ") // false (somente espaços)
present(0) // true
present([]) // false
present([1, 2]) // true
present(x) substitui o padrão comum size(trim(coalesce(x, ""))) > 0.
blank(val)
Inverso de present(). Retorna true para null, undefined, strings vazias/somente espaços e arrays vazios.
blank(contact.platformId) // true se for null ou vazio
blank("hello") // false
blank(0) // false
Utilitários
pluck(arr, path)
Extrai uma propriedade de cada objeto em um array.
pluck(contacts, "name") // ["Alice", "Bob", "Carol"]
pluck(tools, "tool.function.name") // caminho profundo suportado
slice(arr, start, end?)
Fatia um array com segurança. Retorna [] para entradas que não são arrays. Suporta índices negativos.
slice(results, 0, 5) // primeiros 5 itens
slice(results, -3) // últimos 3 itens
slice(results, 1, -1) // todos exceto o primeiro e o último
slice(null, 0, 2) // [] (seguro para não-arrays)
defaults(obj, fallbacks)
Mescla valores de fallback em um objeto para chaves que são null/undefined. Mesclagem superficial.
defaults(response, {"status": "unknown", "retryable": false})
// Preenche status e retryable somente se forem null/undefined em response
Assim como coalesce(), apenas valores null/undefined são substituídos. 0, false e "" são mantidos.
url_params(base, params)
Constrói uma URL com parâmetros de query. Ignora valores null e vazios. Codifica automaticamente.
url_params("https://api.example.com/search", {"q": query, "page": 1, "lang": null})
// "https://api.example.com/search?q=hello&page=1" (lang ignorado)
truncate(str, maxLen, suffix?)
Trunca uma string até um comprimento máximo com um sufixo opcional.
truncate("Hello World", 5) // "Hello"
truncate("Hello World", 8, "...") // "Hello..."
truncate(null, 10) // "" (seguro para null)
truncate("Hi", 100) // "Hi" (sem necessidade de truncar)
| Param | Tipo | Descrição |
|---|---|---|
str | any | Valor a truncar (convertido para string, null retorna "") |
maxLen | number | Comprimento máximo do resultado (incluindo o sufixo) |
suffix | string | Adicionado quando truncado (padrão: "") |
O sufixo é incluído dentro de maxLen: truncate("Hello World", 8, "...") retorna "Hello..." (8 caracteres).
tpl(template, vars)
Interpolação simples de string. Substitui marcadores {key} por valores de um objeto.
tpl("Hello {name}!", {"name": "Alice"}) // "Hello Alice!"
tpl("*{title}*\n{domain}\n{url}", article) // texto formatado do artigo
tpl("{address.city}, {address.country}", contact) // suporte a caminho pontilhado
tpl("Hi {name}", {"name": null}) // "Hi " (null → vazio)
| Param | Tipo | Descrição |
|---|---|---|
template | string | String de template com marcadores {key} |
vars | object | Objeto com valores para interpolar |
join_present(separator, ...values)
Junta valores com um separador, ignorando valores em branco. Usa as mesmas regras de present(): null, strings vazias/somente espaços e arrays vazios são ignorados. 0 e false são mantidos. Aceita no máximo 5 argumentos no total — o separador mais até 4 valores.
join_present(", ", "Alice", "Bob", "Carol") // "Alice, Bob, Carol"
join_present(" - ", title, null, author) // "Title - Author" (null ignorado)
join_present(" ", "Hello", "", "World") // "Hello World" (vazio ignorado)
join_present(" | ", 0, false, "text") // "0 | false | text" (0/false mantidos)
join_present(" - ", prefix, text) substitui o padrão (present(prefix) ? prefix + " - " : "") + text.
encode_uri(str)
Codifica uma string para URL. Caracteres URI reservados (&, =, ?, /, #) não são escapados, então ela só é adequada para codificar uma URL inteira — não valores individuais de parâmetros de query.
encode_uri("hello world") // "hello%20world"
encode_uri("a&b=c") // "a&b=c" (caracteres reservados preservados)
Para adicionar parâmetros de query a uma URL com segurança, use url_params() — ela codifica cada valor de parâmetro para você.
format_currency(currency, locale, amount)
Formata um número como moeda. Os três argumentos são obrigatórios, nesta ordem: código da moeda, locale e, por fim, o valor.
format_currency("USD", "en-US", 1234.5) // "$1,234.50"
format_currency("BRL", "pt-BR", 99.9) // "R$ 99,90"
String
CEL inclui funções de string integradas. A maioria funciona tanto no estilo receptor quanto no estilo função:
"hello".contains("ell") // true (estilo receptor)
contains("hello", "ell") // true (estilo função)
| Função | Descrição | Exemplo |
|---|---|---|
contains(str, sub) | Verifica se a string contém a substring | "hello".contains("ell") |
startsWith(str, prefix) | Verifica prefixo | "hello".startsWith("he") |
endsWith(str, suffix) | Verifica sufixo | "hello".endsWith("lo") |
matches(str, pattern) | Correspondência por expressão regular | "abc123".matches("^abc[0-9]+$") → true |
size(x) | Comprimento de uma string, lista ou map | size("hello") → 5, size([1, 2, 3]) → 3 |
split(str, sep) | Divide em array | split("a,b,c", ",") → ["a","b","c"] |
lowerAscii(str) | Minúsculas | lowerAscii("HELLO") → "hello" |
upperAscii(str) | Maiúsculas | upperAscii("hello") → "HELLO" |
trim(str) | Remove espaços | trim(" hi ") → "hi" |
substring(str, start, end?) | Extrai substring | substring("hello", 1, 4) → "ell" |
replace(str, old, new) | Substitui ocorrências | replace("aab", "a", "x") → "xxb" |
indexOf(str, sub) | Primeiro índice da substring | indexOf("hello", "l") → 2 |
lastIndexOf(str, sub) | Último índice da substring | lastIndexOf("hello", "l") → 3 |
charAt(str, index) | Caractere no índice | charAt("hello", 0) → "h" |
join(list, sep?) | Junta array em string | join(["a","b"], ",") → "a,b" |
Math
| Função | Descrição | Exemplo |
|---|---|---|
math_add(a, b) | Adição | math_add(5, 3) → 8 |
math_subtract(a, b) | Subtração | math_subtract(10, 3) → 7 |
math_multiply(a, b) | Multiplicação | math_multiply(4, 3) → 12 |
math_divide(a, b) | Divisão | math_divide(10, 3) → 3.333... |
math_round(n, decimals?) | Arredondamento | math_round(3.456, 2) → 3.46 |
math_floor(n) | Piso | math_floor(3.7) → 3 |
math_ceil(n) | Teto | math_ceil(3.1) → 4 |
math_abs(n) | Valor absoluto | math_abs(-5) → 5 |
math_pow(base, exp) | Potência | math_pow(2, 3) → 8 |
math_sqrt(n) | Raiz quadrada | math_sqrt(16) → 4 |
math_sin(n) | Seno (radianos) | math_sin(0) → 0 |
math_cos(n) | Cosseno (radianos) | math_cos(0) → 1 |
math_tan(n) | Tangente (radianos) | math_tan(0) → 0 |
math_log(n, base?) | Logaritmo (natural por padrão) | math_log(8, 2) → 3 |
math_exp(n) | e elevado à potência 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) | Média | math_mean([1,2,3]) → 2 |
math_median(arr) | Mediana | math_median([1,2,10]) → 2 |
math_std(arr) | Desvio padrão (amostral) | math_std([2,4,6]) → 2 |
math_variance(arr) | Variância (amostral) | math_variance([2,4,6]) → 4 |
math_dot(a, b) | Produto escalar de dois vetores | math_dot([1,2,3], [4,5,6]) → 32 |
math_norm(arr) | Norma euclidiana (comprimento do vetor) | math_norm([3,4]) → 5 |
math_clamp(val, min, max) | Restringe ao intervalo | math_clamp(15, 0, 10) → 10 |
math_evaluate(expr) | Avalia uma string de expressão matemática | math_evaluate("2 + 3 * 4") → 14 |
math_clamp(val, min, max)
Restringe um número dentro de um intervalo.
math_clamp(page, 1, 100) // garante que page está entre 1 e 100
math_clamp(-5, 0, 10) // 0 (abaixo do mínimo)
math_clamp(15, 0, 10) // 10 (acima do máximo)
DateTime
| Função | Descrição |
|---|---|
now(tz?) | Data/hora atual como uma string ISO 8601 (sempre expressa em UTC) |
format_datetime(d, fmt, tz?, locale?) | Formata uma data/hora. Aceita qualquer string de formato do dayjs — ex.: "DD/MM/YYYY", "YYYY-MM-DD HH:mm:ss", "HH:mm" — mais um fuso horário e locale opcionais ("en", "pt-BR", "es") |
add_datetime(d, n, unit) | Adiciona tempo. Unidades: "years", "months", "weeks", "days", "hours", "minutes", "seconds", "milliseconds" |
diff_datetime(d1, d2, unit) | Diferença entre duas datas/horas |
zoned_datetime(dateStr, timeStr, tz, format?) | Constrói uma data/hora com fuso horário a partir de strings separadas de data e hora, ex.: zoned_datetime("2024-01-15", "14:30", "America/Sao_Paulo"). Para converter ou exibir uma data/hora já existente, use format_datetime |
is_before(d1, d2) | d1 antes de d2? |
is_after(d1, d2) | d1 depois de d2? |
is_between(d, start, end) | d entre start e end? |
is_same_date(d1, d2, unit?, tz?) | d1 e d2 iguais na unidade dada? (unidade padrão: "millisecond") — ex.: is_same_date(a, b, "day") verifica o mesmo dia do calendário |
is_same_or_before(d1, d2, unit?, tz?) | d1 igual ou anterior a d2? |
is_same_or_after(d1, d2, unit?, tz?) | d1 igual ou posterior a d2? |
JSON
| Função | Descrição |
|---|---|
json_parse(str) | Converte string JSON em objeto |
json_stringify(obj) | Serializa objeto em string JSON |
TOON
TOON é um formato de serialização de dados compacto e legível por humanos.
| Função | Descrição |
|---|---|
toon_encode(value) | Codifica um valor em uma string TOON |
toon_decode(str) | Faz o parse de uma string TOON de volta em um valor |
toon_encode({"name": "Alice", "age": 30}) // "name: Alice\nage: 30"
toon_decode("name: Alice\nage: 30") // {"name": "Alice", "age": 30}
BSON / ObjectId
| Função | Descrição |
|---|---|
object_id(value?) | Cria ou normaliza uma instância de ObjectId (uma nova se não houver argumento). Use object_id_to_string() para obter a string hexadecimal |
object_id_is_valid(id) | Verifica se a string é um ObjectId válido |
object_id_to_string(id) | Converte um ObjectId em sua string hexadecimal |
bson_serialize(value, encoding?) | Serializa um valor em bytes BSON, retornados como uma string base64 (padrão) ou "hex" |
bson_deserialize(str, encoding?) | Decodifica uma string BSON base64 (padrão) ou "hex" de volta em um valor |
ejson_stringify(value, relaxed?) | Serializa um valor em uma string Extended JSON do MongoDB (modo relaxado por padrão) |
ejson_parse(str, relaxed?) | Faz o parse de uma string Extended JSON do MongoDB em um 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 funções estão disponíveis apenas em expressões de workflow e agentes (não em CEL de formulários).
step(N)
Acessa a saída do passo N do workflow (indexado a partir de 0).
step(0) // objeto completo de saída do passo
step(0).data // payload de dados do passo
step(0).status // código de status HTTP (para passos HTTP)
step_ok(N)
Verifica se o passo N foi concluído com sucesso. Retorna true quando executionContext.status é "completed" E o status HTTP é 200 (ou null para passos não-HTTP).
// Antes: verboso
get(step(0), "executionContext.status") == "completed" && (get(step(0), "status") == null || get(step(0), "status") == 200)
// Depois: uma chamada de função
step_ok(0)
step_data(N, path?, default?)
Obtém dados do passo N em um caminho pontilhado opcional. Retorna o padrão (ou null) se ausente.
// Antes
get(step(0), "data.title", null)
// Depois
step_data(0, "title")
step_data(0, "results.0.name", "Unknown")
step_data(1, "choices.0.message.content")
step_error(N)
Obtém informações de erro de um passo que falhou. Retorna {code, user_message, retryable} ou null.
// Antes
coalesce(get(step(0), "executionContext.safeError.code"), "UNKNOWN")
// Depois
step_error(0) // {code: "TIMEOUT", user_message: "...", retryable: true}
get(step_error(0), "code", "UNKNOWN") // "TIMEOUT"
step_has_content(N, path)
Verifica se o passo N foi concluído com sucesso E possui dados presentes (não-null, não-vazio) no caminho dado. Combina step_ok(N) && present(step_data(N, path)) em uma única chamada.
// Antes: duas verificações
step_ok(0) && present(step_data(0, "articles"))
// Depois: uma chamada de função
step_has_content(0, "articles")
getContext()
Obtém o objeto de contexto de execução do workflow.
getTool()
Obtém o objeto de contexto da ferramenta em execução no momento — o mesmo contexto que os auxiliares step(N) leem. Não recebe argumentos; quaisquer argumentos passados são ignorados.
getRoot()
Obtém o contexto raiz do workflow.