Search Calendar Items

Full-text search across title, description, and location fields. Do NOT use this to filter by event type (visit, task, call, whatsapp). When the user asks for items of a specific type ('visitas', 'tarefas', 'ligações', 'chamadas', 'zap'), use item_type instead.

Calendar item title (full or partial).

Calendar item type filter. Use when the user asks for items of a specific type. Map Portuguese terms: 'visita', 'visitas' → 'visit'; 'tarefa', 'tarefas', 'lembrete', 'lembretes', 'todo' → 'task'; 'ligação', 'ligações', 'ligacao', 'ligacoes', 'chamada', 'chamadas', 'call' → 'call'; 'whatsapp', 'zap', 'wpp' → 'whatsapp'. Also accepts active custom type names.

Calendar item status: active or canceled.

Completion filter: true (done) or false (pending).

Responsible user name (partial match allowed). Use ONLY when filtering by a specific OTHER user's calendar. When the user refers to their OWN items ('meus compromissos', 'minha agenda', 'minhas tarefas', 'meus eventos', 'minha semana') do NOT set this field — set requesting_user_only=True instead.

Responsible user email (exact match, preferred for disambiguation). Use ONLY when filtering by a specific OTHER user's calendar. When the user refers to their OWN items ('meus compromissos', 'minha agenda'), do NOT set this field — set requesting_user_only=True instead.

Set to true when the user refers to their own calendar items using possessive language: 'meus compromissos', 'minha agenda', 'minhas tarefas', 'meus eventos', 'meus lembretes', 'meu calendário', 'minha semana', 'my appointments'. When true, results are restricted to the requesting user's items regardless of read permissions. Do NOT set this when the user asks about another person's calendar. If user_name or user_email is also provided, that explicit user filter takes precedence.

Related contact name (parent or guest).

Related contact email (preferred for higher precision).

Related contact phone number. Accepts flexible formatting with or without country code, area code, dashes and spaces. Example: '11999887766', '+55 11 99988-7766'.

Related contact legal identification (CPF or CNPJ). Example: '123.456.789-00' or '12345678000190'.

Related property code.

Related property address (partial match allowed).

Deal code in numeric or prefixed format, such as 653 or VEN-653. For a numeric code, also provide pipeline_group_name; a prefixed code resolves the pipeline from its prefix.

Pipeline group name. Provide it when deal_code is numeric; omit it when the code already contains a pipeline prefix.

Date period shortcut for filtering calendar items by date range. Map Portuguese terms from the user's message to the correct value: 'hoje', 'hoje mesmo', 'neste dia' → 'today'; 'esta semana', 'essa semana', 'nesta semana', 'semana atual' → 'this_week'; 'este mês', 'esse mês', 'neste mês', 'mês atual' → 'this_month' (default); 'mês passado', 'mês anterior' → 'last_month'; 'últimos 3 meses', 'últimos três meses', 'trimestre' → 'last_three_months'; 'este ano', 'esse ano', 'ano atual' → 'current_year'; 'ano passado', 'ano anterior' → 'last_year'. When the user provides a specific date or explicit date range, use start_at/end_at instead.

Explicit start datetime in ISO 8601 format (overrides period). Calendar times are interpreted as America/Sao_Paulo wall-clock values. Use when the user provides a specific date like '22/05/2026' or '2026-05-22'. Convert DD/MM/YYYY to ISO 8601 (YYYY-MM-DD). Example: '22/05/2026' → '2026-05-22T00:00:00'.

Explicit end datetime in ISO 8601 format (overrides period). Calendar times are interpreted as America/Sao_Paulo wall-clock values. Use together with start_at when the user specifies a date range.

Maximum number of returned items. Default: 20.