Pular para o conteúdo

Cal.com

Cal.com

O Cal.com é uma plataforma open-source de agendamento que simplifica a coordenação de reuniões por meio de páginas de reserva compartilháveis, sincronização de calendários e gerenciamento de disponibilidade. Com a integração no SquadOS, seus agentes podem criar, cancelar e reagendar reuniões, consultar horários disponíveis, gerenciar tipos de evento e configurar agendas de disponibilidade — tudo de forma programática, sem intervenção manual.

Esta ferramenta suporta dois modos de autenticação: OAuth 2.0 (OAUTH2) e chave de API (API_KEY).

Você vai precisar dos seguintes campos (modo API_KEY):

CampoObrigatórioDescrição
api_keySimChave de API gerada no painel do Cal.com em Settings → Developer → API Keys.

Para o modo OAuth 2.0, nenhum campo manual é necessário — o fluxo de autorização é concluído na página segura da Composio.

Para usar o modo chave de API:

  1. Acesse app.cal.com e faça login na sua conta.
  2. Clique em Settings no menu lateral esquerdo.
  3. Acesse Developer → API Keys.
  4. Clique em Add para gerar uma nova chave.
  5. Dê um nome à chave (ex.: “SquadOS”) e defina a data de expiração desejada.
  6. Copie o valor gerado — ele não será exibido novamente.
  1. Acesse Ferramentas no menu lateral (/admin/tools).
  2. Abra a aba Disponíveis e procure por Cal.com.
  3. Clique no card para abrir o modal de detalhes e em Conectar.
  4. Você é levado para a página de conexão segura hospedada pela Composio, onde autoriza o acesso via OAuth 2.0 ou informa a chave de API obtida acima.
  5. Ao concluir, você volta para o SquadOS com a conta conectada e a ferramenta disponível para os agentes. (Detalhes do fluxo em Ferramentas da Organização.)

CAL_POST_NEW_BOOKING_REQUEST

Cria uma nova reserva para um tipo de evento em um horário de início especificado. Use para agendar uma reunião com um usuário do Cal.com. Pré-requisitos: (1) obter um ID de tipo de evento válido via CAL_LIST_EVENT_TYPES; (2) encontrar um horário disponível via CAL_GET_AVAILABLE_SLOTS_INFO; (3) fornecer nome e e-mail do participante no objeto responses. A reserva será criada com status ACCEPTED se não exigir confirmação, ou PENDING se o tipo de evento exigir aprovação do anfitrião.

NomeTipoObrigatórioDescrição
startstringSimData e hora de início no formato ISO 8601 em UTC (ex.: ‘2024-09-15T10:00:00Z’). Deve ser um horário disponível retornado por CAL_GET_AVAILABLE_SLOTS_INFO.
languagestringSimCódigo de idioma ISO 639-1 para comunicações com o participante (ex.: ‘pt’ para português, ‘en’ para inglês).
timeZonestringSimIdentificador de fuso horário IANA para o participante (ex.: ‘America/Sao_Paulo’, ‘America/New_York’).
responsesobjectSimObjeto com dados do participante. Chaves obrigatórias: name (nome completo) e email (endereço de e-mail válido).
eventTypeIdintegerNãoID numérico único do tipo de evento a ser reservado. Obrigatório se eventTypeSlug não for informado.
eventTypeSlugstringNãoSlug do tipo de evento. Quando usado, deve ser combinado com username ou teamSlug.
guestsarrayNãoLista de endereços de e-mail de convidados adicionais.
locationobjectNãoObjeto de localização correspondente a uma das localizações configuradas no tipo de evento.
metadataobjectNãoMetadados customizados chave-valor para rastreamento ou análises. Máximo de 50 chaves.
lengthInMinutesintegerNãoDuração do evento em minutos. Usar apenas quando o tipo de evento suportar múltiplas durações selecionáveis.
bookingFieldsResponsesobjectNãoRespostas a campos de reserva personalizados definidos no tipo de evento. Obrigatório se o tipo de evento tiver campos obrigatórios customizados.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_FETCH_ALL_BOOKINGS

Busca a lista de reservas do usuário autenticado, com filtros opcionais por status, participante, intervalo de datas ou IDs de evento/equipe, além de suporte a paginação e ordenação.

