Última modificação: 22 de agosto de 2025

Run in Postman

 Use a API de envolvimentos de chamadas para registrar e gerenciar chamadas nos registros do CRM e na página do índice de chamadas. Você pode registrar chamadas no HubSpot 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.

​
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.
CampoDescrição
hs_timestampObrigató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_bodyA descrição da chamada, incluindo todas as notas que você deseja adicionar.
hs_call_callee_object_idO 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_typeO 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_directionA 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_dispositionO 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, você poderá encontrar seus GUIDs de disposição usando essa API. Os rótulos de resultado padrão do HubSpot e seus valores internos são:
  • Ocupado: 9d9162e7-6cf3-4944-bf63-4dff82258764
  • Conectado: f240bbac-87c9-4f6e-bf70-924b57d47db7
  • Deixou mensagem ativa: a4c4c377-d246-4b32-a13b-75a56a4cd0ff
  • Deixou mensagem de voz: b2cf5968-551e-4856-9783-52b3da59a7d0
  • Sem resposta: 73a0d17f-1163-4015-bdd5-ec830791da20
  • Número errado: 17b47fee-58de-441e-a44c-c6300d46f273
hs_call_durationA duração da chamada, em milissegundos.
hs_call_from_numberO número de telefone de onde a chamada foi feita.
hs_call_recording_urlA 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_statusO status da chamada. Os status são BUSY, CALLING_CRM_USER, CANCELED, COMPLETED, CONNECTING, FAILED, IN_PROGRESS, NO_ANSWER, QUEUED e RINGING.
hs_call_titleO título da chamada.
hs_call_sourceA origem da chamada. Isso não é obrigatório, mas é necessário para utilizar o pipeline de gravação e transcrições. Se a propriedade estiver definida, ela deverá ser definida como INTEGRATIONS_PLATFORM.
hs_call_to_numberO número de telefone que recebeu a chamada.
hubspot_owner_idO ID do proprietário associado à chamada. Este campo determina o usuário listado como o criador da chamada na linha do tempo do registro.
hs_activity_typeO tipo de chamada. As opções se baseiam nos tipos de chamada definidos na sua conta da HubSpot.
hs_attachment_idsOs 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: 
// 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:
CampoDescrição
toO registro que deseja associar à chamada, especificado por seu valor de id exclusivo.
typesO 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, ou você pode recuperar o valor de tipos de associação personalizados (ou seja, rótulos) por meio da API de associações.
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. 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çãoParâmetro
propertiesUma lista separada por vírgulas das propriedades a serem retornadas.
associationsUma 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.
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çãoParâmetro
limitO número máximo de resultados a serem exibidos por página.
propertiesUma lista separada por vírgulas das propriedades 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, 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: 
//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.

​
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:
CampoDescrição
callIdO ID da chamada.
toObjectTypeO tipo de objeto ao qual você deseja associar a chamada (por exemplo, contato ou empresa)
toObjectIdO ID do registro ao qual você deseja associar a chamada.
associationTypeIdUm 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.
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 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,contatos, negócios, tickets e objetos personalizados.

​
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. Para excluir uma chamada individual pelo seu ID, faça uma solicitaçãoDELETE para /crm/v3/objects/calls/{callId}. Saiba mais sobre a exclusão de chamadas na [documentação de referência.