O Google Agenda é gerenciado por meio de funções de calculadora: o chatbot se comunica com a API do Google usando sua conta de serviço. Não é necessário configurar solicitações HTTP separadas.

Requisitos

  1. Um projeto do Google Cloud com a API Google Agenda ativada.
  2. Uma conta de serviço para este projeto e sua chave em formato JSON.
  3. Um calendário onde a conta de serviço tenha permissão para modificar eventos.

Como Criar uma Conta de Serviço e Obter uma Chave

  1. Acesse o Console do Google Cloud e crie um novo projeto.

  1. Vá para APIs e serviços → Biblioteca, encontre Google Agenda API e clique em Ativar. Sem esta etapa, todas as solicitações retornarão um erro.

  1. Vá para IAM e administrador → Contas de serviço, crie uma conta de serviço e atribua a ela o papel Proprietário.

  1. Abra a conta de serviço que você criou → guia Chaves → Adicionar chave → Criar nova chave → selecione JSON.

O arquivo de chave será baixado para o seu computador.

  1. Salve o endereço da conta de serviço — o campo client_email no arquivo baixado, por exemplo [email protected]. Você precisará dele para conceder à conta de serviço acesso ao calendário.

Onde Armazenar a Chave: Variável calendar_json_keys

  1. Envie o arquivo JSON baixado para o armazenamento de arquivos do projeto onde você está trabalhando com o Google Agenda, depois clique com o botão direito no arquivo e copie o link.

  1. Em Constantes do Projeto, adicione uma variável chamada calendar_json_keys e defina seu valor como um array de chaves:

Em outras palavras, cole o link que você copiou para o arquivo de chave enviado ao seu projeto.

["https://files.mavibot.ai/uploads/file_item/file/your_project_id/your_file_name.json"]

Você pode especificar várias chaves, por exemplo, se usar projetos diferentes. Para cada solicitação, o construtor usará uma delas:

[
  "https://files.mavibot.ai/uploads/file_item/file/your_project_id/your_file_name.json",
  "https://files.mavibot.ai/uploads/file_item/file/your_project_id/your_file_name.json"
]

Em vez de um link, você pode fornecer a chave inteira diretamente do arquivo enviado:

[
  {
    "type": "service_account",
    "project_id": "my-project",
    "private_key": "-----BEGIN PRIVATE KEY-----...",
    "client_email": "[email protected]",
    "..."
  }
]

Como Conceder à Conta de Serviço Acesso a um Calendário

Abra as configurações do calendário necessário → Compartilhar com pessoas ou grupos → Adicionar pessoas e grupos → insira o client_email da conta de serviço e conceda a permissão Fazer alterações em eventos.

Sem esta permissão, o Google retorna Not Found mesmo que o calendário exista.

Um calendário criado usando gcal_create_calendar fica imediatamente disponível para a conta de serviço, portanto, você não precisa compartilhá-lo separadamente.

Como Encontrar o ID do Calendário

Abra as configurações do calendário → Integrar calendário → ID do calendário.

O ID se parece aproximadamente com isto:

[email protected]

Você também pode obter os IDs de todos os calendários disponíveis usando:

gcal_calendars_list()

Como Chamar Funções, Formatos de Data e Fusos Horários

As funções, incluindo todas as funções listadas abaixo, são inseridas na calculadora do construtor do chatbot.

É conveniente salvar o resultado diretamente em uma variável:

event = gcal_add_event("[email protected]", "Consultation", "20.08.2026 14:00", "20.08.2026 15:00")

Cada função retorna a resposta da API do Google em formato JSON. Se ocorrer um erro, a resposta se parece com isto:

{"status": false, "err": "error description"}

Você pode recuperar um campo específico da resposta usando a função get.

Por exemplo:

get(event, 'id')

Formatos de Valor

Valor Formato Exemplo
Data e hora dd.mm.aaaa HH:MM 20.08.2026 14:00
Data (evento de dia inteiro) dd.mm.aaaa 20.08.2026
Fuso horário Identificador IANA Europe/Moscow, Europe/Istanbul

