Saltar para o conteúdo principal

Visão geral

Variáveis permitem que você personalize as instruções do seu agente com dados dinâmicos. itellicoAI usa templates Jinja2.

Como as variáveis funcionam

Variáveis de contato integradas

Se um contato existe em sua conta itellicoAI, estes 5 campos estão automaticamente disponíveis:
{{ contact.first_name }}
{{ contact.last_name }}
{{ contact.full_name }}
{{ contact.email }}
{{ contact.phone }}
Exemplo:
Olá {{ contact.first_name }}!
Seu e-mail é {{ contact.email }}.
✅ Nenhuma configuração necessária - funciona automaticamente se o contato existe

Todo o resto: API de contexto dinâmico

Todos os outros dados devem vir do seu endpoint API de contexto dinâmico como variáveis de nível superior. Você pode retornar quaisquer campos que desejar. Por exemplo:
{{ language }}
{{ account_tier }}
{{ company_name }}
{{ order_id }}
{{ customer_since }}
{{ any_field_you_need }}
Exemplo - Sua API retorna:
{
  "language": "pt",
  "account_tier": "premium",
  "company_name": "Acme Corp"
}
Então seu agente pode usar:
{% if language == "pt" %}
Olá! Você trabalha para {{ company_name }}.
{% endif %}

{% if account_tier == "premium" %}
Suporte prioritário disponível.
{% endif %}
⚙️ Requer configuração - veja API de contexto dinâmico

Variáveis disponíveis

Variáveis de contato integradas

Estas variáveis estão automaticamente disponíveis de seus contatos itellicoAI:
{{ contact.first_name }}
{{ contact.last_name }}
{{ contact.full_name }}
{{ contact.email }}
{{ contact.phone }}
Exemplo de uso:
Você está falando com {{ contact.first_name }} {{ contact.last_name }}.
O e-mail dele é {{ contact.email | default("não fornecido") }}.
O número de telefone dele é {{ contact.phone }}.

Campos personalizados NÃO estão aninhados sob contact. — eles são variáveis de nível superior como {{ language }} ou {{ account_tier }}. Você deve fornecê-los através da sua API de contexto dinâmico.

Variáveis de contexto dinâmico

Quaisquer dados personalizados que você forneça através do seu endpoint API de contexto dinâmico se tornam disponíveis como variáveis de nível superior:
{{ account_tier }}
{{ language }}
{{ company_name }}
{{ preferred_contact_method }}
Exemplo com variáveis personalizadas:
{% if account_tier == "premium" %}
Como cliente premium, você tem suporte prioritário.
{% endif %}

{% if language == "pt" %}
Fale português.
{% endif %}

Empresa: {{ company_name | default("cliente valorizado") }}

Configure um endpoint API de contexto dinâmico para fornecer variáveis personalizadas. Quaisquer campos JSON que você retornar se tornam variáveis de nível superior (ex., {"language": "pt"}{{ language }}).

Data e hora

A data e hora atuais estão automaticamente disponíveis como current_datetime tanto em saudações quanto instruções:
{{ current_datetime }}                      # Timestamp atual
{{ current_datetime.hour }}                 # Hora atual (0-23)
{{ current_datetime | datetime("%H:%M") }}  # Formato com filtro datetime
{{ current_datetime | datetime("%A") }}     # Nome do dia (Segunda, Terça, etc.)
Exemplo de uso:
{% if current_datetime.hour < 12 %}
Bom dia, {{ contact.first_name }}!
{% elif current_datetime.hour < 17 %}
Boa tarde, {{ contact.first_name }}!
{% else %}
Boa noite, {{ contact.first_name }}!
{% endif %}
Use current_datetime para construir lógica avançada baseada em tempo como roteamento de horário comercial, saudações baseadas em hora do dia ou restrições de agendamento sem precisar de fontes de dados externas.
Use o filtro datetime para formatação. O método .strftime() não está disponível por restrições de segurança.

Lógica condicional

Instrução If

{% if condition %}
  Isto é mostrado se a condição for verdadeira
{% endif %}

If-Else

{% if account_tier == "VIP" %}
  Fornecer serviço VIP
{% else %}
  Fornecer serviço padrão
{% endif %}

If-Elif-Else

{% if account_value > 10000 %}
  Cliente nível Enterprise
{% elif account_value > 1000 %}
  Cliente nível Professional
{% else %}
  Cliente nível Padrão
{% endif %}

Exemplo do mundo real

{% if language == "es" %}
Responda em espanhol. Use tratamento formal (usted).
{% elif language == "fr" %}
Responda em francês. Use tratamento formal (vous).
{% elif language == "de" %}
Responda em alemão. Use tratamento formal (Sie).
{% else %}
Responda em inglês. Use tom amigável e conversacional.
{% endif %}

Filtros

Filtros transformam valores de variáveis.

Filtros comuns