NomeTipoObrigatórioDescrição
skipintegerNãoNúmero de reservas a pular no início dos resultados (para paginação).
takeintegerNãoNúmero máximo de reservas a retornar (para paginação).
statusarrayNãoFiltrar reservas por status. Ex.: ["upcoming", "past"].
teamIdintegerNãoFiltrar por ID de uma equipe da qual o usuário é membro.
afterStartstringNãoFiltrar reservas com início após esta data/hora ISO 8601.
beforeEndstringNãoFiltrar reservas com término antes desta data/hora ISO 8601.
eventTypeIdintegerNãoFiltrar por ID de tipo de evento pertencente ao usuário.
attendeeEmailstringNãoFiltrar pelo endereço de e-mail exato de um participante.
attendeeNamestringNãoFiltrar pelo nome de um participante.
sortStartstringNãoOrdenar resultados pelo horário de início (asc ou desc).
sortEndstringNãoOrdenar resultados pelo horário de término (asc ou desc).
sortCreatedstringNãoOrdenar resultados pela data de criação (asc ou desc).
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_RETRIEVE_BOOKING_DETAILS_BY_UID

Busca todos os detalhes de uma reserva existente, identificada pelo seu bookingUid.

NomeTipoObrigatórioDescrição
bookingUidstringSimIdentificador único (UID) da reserva.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_RESCHEDULE_BOOKING_BY_UID

Reagenda uma reserva existente (identificada pelo bookingUid) para um novo horário. Requer o UID da reserva e o novo horário de início no formato ISO 8601. Opcionalmente, pode-se fornecer o motivo do reagendamento e o e-mail da pessoa que está reagendando.

NomeTipoObrigatórioDescrição
bookingUidstringSimIdentificador único (UID) da reserva a ser reagendada.
startstringSimNovo horário de início no formato ISO 8601 com fuso horário (ex.: ‘2024-08-13T10:00:00Z’).
rescheduledBystringNãoE-mail da pessoa que está reagendando. Se for o e-mail do proprietário do tipo de evento, a reserva será confirmada automaticamente.
reschedulingReasonstringNãoMotivo do reagendamento.
emailVerificationCodestringNãoObrigatório quando o tipo de evento tem verificação de e-mail habilitada.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_CANCEL_BOOKING_VIA_UID

Cancela uma reserva ativa do Cal.com usando seu identificador único (UID).

NomeTipoObrigatórioDescrição
bookingUidstringSimIdentificador único (UID) da reserva a ser cancelada.
cancellationReasonstringNãoMotivo do cancelamento. Recomendado para comunicação clara com o participante.
seatUidstringNãoApenas para reservas com assentos: UID do assento específico a cancelar.
cancelSubsequentBookingsbooleanNãoPara reservas recorrentes: se verdadeiro, cancela esta reserva e todas as recorrências subsequentes.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_CONFIRM_BOOKING_BY_UID

Confirma uma reserva existente pelo bookingUid, desde que esteja em um estado que permita confirmação (por exemplo, não cancelada ou já confirmada). Finaliza a reserva sem modificar seus detalhes.

NomeTipoObrigatórioDescrição
bookingUidstringSimIdentificador único (UID) da reserva a ser confirmada.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_DECLINE_BOOKING_WITH_REASON

Recusa uma reserva pendente usando seu bookingUid, opcionalmente com um motivo. A ação é irreversível e se aplica apenas a reservas aguardando confirmação.

NomeTipoObrigatórioDescrição
bookingUidstringSimIdentificador único (UID) da reserva a ser recusada.
reasonstringNãoMotivo fornecido pelo anfitrião para recusar a reserva. Recomendado para comunicação clara com o participante.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_EDIT_BOOKING_BY_ID

Edita uma reserva existente pelo seu ID. Use para atualizar detalhes como título, descrição, status ou horário.

NomeTipoObrigatórioDescrição
idintegerSimID da reserva a editar.
titlestringNãoTítulo do evento da reserva.
descriptionstringNãoDescrição da reunião.
statusstringNãoStatus da reserva. Valores possíveis: ACCEPTED, PENDING, CANCELLED, REJECTED.
startstringNãoHorário de início do evento no formato ISO 8601.
endstringNãoHorário de término do evento no formato ISO 8601.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_MARK_BOOKING_ABSENT_FOR_UID

Marca o anfitrião e/ou participantes especificados como ausentes em uma reserva existente. Normalmente usado após um evento agendado para registrar faltas.

NomeTipoObrigatórioDescrição
bookingUidstringSimIdentificador único (UID) da reserva.
hostbooleanNãoSe verdadeiro, marca o anfitrião como ausente. Se nulo ou omitido, o status de presença do anfitrião não é alterado.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_CHECK_CALENDAR_VERSION2

Recupera a disponibilidade livre/ocupado de um calendário especificado para auxiliar no agendamento, sem revelar detalhes dos eventos.