Se nenhum fuso horário for especificado, o fuso horário configurado nas configurações do projeto será usado.

Calendários

Como Criar um Calendário

Use a seguinte função:

gcal_create_calendar(name, description=null, time_zone=null, location=null, owner_email=null)

Parâmetros:

  • name — nome do calendário;
  • description — descrição do calendário;
  • time_zone — fuso horário;
  • location — localização;
  • owner_email — endereço de e-mail da conta do Google que receberá permissões de proprietário. A conta de serviço manterá o acesso ao calendário.

Exemplo:

calendar = gcal_create_calendar("Consultation Bookings", "Bot calendar", "Europe/Moscow", "", "[email protected]")

A função retorna os dados do calendário criado:

{
  "kind": "calendar#calendar",
  "id": "[email protected]",
  "summary": "Consultation Bookings",
  "timeZone": "Europe/Moscow"
}

Salve o ID do campo id em uma variável do projeto — ele é necessário para todas as outras funções.

Como Obter Informações do Calendário

gcal_get_calendar(calendar_id)

A função retorna o nome do calendário, descrição, fuso horário e endereço.

Como Obter a Lista de Calendários da Conta de Serviço

gcal_calendars_list()

A função retorna todos os calendários acessíveis à conta de serviço, juntamente com seus IDs.

Como Excluir um Calendário

gcal_remove_calendar(calendar_id)

Se o calendário for excluído com sucesso, a função retorna:

{"status": true}

Eventos

Como Adicionar Rapidamente um Evento

Use a seguinte função:

gcal_quick_add_event(calendar_id, event_name)

O Google analisará automaticamente a data e a hora do texto.

Exemplo:

event = gcal_quick_add_event("[email protected]", "Meeting with John tomorrow at 15:00")

Como Adicionar um Evento

Use a seguinte função:

gcal_add_event(calendar_id, event_name, start_datetime=null, end_datetime=null, event_description=null, location=null, time_zone=null, extra_params=null)

Parâmetros:

  • calendar_id — ID do calendário;
  • event_name — nome do evento;
  • start_datetime — data e hora de início do evento;
  • end_datetime — data e hora de término do evento;
  • event_description — descrição do evento;
  • location — localização do evento;
  • time_zone — fuso horário;
  • extra_params — parâmetros adicionais do evento em formato JSON.

Exemplo:

event = gcal_add_event("[email protected]", "Consultation #{name}", "20.08.2026 14:00", "20.08.2026 15:00", "Client phone: #{phone}", "Zoom", "Europe/Moscow", '{"popup_minutes": 30, "email_minutes": 60}')

Parâmetros Adicionais extra_params

extra_params é um objeto JSON contendo parâmetros opcionais:

Parâmetro Descrição
email_minutes Envia um lembrete por e-mail o número especificado de minutos antes do evento
popup_minutes Mostra um lembrete pop-up o número especificado de minutos antes do evento
start_date Data de início para um evento de dia inteiro
end_date Data de término para um evento de dia inteiro
transparency opaque — o horário é marcado como ocupado; transparent — o horário permanece disponível
recurrence_days Dias da semana para recorrência semanal: MO, TU, WE, TH, FR, SA, SU, separados por vírgulas
recurrence_until Data até a qual o evento se repete, por exemplo 20261231T000000Z
recurrence_count Número de ocorrências em vez de uma data de término

O valor padrão é:

transparency = opaque

Isso significa que o horário do evento é considerado ocupado.

Para manter o horário do evento disponível:

{"transparency": "transparent"}

Evento de Dia Inteiro

Para um evento de dia inteiro, passe start_date e end_date através de extra_params em vez de start_datetime e end_datetime.

Exemplo de um evento de dia inteiro que se repete às segundas e quartas-feiras 10 vezes:

event = gcal_add_event("[email protected]", "Webinar", null, null, "Weekly webinar", "", null, '{"start_date": "01.09.2026", "end_date": "02.09.2026", "recurrence_days": "MO,WE", "recurrence_count": 10}')