default: Fornecer valor de fallback
{{ contact.first_name | default("") }}
upper: Converter para maiúsculas
{{ contact.last_name | upper }}
lower: Converter para minúsculas
{{ contact.email | lower }}
title: Primeira letra maiúscula
{{ contact.first_name | title }}
length: Obter comprimento
{% if contact.phone | length > 10 %}
  Número internacional detectado
{% endif %}
datetime: Formatar objetos datetime
{{ current_datetime | datetime("%H:%M") }}         # 14:30
{{ current_datetime | datetime("%d.%m.%Y") }}      # 24.01.2025
{{ current_datetime | datetime("%A, %B %d") }}     # Segunda, 24 de janeiro

Encadeamento de filtros

{{ contact.first_name | default("Amigo") | title }}

Loops

Iterar sobre listas (caso de uso avançado):
{% for item in list_variable %}
  Processar {{ item }}
{% endfor %}

Exemplos práticos

Exemplo 1: Saudação personalizada

{% if contact.first_name %}
Olá {{ contact.first_name }}, é ótimo ouvir de você!
{% else %}
Olá! Obrigado por ligar!
{% endif %}

{% if contact.email %}
Tenho suas informações de contato em arquivo, então posso enviar uma confirmação após nossa chamada.
{% endif %}

Exemplo 2: Lógica de negócio personalizada (Requer API de contexto dinâmico)

{% if contact.first_name %}
Olá {{ contact.first_name }}, obrigado por ligar para {{ company_name }}!
{% else %}
Olá! Obrigado por ligar para {{ company_name }}!
{% endif %}

{% if account_tier == "premium" %}
Como cliente premium, você tem suporte prioritário. Como posso ajudá-lo hoje?
{% else %}
Como posso ajudá-lo hoje?
{% endif %}
Variáveis como company_name e account_tier devem ser fornecidas pelo seu endpoint API de contexto dinâmico.

Exemplo 3: Instruções baseadas em tempo

Hora atual: {{ current_datetime | datetime("%H:%M") }}

{% if current_datetime.hour >= 17 or current_datetime.hour < 9 %}
Fora do horário comercial normal. Se o cliente precisa de assistência imediata:
"Nosso horário de suporte regular é das 9h às 17h. Para problemas urgentes, posso pegar suas informações e alguém ligará de manhã cedo, ou você pode ligar para nossa linha de emergência no [número]."
{% else %}
Dentro do horário comercial. Suporte completo disponível.
{% endif %}

Exemplo 4: Suporte multilíngue (Requer API de contexto dinâmico)

Idioma preferido do cliente: {{ language | default("pt") }}

{% if language == "es" %}
Idioma: Espanhol
Saudação: "¡Hola!"
Tom: Formal (use "usted")
Coleção de conhecimento: "FAQ Español"
{% elif language == "de" %}
Idioma: Alemão
Saudação: "Guten Tag!"
Tom: Formal (use "Sie")
Coleção de conhecimento: "FAQ Deutsch"
{% else %}
Idioma: Português
Saudação: "Olá!"
Tom: Amigável e conversacional
Coleção de conhecimento: "FAQ Português"
{% endif %}

Exemplo 5: Lógica de nível de conta

Valor da conta: R${{ account_value | default(0) }}

{% if account_value >= 50000 %}
🌟 CLIENTE ENTERPRISE
- Oferecer serviço white-glove
- Acesso direto ao gerente de conta
- Tempos de resposta prioritários
- Soluções personalizadas disponíveis
{% elif account_value >= 10000 %}
💼 CLIENTE PROFESSIONAL
- Nível de suporte premium
- Equipe de suporte dedicada
- Fila prioritária
{% else %}
👤 CLIENTE PADRÃO
- Suporte padrão
- Base de conhecimento primeiro
- Transferir para problemas complexos
{% endif %}

Testando variáveis

Testar com dados diferentes

  1. Vá para Chamada de teste
  2. Teste cenários com dados de contato diferentes:
    • Com nome vs sem nome
    • Cliente VIP vs cliente padrão
    • Idiomas diferentes
    • Fusos horários diferentes

Problemas comuns

ProblemaCausaSolução
Variável aparece em brancoNenhum valor padrão fornecidoAdicione | default("fallback")
Erro de sintaxeErro de digitação no nome da variávelVerifique ortografia contra variáveis disponíveis
Condição não funcionaOperador de comparação erradoUse == não =
Filtro não se aplicaFiltro não existeVerifique ortografia do nome do filtro

Melhores práticas

Nunca assuma que uma variável tem um valor. Sempre forneça padrões.Ruim:
Olá {{ contact.first_name }}!
Bom:
Olá {{ contact.first_name | default("") }}!
Condições aninhadas complexas são difíceis de depurar. Mantenha simples.Muito complexo:
{% if account_tier == "VIP" and account_value > 10000 and region == "BR" %}
Mais simples:
{% if account_tier == "VIP" %}
Teste com:
  • Dados ausentes (todos os campos vazios)
  • Valores inesperados
  • Strings muito longas
  • Caracteres especiais

Próximos passos