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 pontos de extremidade disponíveis e seus requisitos, clique na guia Pontos de extremidade na parte superior deste artigo.
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).
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:
|
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. |
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 clicando na guia Pontos de extremidade na parte superior deste artigo.
Você pode recuperar chamadas individualmente ou em massa. Saiba mais sobre a recuperação em massa clicando na guia Pontos de extremidade na parte superior deste artigo.
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.
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.
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:
xxxxxxxxxx
//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** Pontos de extremidade** na parte superior deste artigo.
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
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}
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.
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 em massa clicando na guia** Pontos de extremidade** na parte superior deste artigo.