> ## Documentation Index > Fetch the complete documentation index at: https://br.developers.hubspot.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Engajamentos | Chamadas > **[Run in Postman](https://app.getpostman.com/run-collection/dd75d149eaa15806754f)** > **Requisitos de escopo** Use a API de envolvimentos de chamadas para registrar e gerenciar chamadas nos registros do CRM e na [página do índice de chamadas](https://knowledge.hubspot.com/pt/records/view-and-filter-records). Você pode registrar chamadas [no HubSpot](https://knowledge.hubspot.com/pt/records/manually-log-activities-on-records) ou por meio da API de chamadas. Abaixo, aprenda os métodos básicos de gerenciamento de chamadas por meio da API. Para exibir todos os endpoints disponíveis e seus requisitos, verifique a [documentação de referência](https://br.developers.hubspot.com/docs/api-reference/crm-calls-v3/guide.md). ## Criar envolvimento de chamada Para criar um envolvimento de chamada, faça uma solicitação `POST` para `/crm/v3/objects/calls`. No corpo da solicitação, adicione detalhes da chamada em um objeto de **propriedades**. Você também pode adicionar um objeto de **associações** para associar sua nova chamada a um registro existente (por exemplo, contatos, empresas). ### Propriedades Veja abaixo uma lista de propriedades de chamada padrão do HubSpot que podem ser incluídas no objeto de propriedades. Também é possível criar propriedades personalizadas utilizando a [API de propriedades](https://br.developers.hubspot.com/docs/api-reference/crm-properties-v3/guide.md). | Campo | Descrição | | - | - | | `hs_timestamp` | Obrigatório. Este campo marca o tempo de criação da chamada e determina onde ela fica na linha do tempo do registro. Você pode usar um carimbo de data e hora do Unix em milissegundos ou no formato UTC. | | `hs_call_body` | A descrição da chamada, incluindo todas as notas que você deseja adicionar. | | `hs_call_callee_object_id` | O ID do registro do HubSpot associado à chamada. Este será o destinatário para chamadas de `OUTBOUND` ou o discador para chamadas de `INBOUND`. | | `hs_call_callee_object_type` | O tipo do objeto ao qual o registro associado à chamada pertence (por exemplo, especifica se o registro é um contato ou empresa). Este será o objeto do destinatário para chamadas de `OUTBOUND` ou o objeto do discador para chamadas de `INBOUND`. | | `hs_call_direction` | A direção da chamada da perspectiva do usuário da HubSpot. Se o usuário for o destinatário da chamada, a direção deve ser definida como `INBOUND`. Se o usuário iniciou a chamada, a direção deve ser definida como `OUTBOUND`. | | `hs_call_disposition` | O resultado da chamada. Para definir a disposição da chamada, você precisa usar o valor GUID interno. Se sua conta tiver configurado [resultados de chamadas personalizados](https://knowledge.hubspot.com/pt/calling/create-custom-call-and-meeting-outcomes), você poderá encontrar seus GUIDs de disposição usando [essa API](https://br.developers.hubspot.com/docs/api-reference/crm-communications-v3/guide.md#get-call-engagement-dispositions). Os rótulos de resultado padrão do HubSpot e seus valores internos são: | | `hs_call_duration` | A duração da chamada, em milissegundos. | | `hs_call_from_number` | O número de telefone de onde a chamada foi feita. | | `hs_call_recording_url` | A URL que armazena a gravação de chamadas. As URLS para arquivos .mp3 ou .wav podem ser reproduzidas em registros do CRM. Apenas HTTPS, URLs seguros serão aceitos. | | `hs_call_status` | O status da chamada. Os status são `BUSY`, `CALLING_CRM_USER`, `CANCELED`, `COMPLETED`, `CONNECTING`, `FAILED`, `IN_PROGRESS`, `NO_ANSWER`, `QUEUED` e `RINGING`. | | `hs_call_title` | O título da chamada. | | `hs_call_source` | A origem da chamada. Isso não é obrigatório, mas é necessário para utilizar o [pipeline de gravação e transcrições](https://br.developers.hubspot.com/docs/apps/legacy-apps/extensions/calling-extensions/recordings-and-transcriptions.md#log-a-call-with-your-app-s-endpoint-using-the-engagements-api). Se a propriedade estiver definida, ela deverá ser definida como `INTEGRATIONS_PLATFORM`. | | `hs_call_to_number` | O número de telefone que recebeu a chamada. | | `hubspot_owner_id` | O [ID do proprietário](https://br.developers.hubspot.com/docs/api-reference/crm-crm-owners-v3/guide.md) associado à chamada. Este campo determina o usuário listado como o criador da chamada na linha do tempo do registro. | | `hs_activity_type` | O tipo de chamada. As opções se baseiam nos [tipos de chamada definidos na sua conta da HubSpot.](https://knowledge.hubspot.com/pt/meetings-tool/how-do-i-create-and-use-call-and-meeting-types) | | `hs_attachment_ids` | Os Ids dos anexos da chamada. Vários IDs de anexo são separados por ponto e vírgula. | ### Associações Para criar e associar uma chamada a registros existentes, inclua um objeto de associações na solicitação. Por exemplo, para criar uma chamada e associá-la a um contato e a um ticket, o corpo da solicitação pode ser semelhante ao seguinte: ```json theme={null} // Example request body { "properties": { "hs_timestamp": "2021-03-17T01:32:44.872Z", "hs_call_title": "Support call", "hubspot_owner_id": "11349275740", "hs_call_body": "Resolved issue", "hs_call_duration": "3800", "hs_call_from_number": "(857) 829 5489", "hs_call_to_number": "(509) 999 9999", "hs_call_recording_url": "https://api.twilio.com/2010-04-01/Accounts/AC890b8e6fbe0d989bb9158e26046a8dde/Recordings/RE3079ac919116b2d22", "hs_call_status": "COMPLETED" }, "associations": [ { "to": { "id": 500 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 194 } ] }, { "to": { "id": 1234 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 220 } ] } ] } ``` No objeto de associações, você deve incluir o seguinte: | Campo | Descrição | | - | - | | `to` | O registro que deseja associar à chamada, especificado por seu valor de `id` exclusivo. | | `types` | O tipo de associação entre a chamada e o registro. Inclua `associationCategory` e `associationTypeId`. Os IDs de tipo de associação padrão são listados [aqui](https://br.developers.hubspot.com/docs/api-reference/crm-associations-v4/guide.md#association-type-id-values), ou você pode recuperar o valor de tipos de associação personalizados (ou seja, rótulos) por meio da [API de associações](https://br.developers.hubspot.com/docs/api-reference/crm-associations-v4/guide.md#retrieve-association-types). | Saiba mais sobre a criação de chamadas em lote na \[documentação de referência. ## Recuperar chamadas Você pode recuperar chamadas individualmente ou em massa. Saiba mais sobre a recuperação em lote na [documentação de referência](https://br.developers.hubspot.com/docs/api-reference/crm-calls-v3/guide.md#post-%2Fcrm%2Fv3%2Fobjects%2Fcalls%2Fbatch%2Fread). Para recuperar uma chamada individual pelo seu ID, faça uma solicitação `GET` para `/crm/v3/objects/calls/{callId}`. Você pode incluir os seguintes parâmetros na URL da solicitação: | Descrição | Parâmetro | | - | - | | `properties` | Uma lista separada por vírgulas das [propriedades](#call-properties-1) a serem retornadas. | | `associations` | Uma lista separada por vírgulas de tipos de objeto para recuperar IDs associados. Todas as associações especificadas que não existem não serão retornadas na resposta. Saiba mais sobre a [API de associações.](https://br.developers.hubspot.com/docs/api-reference/crm-associations-v4/guide.md) | Para solicitar uma lista de todas as chamadas, faça uma solicitação `GET` para `/crm/v3/objects/calls`. Você pode incluir os seguintes parâmetros na URL da solicitação: | Descrição | Parâmetro | | - | - | | `limit` | O número máximo de resultados a serem exibidos por página. | | `properties` | Uma lista separada por vírgulas das [propriedades](#call-properties-1) a serem retornadas. | Ao fazer uma solicitação bem-sucedida, a resposta incluirá o `callId` que você pode usar para recuperar, atualizar e excluir a chamada. ## Diferenciar mensagens de voz e chamadas gravadas Para chamadas gravadas e mensagens de voz, uma gravação é armazenada na propriedade `hs_call_recording_url`. Se sua conta tiver acesso a [chamada recebida](https://knowledge.hubspot.com/pt/calling/receive-calls-in-hubspot), para diferenciar entre chamadas concluídas e gravadas versus chamadas recebidas com uma mensagem de voz, inclua as seguintes propriedades na solicitação: `hs_call_status` e `hs_call_has_voicemail`. Se uma chamada tiver uma mensagem de voz, o valor `hs_call_status` será `missed` e o valor `hs_call_has_voicemail` será `true`. O valor `hs_call_has_voicemail` será `false` para uma chamada recebida, onde não foi deixado uma mensagem de voz, ou `null` se a chamada tiver um status diferente de perdida. ## Atualizar chamadas Você pode atualizar chamadas individualmente ou em massa. Para atualizar uma chamada individual pelo seu ID, faça uma solicitação `PATCH` para `/crm/v3/objects/calls/{callId}`. No corpo da solicitação, inclua as propriedades da chamada que deseja atualizar: ```json theme={null} //Example PATCH request to https://api.hubspot.com/crm/v3/objects/calls/{callID} { "properties": { "hs_timestamp": "2021-03-17T01:32:44.872Z", "hs_call_title": "Discovery call", "hubspot_owner_id": "11349275740", "hs_call_body": " Decision maker out, will call back tomorrow", "hs_call_duration": "3800", "hs_call_from_number": "(857) 829 5489", "hs_call_to_number": "(509) 999 9999", "hs_call_recording_url": "https://api.twilio.com/2010-04-01/Accounts/AC890b8e6fbe0d989bb9158e26046a8dde/Recordings/RE3079ac919116b2d22", "hs_call_status": "COMPLETED" } }' ``` O HubSpot ignorará valores para propriedades somente leitura e inexistentes. Para limpar um valor de propriedade, passe uma string vazia para a propriedade no corpo da solicitação. Saiba mais sobre a atualização em lotes na [documentação de referência](https://br.developers.hubspot.com/docs/api-reference/crm-calls-v3/guide.md#post-%2Fcrm%2Fv3%2Fobjects%2Fcalls%2Fbatch%2Fupdate). ### Associar chamadas existentes a registros Para associar uma chamada a registros, como um contato e suas empresas associadas, faça uma solicitação `PUT` para `/crm/v3/objects/calls/{callId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}`. A URL da solicitação contém os campos a seguir: | Campo | Descrição | | - | - | | `callId` | O ID da chamada. | | `toObjectType` | O tipo de objeto ao qual você deseja associar a chamada (por exemplo, contato ou empresa) | | `toObjectId` | O ID do registro ao qual você deseja associar a chamada. | | `associationTypeId` | Um identificador exclusivo para indicar o tipo de associação entre a chamada e o outro objeto. O ID pode ser representado numericamente ou em maiúsculas (por exemplo, `call_to_contact`). Você pode recuperar o valor por meio da [API de associações](https://br.developers.hubspot.com/docs/api-reference/crm-associations-v3/guide.md). | Por exemplo, a URL da sua solicitação pode ser parecida com o seguinte: `https://api.hubspot.com/crm/v3/objects/calls/17591596434/associations/contact/104901/194` ### Remover uma associação Para remover uma associação entre uma chamada e um registro, faça uma solicitação `DELETE` para o mesmo URL acima: `/crm/v3/objects/calls/{callId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}` ## Fixar uma chamada em um registro Você pode [fixar uma chamada](https://knowledge.hubspot.com/pt/records/pin-an-activity-on-a-record) em um registro para que permaneça no topo da linha do tempo do registro. A chamada já deve estar associada ao registro antes da fixação e você só pode fixar uma atividade por registo. Para fixar uma chamada, inclua o `id` da chamada no campo `hs_pinned_engagement_id` ao criar ou atualizar um registro por meio das APIs de objeto. Saiba mais sobre como usar as APIs de [empresas,](https://br.developers.hubspot.com/docs/api-reference/crm-companies-v3/guide.md#pin-an-activity-on-a-company-record)[contatos](https://br.developers.hubspot.com/docs/api-reference/crm-contacts-v3/guide.md#pin-an-activity-on-a-contact-record), [negócios](https://br.developers.hubspot.com/docs/api-reference/crm-deals-v3/guide.md#pin-an-activity-on-a-deal-record), [tickets](https://br.developers.hubspot.com/docs/api-reference/crm-tickets-v3/guide.md#pin-an-activity-on-a-ticket-record) e [objetos personalizados](https://br.developers.hubspot.com/docs/api-reference/crm-custom-objects-v3/guide.md). ## Excluir chamadas Você pode excluir chamadas individualmente ou em massa, o que adicionará a chamada à lixeira no HubSpot. Você pode [restaurar posteriormente a chamada da linha do tempo do registro](https://knowledge.hubspot.com/pt/records/restore-deleted-activity-in-a-record). Para excluir uma chamada individual pelo seu ID, faça uma solicitação`DELETE` para `/crm/v3/objects/calls/{callId}`. Saiba mais sobre a exclusão de chamadas na \[documentação de referência.