NomeTipoObrigatórioDescrição
calendarstringSimTipo de calendário para verificar disponibilidade. Deve ser um dos provedores de calendário suportados.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_GET_AVAILABLE_SLOTS_INFO

Recupera os horários disponíveis para agendamento, considerando reservas existentes e disponibilidade configurada, com base em um intervalo de datas e tipo de evento.

NomeTipoObrigatórioDescrição
eventTypeIdintegerSimIdentificador numérico único do tipo de evento.
startTimestringSimData e hora de início em UTC (formato ISO 8601) a partir da qual buscar horários disponíveis.
endTimestringSimData e hora de término em UTC (formato ISO 8601) até a qual buscar horários disponíveis. Deve ser posterior a startTime.
timeZonestringNãoIdentificador de fuso horário IANA (ex.: ‘America/Sao_Paulo’) para calcular e retornar os horários disponíveis.
durationintegerNãoDuração desejada dos horários em minutos. Normalmente usada para eventos dinâmicos onde a duração não é fixa.
slotFormatstringNãoFormato dos horários retornados. Use range para início e fim de cada slot; use time para apenas o horário de início.
usernameListarrayNãoObrigatório para tipos de evento dinâmicos ou coletivos, para especificar os usuários cuja disponibilidade deve ser considerada.
rescheduleUidstringNãoUID de uma reserva existente sendo reagendada. Fornecê-lo ajuda a encontrar slots adequados para o contexto de reagendamento.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_RESERVE_SLOT_FOR_EVENT

Reserva temporariamente um horário disponível para um tipo de evento existente. Útil para horários de alta demanda, evitando reservas duplicadas enquanto o usuário conclui o agendamento.

NomeTipoObrigatórioDescrição
eventTypeIdintegerSimIdentificador único do tipo de evento para o qual o horário está sendo reservado.
slotUtcStartDatestringSimData e hora de início do slot a reservar, em UTC (formato ISO 8601).
slotUtcEndDatestringSimData e hora de término do slot a reservar, em UTC (formato ISO 8601).
bookingUidstringNãoIdentificador opcional, normalmente usado para eventos com assentos.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_LIST_EVENT_TYPES

Recupera os tipos de evento do Cal.com, com filtros opcionais por username, múltiplos usernames ou detalhes da organização (orgSlug ou orgId).

NomeTipoObrigatórioDescrição
usernamestringNãoNome de usuário cujos tipos de evento devem ser recuperados. Obrigatório se eventSlug for informado.
eventSlugstringNãoSlug de um tipo de evento específico a recuperar. Se informado, username também deve ser fornecido.
usernamesstringNãoString com nomes de usuário separados por vírgula para recuperar tipos de evento dinâmicos de múltiplos usuários (ex.: ‘alice,bob’).
orgIdintegerNãoID único da organização.
orgSlugstringNãoSlug da organização.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_RETRIEVE_EVENT_TYPE_BY_ID

Recupera todos os detalhes de um tipo de evento específico do Cal.com pelo seu ID único. Ação somente de leitura — não retorna eventos ou reservas associadas.

NomeTipoObrigatórioDescrição
eventTypeIdstringSimIdentificador único do tipo de evento. Valor numérico ou UUID encontrado na URL das configurações do tipo de evento.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_EDIT_EVENT_TYPE_BY_ID

Edita um tipo de evento existente do Cal.com pelo ID. Use para atualizar configurações como título, descrição, duração, localizações ou configurações de reserva.

NomeTipoObrigatórioDescrição
idintegerSimID do tipo de evento a editar.
titlestringNãoTítulo do tipo de evento.
slugstringNãoSlug único para o tipo de evento.
hiddenbooleanNãoSe o tipo de evento deve ser ocultado da sua página pública de reservas.
priceintegerNãoPreço da reserva do tipo de evento.
hostsarrayNãoLista de anfitriões para tipos de evento de equipe.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_DELETE_EVENT_TYPE_BY_ID

Exclui permanentemente um tipo de evento existente pelo seu ID. A operação é irreversível e invalida os links de agendamento associados; reservas existentes não são afetadas.

NomeTipoObrigatórioDescrição
eventTypeIdintegerSimIdentificador numérico único do tipo de evento a ser excluído.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_RETRIEVE_SCHEDULES_LIST

Recupera todas as agendas de disponibilidade do usuário autenticado no Cal.com. Cada agenda inclui blocos de horário, fuso horário e se é a agenda padrão. Retorna lista vazia se nenhuma agenda estiver configurada.

NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_FETCH_SCHEDULE_BY_ID

Busca todos os detalhes de uma agenda específica usando seu scheduleId.

