Guias

Ligações

O seu assistente de IA (Claude, ChatGPT) e o agente de voz durante uma chamada podem ambos ler o Google Calendar e o Calendário da Apple e, depois de o aprovar, atualizar um evento existente - e o agente de voz no motor próprio da volai pode ainda verificar um horário livre e fazer a marcação logo durante a chamada. No caso da Apple, preserve os identificadores opacos e tenha cuidado com as séries recorrentes.

O que consegue e o que não consegue fazer

• Lista os calendários ligados e os respetivos eventos.
• Altera o título, o início ou o fim de um evento existente.
• O agente de voz no motor próprio da volai verifica um horário livre e faz a marcação durante a chamada.
• Encontra horários livres e cria uma marcação também fora de uma chamada, através de REST e MCP.

Não consegue

• Nunca elimina um evento.
• Não procura horários livres para mais do que um participante.

Ligar uma conta Google

Ligue uma conta Google no portal, em Ligações (o item Integrações no menu do portal). Depois de a conta estar ligada, a mesma chave de API vê o mesmo através de REST e de MCP - não é necessário um início de sessão separado.

Pode desligar uma conta no portal ou com o REST DELETE /v1/integrations/{id}. O REST desliga-a de imediato e não tem qualquer campo de confirmação adicional, pelo que só o deve chamar depois de o utilizador ter aprovado expressamente a ação. O MCP não tem nenhuma ferramenta para desligar.

Calendário da Apple

Liga-se com uma palavra-passe específica da aplicação (não a palavra-passe normal da sua Conta Apple) no portal, em Dados e integrações. O REST também a pode ligar com POST /v1/integrations e {provider: "apple-calendar", username, appPassword, calendarUrl?}; o MCP não aceita credenciais e só pode utilizar a conta depois de esta ter sido ligada.

list_calendar_events e o REST GET /v1/integrations/{id}/events suportam o Calendário da Apple. Use o externalId opaco devolvido, sem o alterar, como eventId em get_calendar_event e nas atualizações; não é um UID iCalendar. Uma linha com recurring: true representa toda a série recorrente, e atualizá-la altera o evento principal da série e não uma única ocorrência; as exceções individuais são preservadas.

calendarId tem de ser um dos endereços devolvidos por list_calendars - qualquer outro é rejeitado com 400 calendar_invalid_calendar.

Marcação durante a chamada

Um agente de voz no motor próprio da volai pode verificar um horário livre e fazer a marcação logo durante a chamada telefónica - não se trata de um assistente de IA por chat, mas do próprio agente de voz que conduz a chamada. Ative-o no separador Calendário do editor do agente: escolha a ligação, o calendário e as regras de disponibilidade (janelas por dia da semana, duração da marcação, intervalo entre marcações, antecedência mínima, horizonte de pesquisa).

• Funciona apenas no motor de voz próprio da volai - num agente alojado na ElevenLabs, a definição é guardada e aguarda a mudança automática para o motor.
• O agente nunca diz o que está escrito no calendário - apenas se uma determinada hora está livre.
• O número de telefone de quem liga só é escrito no evento quando o agente o conhece; um número oculto significa que o evento não leva número de telefone.
• A mesma pesquisa de horários livres e a mesma marcação funcionam também fora de uma chamada, através de REST (POST .../availability, POST .../events) e de MCP (find_free_slots, create_calendar_event).

Fakturoid e ABRA Flexi

Esta página trata apenas de calendários. O Fakturoid e o ABRA Flexi ligam-se no mesmo local (list_integrations/GET /v1/integrations, a secção Dados e integrações do portal), mas a leitura de faturas e a sua utilização em Tarefas de lembrete tem um guia próprio, Faturas.

Sequência para um agente

A atualização de um evento tem sempre seis passos, por esta ordem:

• 1. list_integrations - calendários ligados e o respetivo integrationId.
• 2. list_calendars - os calendários dessa ligação e o respetivo calendarId.
• 3. list_calendar_events e depois get_calendar_event com o externalId devolvido como eventId - lê o evento e a sua sourceRevision atual.
• 4. propose_calendar_update - prepara a alteração, mas ainda não escreve nada.
• 5. Aprovação do utilizador - o agente mostra os valores originais e a proposta e só então continua.
• 6. confirm_calendar_update com confirm: true - só este passo escreve a alteração no Google/Apple.

Equivalentes REST: GET /v1/integrations, GET /v1/integrations/{id}/calendars, GET /v1/integrations/{id}/events, GET /v1/integrations/{id}/events/{eventId}, depois POST /v1/integrations/{id}/events/{eventId}/propose com {calendarId, sourceRevision, patch} e, após a aprovação, PATCH /v1/integrations/{id}/events/{eventId} com os mesmos valores e confirm: true.

Erros

• calendar_stale_revision - O evento foi alterado noutro local entretanto - leia-o de novo (get_calendar_event) e obtenha a aprovação da nova proposta.
• calendar_oauth_failed - A Google rejeitou o início de sessão - é preciso refazer a ligação no portal.
• calendar_unauthorized - A ligação deixou de ser válida (acesso revogado, token expirado) - volte a ligar a conta.
• calendar_confirmation_required - Uma escrita sem confirm: true - confirme a proposta apenas depois de o utilizador a ter aprovado.
• calendar_verification_failed - A escrita foi efetuada, mas uma nova leitura não corresponde ao que foi enviado - verifique o estado manualmente, não repita às cegas.

A tabela completa de todos os códigos encontra-se na secção Calendar da referência da API REST e na referência de erros do MCP.

Segurança

Os tokens de acesso a uma conta Google ou Apple nunca são devolvidos através de REST ou MCP e são armazenados cifrados. Envie uma appPassword da Apple por REST apenas quando o utilizador já a tiver guardado em segurança numa variável de ambiente ou num ficheiro por si indicado - nunca a peça em conversa nem a repita. Desligue uma integração no portal ou com o REST DELETE /v1/integrations/{id} após aprovação expressa do utilizador; o MCP não oferece a desativação.