​

Crono — Guia de Uso

Guia prático para utilizar o Crono, o recurso de resolução de datas e horários em linguagem natural do Tolky.

​

O que é o Crono?

O Crono interpreta expressões em português e devolve datas e horários concretos para agendamentos, reagendamentos e lembretes. Ele entende frases como:

• “Agendar para amanhã às 14h”
• “Próxima terça-feira”
• “Daqui a 3 dias úteis”
• “Primeira terça da segunda quinzena de março”
• “Toda segunda às 9h”

​

Como funciona: detecção de operadores

O Crono usa detecção de operadores temporais para fazer os cálculos. Ele identifica palavras e padrões no texto (dias da semana, meses, expressões relativas, horários, etc.) e aplica regras para chegar à data final.

Importante: o resultado depende da forma como você fala. Algumas frases funcionam muito bem; outras podem gerar dúvidas ou não serem interpretadas corretamente.

​

O que isso significa na prática

• Frases claras e diretas tendem a funcionar melhor.
• Expressões ambíguas ou muito coloquiais podem gerar confiança baixa ou pedido de confirmação.
• Formas alternativas de dizer a mesma coisa às vezes são tratadas de forma diferente.

Tentamos cobrir o máximo de cenários possíveis. Se algum caso não estiver coberto ou não funcionar como esperado, podemos aprimorar a funcionalidade — basta reportar.

​

Formas recomendadas de falar

​

Datas explícitas

​

Expressões relativas

​

Dias úteis

​

Recorrências

​

Expressões compostas

​

Situações que podem gerar dificuldade

​

1. Ambiguidade

• “Na quinta” — pode ser esta quinta ou a próxima. O sistema tende a assumir a próxima e pode pedir confirmação.
• “Segunda” sem “-feira” — pode ser ordinal (ex.: “segunda quinzena”) ou dia da semana. Em caso de dúvida, use “segunda-feira”.

​

2. Expressões muito vagas

• “Talvez algum dia semana que vem” — intenção pouco clara; pode retornar confiança baixa.
• “Quando der” — sem referência temporal; não será interpretado como data.

​

3. Formas muito coloquiais ou regionais

• Algumas gírias ou expressões regionais podem não ser reconhecidas.
• Preferir formas mais padrão quando possível.

​

4. Múltiplas datas no mesmo texto

• Se o usuário mudar de ideia várias vezes, o sistema prioriza a última menção de data.

​

O que fazer quando não funcionar

1. Reformule — tente uma forma mais direta ou explícita.
2. Confirme — se o sistema retornar needs_confirmation: true, mostre a data proposta e peça confirmação ao usuário.
3. Reporte — se um caso comum não estiver coberto, podemos adicionar suporte.

​

Uso via API

​

Endpoint

POST /api/externalAPIs/public/dateResolverFromDialogue

​

Corpo da Requisição

Se dialogue for um array, cada item deve seguir o formato:

{ "role": "system|user|assistant", "content": "texto da mensagem" }

​

Exemplo mínimo

curl -X POST "{{BASE_URL}}/api/externalAPIs/public/dateResolverFromDialogue" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{seu-tolky-domain-token}}" \
  -d '{
    "dialogue": "Agendar para próxima terça às 14h"
  }'

​

Exemplo com opções

curl -X POST "{{BASE_URL}}/api/externalAPIs/public/dateResolverFromDialogue" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{seu-tolky-domain-token}}" \
  -d '{
    "dialogue": [
      { "role": "user", "content": "Hoje é 2026-03-05" },
      { "role": "user", "content": "Marque para segunda às 9h" }
    ],
    "nowISO": "2026-03-05T10:00:00-03:00",
    "options": {
      "tz": "America/Sao_Paulo",
      "defaultTime": "09:00",
      "holidaysCountry": "BR",
      "holidaysState": "SP"
    }
  }'

​

Interpretando a resposta

​

Sucesso com data resolvida

• resolved_date — texto amigável (ex.: “terça, 10/03/2026 14:00”)
• resolution.start_local — data/hora em ISO com timezone
• resolution.assumed_time — true se o horário foi assumido (não informado)

​

Confiança baixa

• Se trust.score < 70, resolved_date virá null.
• Use insights para mensagens de orientação ao usuário.

​

Ambiguidade

• resolution.needs_confirmation — true quando há dúvida
• resolution.ambiguity_reason — explicação (ex.: “Você disse ‘terça’, mas caiu em quinta.“)
• Mostre a data proposta e peça confirmação.

​

Exemplo de resposta

{
  "resolved_date": "terça, 10/03/2026 14:00",
  "resolution": {
    "start_local": "2026-03-10T14:00:00-03:00",
    "start_utc": "2026-03-10T17:00:00Z",
    "tz": "America/Sao_Paulo",
    "assumed_time": false,
    "needs_confirmation": false,
    "ambiguity_reason": null,
    "recurrence": null
  },
  "insights": [
    "Usuário sugeriu terça às 14h."
  ],
  "trust": {
    "score": 0.92,
    "explain": "Extração clara de weekday/time; baixa ambiguidade."
  }
}

​

Boas práticas

1. Envie contexto quando relevante — se o usuário disser “hoje é 15 de novembro” e depois “daqui a 3 dias”, inclua as duas mensagens no dialogue.
2. Use nowISO em testes — para resultados reproduzíveis.
3. Valide trust.score — scores baixos indicam incerteza; considere pedir clarificação.
4. Confirme agendamentos — mostre a data resolvida antes de finalizar, principalmente se needs_confirmation for true.
5. Aproveite os insights — o sistema pode avisar sobre feriados ou outras observações.

​

Códigos de Erro

• 400: Payload inválido (ex.: dialogue ausente, vazio ou mal formatado)

​

Resumo

Documentação voltada para uso do Crono na plataforma Tolky. Para detalhes técnicos e arquitetura, consulte a documentação interna do projeto.