Para eventos de dia inteiro, o Google trata a data de término como exclusiva. Para criar um evento que ocupe apenas 01.09.2026, especifique 02.09.2026 como end_date.

Resposta ao Criar um Evento

A função retorna o evento criado:

{
  "kind": "calendar#event",
  "id": "7b1k2m3n4o5p",
  "status": "confirmed",
  "htmlLink": "https://www.google.com/calendar/event?eid=..."
}

Salve o id do evento em uma variável do cliente.

Por exemplo:

event_id = get(event, 'id')

Você precisará do ID posteriormente para atualizar, mover ou excluir o evento.

Como Atualizar um Evento

Use a seguinte função:

gcal_update_event(calendar_id, event_id, event_name=null, start_datetime=null, end_datetime=null, event_description=null, location=null, time_zone=null, extra_params=null)

Passe apenas os campos que deseja alterar. Todos os outros campos permanecerão inalterados.

Por exemplo, para remarcar um evento existente para 21.08.2026 das 16:00 às 17:00:

event = gcal_update_event("[email protected]", "#{event_id}", null, "21.08.2026 16:00", "21.08.2026 17:00")

A estrutura de extra_params é a mesma de gcal_add_event.

Os lembretes são atualizados por tipo.

Por exemplo, se você passar apenas:

{"popup_minutes": 30}

O lembrete pop-up será substituído, enquanto o lembrete por e-mail existente permanecerá inalterado.

Como Obter uma Lista de Eventos

Use a seguinte função:

gcal_get_event_list(calendar_id, start_date=null, end_date=null)

Parâmetros:

  • calendar_id — ID do calendário;
  • start_date — início do período no formato dd.mm.aaaa;
  • end_date — fim do período no formato dd.mm.aaaa.

Exemplo:

events = gcal_get_event_list("[email protected]", "20.08.2026", "27.08.2026")

Se nenhuma data for especificada, a função retorna eventos para o dia atual:

events = gcal_get_event_list("[email protected]")

Os eventos são retornados ordenados pela hora de início.

Eventos recorrentes são retornados como entradas separadas.

Como Obter Informações do Evento

Use a seguinte função:

gcal_get_event(calendar_id, event_id)

A função retorna todos os dados do evento, incluindo:

  • nome;
  • descrição;
  • data e hora;
  • local;
  • participantes;
  • lembretes;
  • outros parâmetros do evento.

Exemplo:

event = gcal_get_event("[email protected]", "#{event_id}")

Como Mover um Evento para Outro Calendário

Use a seguinte função:

gcal_move_event(calendar_id, event_id, destination_calendar_id)

onde:

  • calendar_id — ID do calendário atual;
  • event_id — ID do evento;
  • destination_calendar_id — ID do calendário para o qual o evento deve ser movido.

Exemplo:

event = gcal_move_event("[email protected]", "#{event_id}", "[email protected]")

Como Excluir um Evento

Use a seguinte função:

gcal_remove_event(calendar_id, event_id)

Exemplo:

result = gcal_remove_event("[email protected]", "#{event_id}")

Se o evento for excluído com sucesso, a função retorna:

{"status": true}

Participantes do Evento

Como Adicionar um Participante

Use a seguinte função:

gcal_add_client(calendar_id, event_id, client_email, name=null, comment=null)

Parâmetros:

  • calendar_id — ID do calendário;
  • event_id — ID do evento;
  • client_email — endereço de e-mail do participante;
  • name — o nome que será exibido no calendário;
  • comment — um comentário para o participante.

Exemplo:

event = gcal_add_client("[email protected]", "#{event_id}", "#{email}", "#{name}", "Reservado pelo bot")

Se este participante já foi adicionado ao evento, a função retorna um erro:

{"status": false, "err": "attendee already exists"}

Como Remover um Participante

Use a seguinte função:

gcal_remove_client(calendar_id, event_id, client_email)

Parâmetros:

  • calendar_id — ID do calendário;
  • event_id — ID do evento;
  • client_email — endereço de e-mail do participante a ser removido.

