Pular para conteúdo

CALENDAR_CREATE_EVENT - Criar Evento no Google Calendar

O que é esta Tool?

A CALENDAR_CREATE_EVENT é a tool responsável por criar novos eventos no Google Calendar com suporte completo a datas, horários, convidados, lembretes, recorrência e configurações avançadas.

Por que esta Tool existe?

Agendar eventos manualmente é trabalhoso e propenso a erros. A CALENDAR_CREATE_EVENT existe para:

  1. Automação de Agendamentos: Criar eventos automaticamente via WhatsApp ou outros canais
  2. Integração com Workflows: Agendar reuniões após confirmação de clientes
  3. Gestão de Compromissos: Criar eventos com múltiplos convidados e notificações
  4. Eventos Recorrentes: Configurar reuniões semanais, mensais ou anuais automaticamente

Como funciona internamente?

Quando a CALENDAR_CREATE_EVENT é executada, o sistema:

  1. Valida Autenticação: Verifica se possui accessToken ou refreshToken válidos
  2. Renova Token: Se necessário, usa o refreshToken para obter novo accessToken
  3. Prepara Dados: Formata data/hora no padrão RFC3339 e prepara estrutura do evento
  4. Envia Requisição: Chama a API do Google Calendar (POST /calendar/v3/calendars/{calendarId}/events)
  5. Processa Resposta: Retorna eventId, htmlLink e dados completos do evento criado
  6. Se erro de autenticação: Retorna erro solicitando re-autorização OAuth2
  7. Se sucesso: Retorna confirmação com link do evento e ID único

Código interno (google-executors.service.ts:371-381): 

case 'createEvent':
  const createResult = await calendar.events.insert({
    calendarId: data.calendarId || 'primary',
    requestBody: {
      summary: data.summary,
      description: data.description,
      start: { dateTime: data.startDateTime, timeZone: data.timeZone || 'America/Sao_Paulo' },
      end: { dateTime: data.endDateTime, timeZone: data.timeZone || 'America/Sao_Paulo' },
      attendees: data.attendees?.map((email: string) => ({ email })) || [],
    },
  });

  return {
    success: true,
    eventId: createResult.data.id,
    htmlLink: createResult.data.htmlLink,
  };

Quando você DEVE usar esta Tool?

Use CALENDAR_CREATE_EVENT sempre que precisar de criação automatizada de eventos:

Casos de uso

  1. Agendamento de Consultas: "Agendar consulta médica para amanhã às 14h"
  2. Reuniões de Negócio: "Criar reunião com cliente na sexta-feira às 10h"
  3. Eventos Recorrentes: "Agendar reunião semanal toda segunda às 9h"
  4. Workshops e Treinamentos: "Criar evento de treinamento com 20 participantes"

Quando NÃO usar CALENDAR_CREATE_EVENT

  • Atualizar evento existente: Use CALENDAR_UPDATE_EVENT
  • Apenas consultar eventos: Use CALENDAR_LIST_EVENTS ou CALENDAR_GET_EVENT
  • Verificar disponibilidade: Use CALENDAR_GET_FREE_BUSY

Parâmetros Detalhados

summary (string, obrigatório)

O que é: Título do evento que aparece na agenda.

Padrão: Nenhum (obrigatório)

Flow completo para testar:

