Engajamentos | Chamadas

Run in Postman

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. 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.

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, 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_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. 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 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.
`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:

// 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, 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ção	Parâmetro
`properties`	Uma lista separada por vírgulas das propriedades 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.

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 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:

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.

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.

Conta e configurações

Gerenciamento de aplicativo

Autenticação

Automação

CMS

Preferências de comunicação

Conversas

CRM

Data Studio

Eventos

Arquivos

Marketing

Reuniões

Receita

Webhooks

Diário de Webhooks

Engajamentos | Chamadas

Run in Postman

Criar envolvimento de chamada

Propriedades

Associações

Recuperar chamadas

Diferenciar mensagens de voz e chamadas gravadas

Atualizar chamadas

Associar chamadas existentes a registros

Remover uma associação

Fixar uma chamada em um registro

Excluir chamadas

Run in Postman

​Criar envolvimento de chamada

​Propriedades

​Associações

​Recuperar chamadas

​Diferenciar mensagens de voz e chamadas gravadas

​Atualizar chamadas

​Associar chamadas existentes a registros

​Remover uma associação

​Fixar uma chamada em um registro

​Excluir chamadas

Criar envolvimento de chamada

Propriedades

Associações

Recuperar chamadas

Diferenciar mensagens de voz e chamadas gravadas

Atualizar chamadas

Associar chamadas existentes a registros

Remover uma associação

Fixar uma chamada em um registro

Excluir chamadas