> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Cal.com ## Visão geral Conecte seus agentes de IA da ElevenLabs ao [Cal.com](https://cal.com) para gerenciar agendamentos e reservas no calendário. Essa integração permite que seus agentes verifiquem a disponibilidade, agendem compromissos, cancelem ou remarquem reuniões e consultem reservas existentes por meio de conversas naturais. ## Recursos | Recurso | Suporte | | --------------------------- | ------------------------------------------------------- | | Modo de retenção zero (ZRM) | Não compatível | | Anexos em ferramentas | Não compatível — as ferramentas operam apenas com texto | ## Configuração Esta integração usa uma **chave de API do Cal.com** para autenticação (não um app OAuth). #### Gere uma chave de API no Cal.com Acesse **Settings > Developer > API Keys** na sua conta do Cal.com e clique em **New**. Copie a chave gerada imediatamente — ela não será exibida novamente. #### Use uma chave de produção O Cal.com gera dois tipos de chave — chaves de teste (que começam com `cal_`) e chaves de produção (que começam com `cal_live_`). Use uma **chave de produção** para que seu agente possa acessar dados reais do calendário. #### Conecte na ElevenLabs Na configuração da integração da ElevenLabs, cole sua chave de API do Cal.com no campo **API Key**. ## Demonstração > **Note** > > Esta demonstração usa ferramentas de webhook legadas. Se você usa a integração nativa do Cal.com, as ferramentas são > configuradas automaticamente — não é necessária nenhuma configuração manual de webhook. ## Como funciona O agente agenda reuniões usando chamadas de ferramentas para seguir as etapas do processo de reserva. As abas abaixo mostram um resumo geral e o prompt detalhado do sistema. #### Visão geral #### Consulta inicial e detalhes da reunião O agente pergunta o objetivo da reunião, a data e o horário preferidos e a duração para reunir informações de agendamento. #### Verificar disponibilidade no calendário O agente verifica a disponibilidade no calendário: * Usa a ferramenta `get_available_slots` para buscar horários disponíveis. * Confere se o horário solicitado está disponível. * Sugere alternativas se o horário solicitado não estiver disponível. * Confirma o horário selecionado com a pessoa que ligou. #### Coleta de informações de contato Quando um horário é definido, o agente: * Coleta e valida o nome completo do participante. * Verifica se o endereço de e-mail está correto. * Confirma as informações de fuso horário. * Reúne todos os campos adicionais exigidos para o tipo de evento do Cal.com. #### Criação da reunião O agente: * Chama a ferramenta `book_meeting` após verificar todas as informações. * Segue a estrutura do modelo de reserva. * Confirma a criação da reunião com o participante. * Informa que ele receberá um convite de calendário. #### Prompt detalhado do sistema ``` You are a helpful receptionist responsible for scheduling meetings using the Cal.com integration. Be friendly, precise, and concise. Begin by briefly asking for the purpose of the meeting and the caller's preferred date and time. Then, ask about the desired meeting duration (15, 30, or 60 minutes), and wait for the user's response before proceeding. Once you have the meeting details, say you will check calendar availability: - Call get_available_slots with the appropriate date range - Verify if the requested time slot is available - If not available, suggest alternative times from the available slots - Continue until a suitable time is agreed upon After confirming a time slot, gather the following contact details: - The attendee's full name - A valid email address. Note that the email address is transcribed from voice, so ensure it is formatted correctly. - The attendee's time zone (in 'Continent/City' format like 'America/New_York') - Read the email back to the caller to confirm accuracy Once all details are confirmed, explain that you will create the meeting. Create the meeting by using the book_meeting tool with the following parameters: - start: The agreed meeting time in ISO 8601 format - eventTypeId: The appropriate ID based on the meeting duration (15min: 1351800, 30min: 1351801, 60min: 1351802) - attendee: An object containing the name, email, and timeZone Thank the attendee and inform them they will receive a calendar invitation shortly. Clarifications: - Do not inform the user that you are formatting the email; simply do it. - If the caller asks you to proceed with booking, do so with the existing information. Guardrails: - Do not share any internal IDs or API details with the caller. - If booking fails, check for formatting issues in the email or time conflicts. ``` ## Configuração manual de webhook > **Note** > > Se você usa a integração nativa do Cal.com, as ferramentas são configuradas automaticamente. As etapas abaixo > se aplicam apenas à configuração manual de webhook. #### Armazene seu segredo do Cal.com Armazene sua chave de API com segurança antes de fazer solicitações autenticadas. Gere uma nova [chave de API do Cal.com](https://cal.com/docs/api-reference/v1/introduction#get-your-api-keys) caso ainda não tenha uma. A API do Cal.com espera o seguinte cabeçalho de autenticação: **`Estrutura do cabeçalho de solicitação do Cal`** ```plaintext Estrutura do cabeçalho de solicitação do Cal 'Authorization': 'Bearer YOUR_API_KEY' ``` Armazene a chave no armazenamento de segredos do agente para mantê-la segura e acessível ao fazer solicitações. > **Warning** > > Para corresponder à estrutura de autenticação esperada pelo Cal.com, lembre-se de adicionar `Bearer ` antes da chave de API ao criar o segredo. ![Segredos de ferramentas](/docs/_fern-img/5ffae070945a86b74975cd9b56679c2bb76f0ce70d05fe7b10e8e5dff6ddd630.webp) #### Adicione ferramentas ao agente Habilite reservas no calendário criando duas ferramentas: 1. **`get_available_slots`**: Quando um usuário pergunta *"Louis está disponível às 10h30 na terça-feira?"*, o agente usa o [endpoint "Get available slots" do Cal.com](https://cal.com/docs/api-reference/v2/slots/find-out-when-is-an-event-type-ready-to-be-booked) para verificar horários disponíveis. 2. **`book_meeting`**: Depois de identificar um horário adequado, o agente agenda a reunião usando o [endpoint "Create a booking" do Cal.com](https://cal.com/docs/api-reference/v2/bookings/create-a-booking#create-a-booking). Acesse a seção **Tools** do painel e selecione **Add Tool**. Escolha **Webhook** como tipo de ferramenta e preencha as seções a seguir: #### Ferramenta 1: get_available_slots #### Configuração Metadados usados pelo agente para determinar quando a ferramenta deve ser chamada: | Campo | Valor | | --------- | --------------------------------------------------------------------------------- | | Nome | get_available_slots | | Descrição | Esta ferramenta verifica se um determinado horário está disponível no calendário. | | Método | GET | | URL | [https://api.cal.com/v2/slots](https://api.cal.com/v2/slots) | #### Cabeçalhos Corresponde aos cabeçalhos de solicitação definidos [aqui](https://cal.com/docs/api-reference/v2/slots/get-available-slots#get-available-slots): | Tipo | Nome | Valor | | ------- | --------------- | -------------------------------------- | | Segredo | Authorization | Selecione a chave secreta criada acima | | String | cal-api-version | 2024-09-04 | #### Parâmetros de consulta Corresponde aos parâmetros de consulta da solicitação definidos [aqui](https://cal.com/docs/api-reference/v2/slots/get-available-slots#get-available-slots): | Tipo de dado | Identificador | Obrigatório | Descrição | | ------------ | ------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- | | string | start | Sim | Data/hora de início (UTC) a partir da qual buscar horários, por exemplo, '2024-08-13T09:00:00Z'. | | string | end | Sim | Data/hora de término (UTC) até a qual buscar horários, por exemplo, '2024-08-13T17:00:00Z'. | | string | eventTypeId | Sim | O ID do tipo de evento reservado. Se for 15 minutos, retorne abc. Se for 30 minutos, retorne def. Se for 60 minutos, retorne xyz. | #### Ferramenta 2: book_meeting #### Configuração Metadados usados pelo agente para determinar quando a ferramenta deve ser chamada: | Campo | Valor | | --------- | -------------------------------------------------------------------------------- | | Nome | book_meeting | | Descrição | Esta ferramenta agenda uma reunião no calendário após a definição de um horário. | | Método | POST | | URL | [https://api.cal.com/v2/bookings](https://api.cal.com/v2/bookings) | #### Cabeçalhos Corresponde aos cabeçalhos de solicitação definidos [aqui](https://cal.com/docs/api-reference/v2/bookings/create-a-booking#create-a-booking): | Tipo | Nome | Valor | | ------- | --------------- | -------------------------------------- | | Segredo | Authorization | Selecione a chave secreta criada acima | | String | cal-api-version | 2024-08-13 | #### Parâmetros do corpo Corresponde aos parâmetros do corpo da solicitação definidos [aqui](https://cal.com/docs/api-reference/v2/bookings/create-a-booking#create-a-booking): | Identificador | Tipo de dado | Obrigatório | Descrição | | ------------- | ------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------- | | start | String | Sim | O horário de início da reserva no formato ISO 8601 e no fuso horário UTC, por exemplo, '2024-08-13T09:00:00Z'. | | eventTypeId | Number | Sim | O ID do tipo de evento reservado. Se for 15 minutos, retorne abc. Se for 30 minutos, retorne def. Se for 60 minutos, retorne xyz. | | attendee | Object | Sim | Os dados do participante. Você deve coletar esses campos do usuário. | > **Note** > > O `eventTypeId` deve corresponder aos tipos de evento disponíveis no Cal. Chame > [este](https://cal.com/docs/api-reference/v1/event-types/find-all-event-types#find-all-event-types) > endpoint para obter uma lista dos tipos de evento da sua conta (ou crie outra ferramenta que faça isso > automaticamente). **Objeto do participante:** | Identificador | Tipo de dado | Obrigatório | Descrição | | ------------- | ------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------- | | name | String | Sim | O nome completo da pessoa que está agendando a reunião. | | email | String | Sim | O endereço de e-mail da pessoa que está agendando a reunião. | | timeZone | String | Sim | O fuso horário da pessoa que ligou. Deve estar no formato 'Continente/Cidade', como 'Europe/London' ou 'America/New_York'. | > **Success** > > Teste o agente pressionando o botão **Test AI agent**. Ajuste o prompt do sistema conforme necessário. #### Adicione reconhecimento de data e hora Por padrão, o agente não sabe a data ou hora atual. Use uma das seguintes abordagens: 1. **Crie uma ferramenta para obter a hora**: adicione uma ferramenta que busque a data e a hora atuais. 2. **Substituições**: use o recurso de [substituições](/docs/pt/eleven-agents/customization/personalization/overrides) para inserir a data e a hora atuais no prompt do sistema no início de cada conversa. ## Considerações de segurança * Use endpoints HTTPS para todas as chamadas de webhook. * Armazene valores confidenciais como segredos usando o Gerenciador de Segredos da ElevenLabs. * Valide se todos os cabeçalhos de autorização seguem o formato exigido (`Bearer YOUR_API_KEY`). * Nunca exponha IDs de tipos de evento ou detalhes da API às pessoas que ligam. ## Links úteis * [Documentação da API do Cal.com](https://cal.com/docs/api-reference/v2/introduction) * [Guia de chaves de API do Cal.com](https://cal.com/blog/where-is-my-api-key-and-what-can-it-do) * [Visão geral das ferramentas da ElevenLabs](/docs/pt/eleven-agents/customization/tools/server-tools)