{
  "name": "Teste Calendar - Summary",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "calendar_1",
      "type": "google_calendar",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Criar Evento",
        "operation": "createEvent",
        "oauth2": {
          "clientId": "{{GOOGLE_CLIENT_ID}}",
          "clientSecret": "{{GOOGLE_CLIENT_SECRET}}",
          "refreshToken": "{{GOOGLE_REFRESH_TOKEN}}"
        },
        "calendarId": "primary",
        "summary": "Reunião de Planejamento 2025",
        "startDateTime": "2025-10-15T14:00:00-03:00",
        "endDateTime": "2025-10-15T15:00:00-03:00",
        "timeZone": "America/Sao_Paulo"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Evento criado: {{calendar_1.eventId}}\nLink: {{calendar_1.htmlLink}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "calendar_1" },
    { "source": "calendar_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: O sistema criará um evento com título "Reunião de Planejamento 2025" e retornará o link do evento criado.

startDateTime (string RFC3339, obrigatório)

O que é: Data e hora de início do evento no formato ISO 8601 / RFC3339.

Formato: YYYY-MM-DDTHH:MM:SS±HH:MM (exemplo: 2025-10-15T14:00:00-03:00)

Padrão: Nenhum (obrigatório)

Flow completo para testar:

{
  "name": "Teste Calendar - Data/Hora Início",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "calendar_1",
      "type": "google_calendar",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Evento com Data/Hora",
        "operation": "createEvent",
        "oauth2": {
          "clientId": "{{GOOGLE_CLIENT_ID}}",
          "clientSecret": "{{GOOGLE_CLIENT_SECRET}}",
          "refreshToken": "{{GOOGLE_REFRESH_TOKEN}}"
        },
        "calendarId": "primary",
        "summary": "Teste de Horário",
        "startDateTime": "2025-10-20T09:30:00-03:00",
        "endDateTime": "2025-10-20T10:30:00-03:00",
        "timeZone": "America/Sao_Paulo"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Evento agendado para 20/10/2025 às 09:30"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "calendar_1" },
    { "source": "calendar_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: O evento será criado para dia 20/10/2025 às 09:30 (horário de Brasília).

endDateTime (string RFC3339, obrigatório)

O que é: Data e hora de término do evento no formato ISO 8601 / RFC3339.

Formato: YYYY-MM-DDTHH:MM:SS±HH:MM

Padrão: Nenhum (obrigatório)

description (string, opcional)

O que é: Descrição detalhada do evento que aparece nos detalhes.

Padrão: "" (vazio)

location (string, opcional)

O que é: Local do evento (endereço físico ou link de videoconferência).

Padrão: "" (vazio)

attendees (array de emails, opcional)

O que é: Lista de emails dos convidados que receberão notificações.

Formato: ["email1@example.com", "email2@example.com"]

Padrão: [] (sem convidados)

timeZone (string, opcional)

O que é: Fuso horário do evento no formato IANA timezone.

Exemplos: America/Sao_Paulo, America/New_York, Europe/London, Asia/Tokyo

Padrão: "America/Sao_Paulo"

calendarId (string, opcional)

O que é: ID da agenda onde o evento será criado.

Padrão: "primary" (agenda principal do usuário)

Parâmetros

Campo Tipo Obrigatório Descrição
summary string Sim Título do evento
startDateTime string (RFC3339) Sim Data/hora de início
endDateTime string (RFC3339) Sim Data/hora de término
description string Não Descrição detalhada do evento
location string Não Local ou link do evento
attendees array Não Lista de emails dos convidados
timeZone string Não Fuso horário (padrão: America/Sao_Paulo)
calendarId string Não ID da agenda (padrão: primary)

Exemplo 1: Reunião Simples

Objetivo: Criar uma reunião básica com título, data e horário

JSON para Importar

{
  "name": "Reunião Simples - Google Calendar",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Título da Reunião",
        "parameters": {
          "message": "Qual o título da reunião?",
          "variableName": "titulo"
        }
      }
    },
    {
      "id": "calendar_1",
      "type": "google_calendar",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Criar Evento",
        "operation": "createEvent",
        "oauth2": {
          "clientId": "{{GOOGLE_CLIENT_ID}}",
          "clientSecret": "{{GOOGLE_CLIENT_SECRET}}",
          "refreshToken": "{{GOOGLE_REFRESH_TOKEN}}"
        },
        "calendarId": "primary",
        "summary": "{{titulo}}",
        "startDateTime": "2025-10-25T10:00:00-03:00",
        "endDateTime": "2025-10-25T11:00:00-03:00",
        "timeZone": "America/Sao_Paulo"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Reunião agendada com sucesso!\n\nTítulo: {{titulo}}\nData: 25/10/2025\nHorário: 10:00 - 11:00\n\nLink: {{calendar_1.htmlLink}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "calendar_1" },
    { "source": "calendar_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Qual o título da reunião?
Usuário: Alinhamento Semanal
Sistema: Reunião agendada com sucesso!

Título: Alinhamento Semanal
Data: 25/10/2025
Horário: 10:00 - 11:00

Link: https://calendar.google.com/event?eid=...

Exemplo 2: Reunião com Convidados

Objetivo: Criar evento com múltiplos participantes e descrição detalhada

JSON para Importar

{
  "name": "Reunião com Convidados",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "calendar_1",
      "type": "google_calendar",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Criar Reunião com Time",
        "operation": "createEvent",
        "oauth2": {
          "clientId": "{{GOOGLE_CLIENT_ID}}",
          "clientSecret": "{{GOOGLE_CLIENT_SECRET}}",
          "refreshToken": "{{GOOGLE_REFRESH_TOKEN}}"
        },
        "calendarId": "primary",
        "summary": "Review Trimestral Q4 2025",
        "description": "Reunião para revisar resultados do Q4 e planejar Q1 2026.\n\nPauta:\n- Resultados Q4\n- Metas Q1 2026\n- Budget 2026",
        "location": "Sala de Reuniões A - 3º andar",
        "startDateTime": "2025-12-20T14:00:00-03:00",
        "endDateTime": "2025-12-20T16:00:00-03:00",
        "timeZone": "America/Sao_Paulo",
        "attendees": [
          "joao.silva@empresa.com",
          "maria.santos@empresa.com",
          "pedro.costa@empresa.com"
        ]
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Reunião criada e convites enviados para 3 participantes!\n\nID: {{calendar_1.eventId}}\n\nAcesse: {{calendar_1.htmlLink}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "calendar_1" },
    { "source": "calendar_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Reunião criada e convites enviados para 3 participantes!

ID: abc123xyz789

Acesse: https://calendar.google.com/event?eid=abc123xyz789

Resposta da Tool

{
  "success": true,
  "action": "calendar_create_event",
  "eventId": "abc123xyz789",
  "htmlLink": "https://calendar.google.com/event?eid=abc123xyz789",
  "status": "confirmed",
  "timestamp": "2025-10-12T10:30:00.000Z"
}

Boas Práticas

SIM:

  • Use formato RFC3339 para datas: 2025-10-15T14:00:00-03:00
  • Especifique sempre o fuso horário (timeZone)
  • Adicione descrição detalhada para eventos complexos
  • Use calendarId: "primary" para agenda principal
  • Valide que endDateTime seja posterior a startDateTime

NÃO:

  • Não use datas no passado sem justificativa
  • Não esqueça o offset do timezone (-03:00, +00:00, etc)
  • Não crie eventos sem título (summary)
  • Não confunda formato de data (use RFC3339, não DD/MM/YYYY)

Dicas

Formato RFC3339: Use sempre o padrão ISO 8601 com timezone. Exemplos: - Brasília: 2025-10-15T14:00:00-03:00 - UTC: 2025-10-15T17:00:00Z - Nova York: 2025-10-15T12:00:00-04:00

Duração padrão: Se não especificado, o Google Calendar assume 1 hora de duração.

Convites automáticos: Quando você adiciona attendees, o Google envia convites por email automaticamente.

Agenda secundária: Para criar em agenda específica, use o calendarId (ex: empresa.com_abc123@group.calendar.google.com).

Próximos Nodes

→ CALENDAR_UPDATE_EVENT - Atualizar evento existente → CALENDAR_LIST_EVENTS - Listar eventos da agenda → CALENDAR_ADD_ATTENDEE - Adicionar participantes ao evento