Exemplo:

event = gcal_remove_client("[email protected]", "#{event_id}", "#{email}")

Se o participante especificado não estiver no evento, a função retorna:

{"status": false, "err": "attendee not found"}

Erros Possíveis

Se ocorrer um erro, as funções retornam um objeto no seguinte formato:

{
  "status": false,
  "err": "descrição do erro"
}

Erros comuns:

Resposta Causa
Not Found O calendário não foi compartilhado com a conta de serviço, ou um calendar_id incorreto foi especificado
Google Calendar API has not been used in project ... or it is disabled A API do Google Calendar não está habilitada no projeto do Google Cloud
The key to access the calendar was not found in the passed link O link em calendar_json_keys não retorna o arquivo de chave
wrong datetime "...", expected format is dd.mm.yyyy HH:MM A data e a hora foram fornecidas em um formato incorreto
wrong date "...", expected format is dd.mm.yyyy A data foi fornecida em um formato incorreto
Работает только на тарифах Бизнес и Инфобиз O projeto não possui uma assinatura ativa que inclua acesso a este recurso

Erro Not Found

Se o Google retornar:

Not Found

verifique o seguinte:

  1. Certifique-se de que o calendar_id está correto.
  2. Certifique-se de que o client_email da conta de serviço foi adicionado às configurações do calendário.
  3. Certifique-se de que a conta de serviço tem a permissão Fazer alterações em eventos.

Mesmo que o calendário exista, o Google pode retornar Not Found se a conta de serviço não tiver acesso a ele.

API do Google Calendar Não Habilitada

O erro se parece aproximadamente com isto:

Google Calendar API has not been used in project ... or it is disabled

Abra seu projeto no Google Cloud e habilite:

APIs & Services → Library → Google Calendar API → Enable

Após habilitar a API, repita a solicitação.

Chave da Conta de Serviço Não Encontrada

Erro:

The key to access the calendar was not found in the passed link

Verifique o valor de:

calendar_json_keys

Se você usar um link de arquivo, ele deve retornar diretamente o arquivo JSON contendo a chave da conta de serviço.

Exemplo:

["https://files.salebot.pro/xxxxxxxx/key.json"]

Você também pode fornecer a chave diretamente em calendar_json_keys como um objeto JSON.

Formato de Data e Hora Incorreto

Erro:

wrong datetime "...", expected format is dd.mm.yyyy HH:MM

Formato correto:

dd.mm.yyyy HH:MM

Exemplo:

20.08.2026 14:00

Exemplos incorretos:

2026-08-20 14:00
20/08/2026 14:00
20.08.2026

Se a função espera data e hora, você deve fornecer a data junto com horas e minutos.

Formato de Data Incorreto

Erro:

wrong date "...", expected format is dd.mm.yyyy

Formato correto:

dd.mm.yyyy

Exemplo:

20.08.2026

Nenhum Plano de Assinatura Elegível

Erro:

Работает только на тарифах Бизнес и Инфобиз

Isso significa que o projeto não possui uma assinatura ativa que permita o uso das funções do Google Calendar.

Exemplo Rápido

Crie um evento e salve seu ID:

event = gcal_add_event("[email protected]", "Consulta #{name}", "20.08.2026 14:00", "20.08.2026 15:00", "Telefone do cliente: #{phone}", "Zoom", "Europe/Moscow")

event_id = get(event, 'id')

Adicione o cliente ao evento criado:

event = gcal_add_client("[email protected]", "#{event_id}", "#{email}", "#{name}", "Reservado pelo bot")

Se o cliente decidir remarcar:

event = gcal_update_event("[email protected]", "#{event_id}", null, "21.08.2026 16:00", "21.08.2026 17:00")

Se o cliente cancelar a reserva:

result = gcal_remove_event("[email protected]", "#{event_id}")

Erros da API do Google são retornados inalterados no campo err. A mensagem de erro ajuda a determinar o que está faltando: acesso ao calendário, API habilitada, chave válida, formato de data correto ou um evento existente.