Chamadas

Visão geralEndpoints

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 visualizar todos os endpoints disponíveis e seus requisitos, clique na guia Endpoints na parte superior deste artigo.

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

No objeto de propriedades, você pode incluir os seguintes campos:

Use this table to describe parameters / fields
CampoDescription
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 da chamada para chamadas OUTBOUND ou o discador da chamada para chamadas INBOUND.

hs_call_callee_object_type_id

O ID 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 OUTBOUND ou o objeto do discador para chamadas 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 ao vivo: 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. O objeto deve incluir os seguintes campos:

Use this table to describe parameters / fields
CampoDescription
toObjectId

O ID do registro ao qual você deseja associar a chamada.

associationType

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, 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 } ] }] }

Saiba mais sobre a criação de chamadas em lote clicando na guia Endpoints na parte superior deste artigo.

Recuperar chamadas

Você pode recuperar chamadas individualmente ou em massa. Saiba mais sobre a recuperação em massa clicando na guia Endpoints na parte superior deste artigo.

Para recuperar uma chamada individual pelo seu ID de chamada, faça uma solicitação GET para/crm/v3/objects/calls/{callId}. Você pode incluir os seguintes parâmetros na URL da solicitação: 

Use this table to describe parameters / fields
ParameterDescription
propriedades

Uma lista separada por vírgulas das propriedades a serem retornadas. 

associações

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: 

Use this table to describe parameters / fields
ParameterDescription
limite

O número máximo de resultados a serem exibidos por página.

propriedades

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. 

Identify voicemails vs. recorded calls

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 de chamada, 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 massa clicando na guia Endpoints na parte superior deste artigo.

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:

Use this table to describe parameters / fields
CampoDescription
callId

O id da conversa.

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 a mesma 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 de chamada, faça uma solicitação DELETE para /crm/v3/objects/calls/{callId}.

Saiba mais sobre a exclusão em massa clicando na guia Endpoints na parte superior deste artigo.

Este artigo foi útil?
Este formulário deve ser usado apenas para fazer comentários sobre esses artigos. Saiba como obter ajuda para usar a HubSpot..