Visualizações de calendário
- Como qualquer tipo personalizado pode ser exibido como um calendário
- Onde fica a configuração de calendário e o que cada chave faz
- Quando um tipo ganha uma visualização de calendário e como abri-la
- Como o exemplo de agendamento usa o calendário para compromissos
- Como funcionam os registros recorrentes
No AutoTalk, um calendário é uma forma de visualizar um tipo personalizado — não um aplicativo nativo separado. Qualquer tipo personalizado cujos registros tenham um campo Data ou Data e hora pode ser exibido em um calendário, para que você navegue e gerencie esses registros por dia, semana ou mês em vez de uma lista plana.
Quando um tipo ganha um calendário?
Um tipo personalizado ganha uma visualização de calendário quando sua definição inclui uma configuração de calendário — no mínimo, qual campo de data/hora marca o início de cada registro. Você também pode apontar para um campo de fim, um título, uma cor e um campo de recorrência.
Depois que o calendário está configurado, o tipo passa a ter uma visualização de calendário ao lado da listagem normal, acessível pelo item daquele tipo no menu lateral. Tipos sem campo de data — ou sem configuração de calendário — aparecem como lista.
Adicionando uma configuração de calendário
A chave é um único campo na definição do tipo: Calendário, no formulário de Tipos Personalizados. É uma caixa de JSON puro — sem seletor e sem texto de exemplo — e o estado vazio dentro do app chama o que vai ali de bloco de calendário.
O menor bloco que funciona indica o campo de início:
{
"startField": "startTimestamp",
"defaultView": "month"
}
Salve, e o tipo vira um grupo na barra lateral, com Visualização em lista e
Visualização em calendário dentro dele. Um startField não vazio é
exatamente o que essa verificação olha: sem ele o tipo continua sendo uma lista
simples, não importa o que mais o bloco tenha.
Um bloco mais completo, adaptado do tipo Events do exemplo Agendador:
{
"startField": "startTimestamp",
"endField": "endTimestamp",
"recurrenceField": "recurrence",
"groupByField": "employeeId",
"colorExpr": {"expr": "'#23a538'"},
"defaultView": "month"
}
As chaves
Quatro delas são caminhos pontilhados para campos do registro:
| Chave | Para o que aponta |
|---|---|
startField | Obrigatório. O campo Data ou Data e hora que marca onde a entrada começa. Um registro sem nada ali fica fora do calendário |
endField | Onde a entrada termina. Sem ele, o calendário desenha um bloco de uma hora a partir do início |
recurrenceField | Um campo que guarda uma string RRULE — veja Registros recorrentes |
groupByField | Um campo para agrupar as entradas, como o funcionário a quem a entrada foi atribuída |
defaultView escolhe a visualização em que o calendário abre — day, week,
month ou agenda. Se você não informar, ele abre em month. Um ?view= na
URL sobrepõe isso, e é o que torna uma visualização específica compartilhável
como link.
As outras quatro chaves são expressões CEL, e não caminhos:
| Chave | O que define |
|---|---|
titleExpr | O rótulo desenhado em cada entrada |
colorExpr | A cor da entrada, como qualquer string de cor CSS |
allDayExpr | Se a entrada é desenhada como uma faixa de dia inteiro |
tooltipExpr | O texto que aparece ao passar o mouse |
Essas expressões são avaliadas separadamente para cada registro. values e item apontam para o registro; itemId é seu identificador. O contexto da empresa continua disponível. Exemplo:
{"titleExpr": {"expr": "values.name"}, "colorExpr": {"expr": "has(item.confirmed) && item.confirmed == true ? '#23a538' : '#756fef'"}}
Verifique campos ausentes com has(...) ou maps.get(...).
Duas outras chaves aparecem nos blocos do exemplo Agendador —
availabilityFromType e workingHoursType — e nada as lê. A sobreposição de
horário de trabalho encontra aquele tipo pelo slug working_hours, e não por
este bloco, então copiar essas duas chaves para o seu tipo não faz efeito algum.
Um exemplo completo: agendamento de compromissos
Nada provisiona um produto de agendamento para você — um calendário é o que você obtém ao dar a um dos seus tipos personalizados um campo de data e uma configuração de calendário. A forma mais rápida de ver um completo é importar o exemplo Agendador, cujo ZIP já traz um conjunto pronto de tipos personalizados para agendamento:
| Tipo | O que guarda |
|---|---|
| Eventos | Os compromissos em si — data/hora, quem e o quê |
| Serviços | Serviços agendáveis, cada um com duração e preço |
| Horários de Trabalho | A agenda semanal normal de cada funcionário |
| Períodos do Funcionário | Folgas e exceções pontuais de disponibilidade |
O tipo Eventos já vem com uma configuração de calendário, então abre diretamente como um calendário. Esse é o mesmo mecanismo que você pode adicionar a qualquer tipo personalizado — o exemplo é só um conjunto pronto, ajustado para agendamentos.
As visualizações do calendário
Um calendário oferece quatro formas de olhar os mesmos registros:
- Dia — um único dia, hora a hora. Melhor para um olhar detalhado dos registros do dia.
- Semana — a semana atual ao longo das horas de trabalho. Bom para encontrar lacunas e sobreposições.
- Mês — um mês inteiro de uma vez. Bom para uma visão geral.
- Agenda — uma lista cronológica dos próximos registros.
Use as setas de navegação para mudar de período e os filtros para restringir quais registros aparecem (por exemplo, pelo funcionário a quem um Evento está atribuído).
Criando um registro pelo calendário
Usando o tipo Eventos desse exemplo:
- Navegue até a data com as setas ou trocando de visualização.
- Clique em um horário (visualização Dia/Semana) ou em uma data (visualização Mês) para começar um novo Evento.
- Preencha os campos do registro. Para Eventos, são o contato, o(s) serviço(s), o funcionário atribuído e o horário de início/fim — mas o formulário sempre reflete os campos que o seu tipo personalizado define.
- Salve. O registro aparece no calendário imediatamente.
Você pode abrir qualquer registro para editá-lo, arrastá-lo para um novo horário para reagendar ou excluí-lo. Para Eventos, o horário de fim e o título podem ser preenchidos automaticamente pelos workflows do exemplo (por exemplo, calculando o fim a partir da duração dos serviços selecionados).
Registros recorrentes
Se a configuração de calendário declarar um campo de recorrência, os registros podem se repetir em uma programação em vez de serem recriados manualmente. A recorrência é armazenada como uma string RRULE padrão, então um tipo pode expressar padrões diários, semanais ou mensais (por exemplo, uma sessão semanal toda terça às 10:00).
Um registro recorrente é armazenado como um único registro, e o calendário o expande em um evento por ocorrência dentro do período visível. Editá-lo edita esse único registro, então a mudança se aplica à série inteira, e não a uma ocorrência específica.
Como os registros se conectam (exemplo de agendamento)
Nesse exemplo, cada Evento liga outros três registros:
| Campo | O que responde |
|---|---|
| Contato | Para quem é o compromisso? |
| Serviço | O que será feito? |
| Funcionário | Quem vai realizar? |
O Contato é um registro de contato real, então um Evento referencia o contato em vez de copiar os dados dele. Os workflows do exemplo também gravam um carimbo de data/hora lastScheduledEventAt no contato (usado, por exemplo, para retomar o contato após um período de inatividade); os compromissos em si não são listados no perfil do contato. Essa ligação de três pontas é específica do desenho desse exemplo; os seus próprios tipos com calendário podem referenciar quaisquer registros que façam sentido para eles.
Próximos passos
- Criando um Tipo Personalizado — defina um tipo e seus campos, incluindo campos de Data / Data e hora
- Gerenciando registros — adicionar, editar e filtrar registros
- Usando Tipos Personalizados com agentes de IA e MCP — permita que agentes leiam e gravem registros do calendário