NomeTipoObrigatórioDescrição
scheduleIdintegerSimIdentificador único da agenda a recuperar.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_CREATE_USER_AVAILABILITY_SCHEDULE

Cria uma agenda de disponibilidade no Cal.com, definindo nome, fuso horário, disponibilidade semanal recorrente e substituições para datas específicas. Se isDefault for verdadeiro, esta agenda substitui a agenda padrão existente.

NomeTipoObrigatórioDescrição
namestringSimNome descritivo da agenda (ex.: ‘Horário de Trabalho’, ‘Agenda de Férias’).
timeZonestringSimIdentificador de fuso horário IANA (ex.: ‘America/Sao_Paulo’). Essencial para cálculo correto da disponibilidade.
isDefaultbooleanSimDefine esta como a agenda padrão do usuário se verdadeiro, substituindo a existente. Cada usuário deve ter exatamente uma agenda padrão.
availabilityarrayNãoLista de objetos de disponibilidade definindo dias ativos e horários. Se omitido, aplica o padrão (seg-sex, 09:00–17:00 no fuso da agenda).
overridesarrayNãoLista de objetos de substituição para exceções de datas específicas (ex.: feriados). As substituições têm precedência sobre a disponibilidade semanal.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_EDIT_AVAILABILITY_BY_ID

Edita uma disponibilidade existente pelo ID no Cal.com. Use para atualizar dias, horário de início, horário de término ou a associação com uma agenda.

NomeTipoObrigatórioDescrição
idintegerSimID da disponibilidade a editar.
daysarrayNãoArray de inteiros representando dias da semana (0=domingo, 1=segunda, 2=terça, 3=quarta, 4=quinta, 5=sexta, 6=sábado). Apenas valores 0–6 são válidos.
startTimestringNãoHorário de início no formato ISO 8601 (ex.: ‘1970-01-01T10:00:00.000Z’). A parte de data é ignorada; apenas o horário é usado.
endTimestringNãoHorário de término no formato ISO 8601 (ex.: ‘1970-01-01T16:00:00.000Z’). A parte de data é ignorada; apenas o horário é usado.
scheduleIdintegerNãoID da agenda à qual esta disponibilidade está associada.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_DELETE_SCHEDULE_BY_ID

Exclui permanentemente uma agenda específica usando seu identificador único.

NomeTipoObrigatórioDescrição
scheduleIdintegerSimIdentificador único da agenda a ser excluída.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_RETRIEVE_MY_INFORMATION

Recupera as informações de perfil principal do usuário autenticado (ex.: nome, e-mail, fuso horário). Não recupera dados relacionados como eventos de calendário ou agendas.

NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_GET_TEAMS_LIST

Recupera todas as equipes às quais o usuário pertence, incluindo nomes e membros.

NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_ADD_ATTENDEE

Cria um novo participante para uma reserva existente no Cal.com. Use quando precisar adicionar um participante adicional a um evento agendado.

NomeTipoObrigatórioDescrição
bookingIdintegerSimIdentificador único da reserva à qual o participante será adicionado.
namestringSimNome completo do participante.
emailstringSimEndereço de e-mail do participante. Deve ser um formato de e-mail válido.
timeZonestringSimFuso horário IANA do participante (ex.: ‘America/Sao_Paulo’, ‘Europe/London’).
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_LIST_ATTENDEES

Recupera todos os participantes do Cal.com. Use quando precisar obter a lista completa de participantes em todas as reservas.

NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_FETCH_EVENT_TYPE_DETAILS

Busca todas as configurações de um tipo de evento de equipe, identificado por orgId, teamId e eventTypeId. Ação somente de leitura.

NomeTipoObrigatórioDescrição
orgIdintegerSimIdentificador único da organização à qual o tipo de evento pertence.
teamIdintegerSimIdentificador único da equipe, dentro da organização especificada.
eventTypeIdintegerSimIdentificador único do tipo de evento específico.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.

CAL_REASSIGN_BOOKING_TO_ANOTHER_USER

Reatribui uma reserva existente a um usuário especificado. O proprietário da reserva deve estar autorizado a realizar a reatribuição.

NomeTipoObrigatórioDescrição
bookingUidstringSimIdentificador único (UID) da reserva a ser reatribuída.
reasonstringNãoTexto explicando o motivo da reatribuição. Útil para rastreamento ou comunicação interna.
NomeTipoObrigatórioDescrição
datastringSimDados retornados pela execução da ação.
errorstringNãoMensagem de erro caso a execução tenha falhado.
successfulbooleanSimIndica se a ação foi executada com sucesso.