Cartões de CRM

O cartões de CRM personalizados permitem que as informações de outros sistemas apareçam no contato, na empresa, nos negócios ou nos tíquetes do HubSpot. Usando esse recurso, os aplicativos podem criar cartões personalizados para exibir esses dados. Se quiser ter seus dados diretamente ativos no HubSpot, mas nenhum dos objetos nativos se encaixa suas necessidades, veja se os objetos personalizados atendem às suas necessidades.

Exemplo de caso de uso: Sua equipe de engenharia usa um serviço de software para rastrear bugs, mas seus representantes de atendimento ao cliente usam o HubSpot. Seus representantes querem ver informações sobre seus clientes sem sair do HubSpot. Seu aplicativo pode definir um cartão personalizado que exibe essas informações diretamente no registro de contato do HubSpot.

Como funciona

Os cartões podem ser definidos como parte das configurações de recurso do aplicativo. Assim que o aplicativo for instalado e um usuário visualizar os registros de CRM alvo, o HubSpot faz uma solicitação de outbound para o aplicativo, recupera os dados pertinentes e exibe em um cartão na página de registro. Os apps também podem especificar ações personalizadas que o usuário pode realizar com base nessas informações. Um exemplo de uma ação personalizada seria abrir um modal e exibir a próprio UI do aplicativo no HubSpot.

Veja um exemplo de um cartão de CRM:

CRM_Card_1

Este é um exemplo de como usar fluxos de dados para mostrar as propriedades do cartão no CRM:

CRM_card_diagram

 

Configurar cartões de CRM

Os cartões de CRM podem ser criados e configurados na sua conta do desenvolvedor. Detalhes individuais no cartão são representados por propriedades de cartão e os títulos dessas propriedades podem (opcionalmente) se conectar ao sistema externo do integrador. Observe que a linha “Fornecido por” no cartão usará o nome do aplicativo nas configurações do aplicativo.

No painel Apps, escolha o aplicativo em que quer adicionar um cartão e vá para cartões de CRM. Clique no botão “Criar cartão de CRM” para começar.

Captura de tela de 2020-01-14 às 7.36.35 PM

Requisitos do escopo

Para criar cartões de CRM personalizados, seu aplicativo precisa solicitar os escopos de OAuth necessários para modificar os registros de CRM em que seu cartão aparecerá. Isso significa que você solicita o escopo dos contatos para configurar um cartão para contatos, empresas, negócios, e o escopo de tíquetes para fazer o mesmo para tíquetes.

Veja a documentação de OAuth para obter mais detalhes sobre os escopos e configurar o URL de autorização para seu aplicativo.

Remover escopos

Se seu aplicativo já estiver usando cartões de CRM, você não poderá remover os contatos ou os tíquetes até excluir todos os cartões existentes para os tipos de objeto associados.

 

Criar novos cartões

Criar modelos de cartão é a primeira etapa ao usar cartões de CRM. O usuário verá isto:

CRM_card_2

 

Configurar cartões através da API

Saiba mais sobre como gerenciar cartões através da API na guia de endpoints

Configurar de cartões das configurações da UI do aplicativo

Você também pode criar e gerenciar o cartão de CRM* na sua conta do desenvolvedor nas configurações de recurso do seu aplicativo. (Consulte as instruções anteriores.)

Example_CRM_card_3

*Você pode criar até 25 cartões de CRM por aplicativo.


Documentos relacionados

Entendendo o CRM

Eventos de linha do tempo

Solicitações de busca de dados

Conforme mencionado na guia de visão geral, o HubSpot faz uma solicitação de busca de dados ao seu aplicativo sempre que um usuário visualizar o registro de CRM associado. Essas solicitações são enviadas à busca/targetUrl especificado do cartão com uma carga útil que fornece detalhes para o registro do CRM associado.

As respostas podem conter até cinco propriedades de cartão. Se mais propriedades de cartão estiverem disponíveis para um objeto de CRM específico, seu aplicativo pode vincular a eles.

Observe que o tempo limite da solicitação é de 5 segundos. Nesse período, uma conexão deve ser feita em 3 segundos. 

Exemplo de solicitação de busca de dados:

GET: https://example.com/demo-tickets?userId=12345&userEmail=testuser@example.com&associatedObjectId=78912&associatedObjectType=COMPANY&portalId=9999999&domain=testcompany.com

 
Com um cabeçalho:
X-HubSpot-Signature: <some base64 string>

o cabeçalho X-HubSpot-Signature oferece uma confirmação de que a solicitação veio do HubSpot. Veja solicitar assinaturas para detalhes.

Parâmetros de consulta:
  • userId: o ID numérico do usuário do cliente que solicita dados.
  • userEmail: o endereço da HubSpot do usuário que solicita dados.
  • portalId: o ID da conta da HubSpot do cliente que solicita dados. A conta e o Portal são usados intercambiavelmente. 
  • associatedObjectId: o ID do objeto atual, dependendo do associatedObjectType. Será companyId, dealId, contact vID ou objectId para tíquetes.
  • associatedObjectType: o tipo de objeto do qual o usuário solicita dados (contato, empresa, negócio ou tíquete). Esse será um dos associatedHubSpotObjectTypes fornecidos para esse tipo de registro.
  • E valores para qualquer um dos associatedHubSpotObjectTypeProperties solicitados. Se uma das propriedades de solicitação não for definida para o objeto atual, ela não será listada na linha de consulta. No exemplo acima, o domínio de propriedade da empresa está incluído. As propriedades de solicitação podem ser definidas na UI de configurações do aplicativo, como você pode ver na captura de tela abaixo: 

Associated_Objects

Exemplo de resposta:
// example response { "results": [ { "objectId": 245, "title": "API-22: APIs working too fast", "link": "http://example.com/1", "created": "2016-09-15", "priority": "HIGH", "project": "API", "reported_by": "msmith@hubspot.com", "description": "Customer reported that the APIs are just running too fast. This is causing a problem in that they're so happy.", "reporter_type": "Account Manager", "status": "In Progress", "ticket_type": "Bug", "updated": "2016-09-28", "actions": [ { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/edit-iframe-contents", "label": "Edit", "associatedObjectProperties": [] }, { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/reassign-iframe-contents", "label": "Reassign", "associatedObjectProperties": [] }, { "type": "ACTION_HOOK", "httpMethod": "PUT", "associatedObjectProperties": [], "uri": "https://example.com/tickets/245/resolve", "label": "Resolve" }, { "type": "CONFIRMATION_ACTION_HOOK", "confirmationMessage": "Are you sure you want to delete this ticket?", "confirmButtonText": "Yes", "cancelButtonText": "No", "httpMethod": "DELETE", "associatedObjectProperties": [ "protected_account" ], "uri": "https://example.com/tickets/245", "label": "Delete" } ] }, { "objectId": 988, "title": "API-54: Question about bulk APIs", "link": "http://example.com/2", "created": "2016-08-04", "priority": "HIGH", "project": "API", "reported_by": "ksmith@hubspot.com", "description": "Customer is not able to find documentation about our bulk Contacts APIs.", "reporter_type": "Support Rep", "status": "Resolved", "ticket_type": "Bug", "updated": "2016-09-23", "properties": [ { "label": "Resolved by", "dataType": "EMAIL", "value": "ijones@hubspot.com" }, { "label": "Resolution type", "dataType": "STRING", "value": "Referred to documentation" }, { "label": "Resolution impact", "dataType": "CURRENCY", "value": "94.34", "currencyCode": "GBP" } ], "actions": [ { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/edit-iframe-contents", "label": "Edit" }, { "type": "CONFIRMATION_ACTION_HOOK", "confirmationMessage": "Are you sure you want to delete this ticket?", "confirmButtonText": "Yes", "cancelButtonText": "No", "httpMethod": "DELETE", "associatedObjectProperties": [ "protected_account" ], "uri": "https://example.com/tickets/245", "label": "Delete" } ] } ], "settingsAction": { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/settings-iframe-contents", "label": "Settings" }, "primaryAction": { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/create-iframe-contents", "label": "Create Ticket" } }
Definições:
  • results: uma lista de até cinco propriedades de cartão válidas. 
  • results[].objectId: um ID exclusivo para este objeto. Esta propriedade é necessária.
  • results[].title: O título desse objeto. Esta propriedade é necessária.
  • results[].link: a URI que o usuário pode seguir para obter mais detalhes sobre este objeto. Esta propriedade é opcional, mas se todos os objetos não têm um link, você deve fornecer um valor de nulo.
  • results[].properties: uma lista de propriedades personalizadas que não são definidas nas configurações do cartão. Você pode usar essa lista para exibir propriedades exclusivas de objeto específico. Essas propriedades serão exibidas na ordem em que são fornecidas, mas depois das propriedades definidas nas configurações do cartão. Esta propriedade é opcional.
  • results[].actions: uma lista de ações disponíveis que um usuário pode efetuar nesse objeto. Consulte tipos de ação para detalhes das ações especificadas. Esta propriedade é opcional.
  • totalCount: o número total de propriedades de cartão disponíveis, se houver mais de cinco relacionados ao objeto de CRM solicitado. Esta propriedade é opcional.
  • allItemsLink: uma URI que mostra todas as propriedades do cartão associadas ao objeto de CRM solicitado, se houver mais de cinco. Esta propriedade é opcional.
  • itemLabel: o rótulo a ser usado no link "Ver mais", por exemplo, "Ver mais tíquetes". Esta propriedade é opcional e, se não for fornecida, ela será o título do cartão.
  • settingsAction: uma ação iframe que oferece a capacidade de atualizar as configurações do aplicativo aos usuários. Consulte tipos de ação para detalhes das ações especificadas. Esta propriedade é opcional.
  • primaryAction: a ação principal para um tipo de registro, normalmente uma ação de “criação”. Consulte tipos de ação para detalhes das ações especificadas. Esta propriedade é opcional.
  • secondaryActions: Uma lista de ações exibidas no nível do cartão. Consulte tipos de ação para detalhes das ações especificadas. Esta propriedade é opcional.

Além das propriedades acima, o integrador pode fornecer valores para as propriedades definidas nas configurações do cartão. No exemplo acima, a propriedade JSON criada:

"created":"2016-08-04"

Fornece um valor para esse objeto para a propriedade created predefinida.

CRM_card_5

Lidar com hooks de ação 

Quando um usuário clica em uma ação definida como um hook de ação, o HubSpot envia uma solicitação usando o método URI e HTTP especificado na definição de ação.

Exemplo de solicitação:

DELETE https://example.com/tickets/245?userId=12345&userEmail=testuser@example.com&associatedObjectId=78912&associatedObjectType=COMPANY&portalId=9999999&domain=testcompany.com

Com um cabeçalho:
X-HubSpot-Signature: <some base64 string>
Parâmetros de consulta:
  • userId: o ID numérico do usuário do cliente que solicita dados.
  • userEmail: o endereço de usuário da HubSpot do cliente que solicita dados.
  • associatedObjectId: o ID do objeto atual, dependendo do associatedObjectType. Será companyId, dealId, contact vid ou objectId para tíquetes.
  • associatedObjectType: o tipo de objeto para o qual o usuário está solicitando dados (contato, empresa, negócio ou tíquete).
  • portalId: o ID da conta (também chamado de ID do Hub) do cliente que solicita dados.
  • E os valores de qualquer  associatedObjectProperties solicitado. Se uma das propriedades solicitadas for indefinida para o objeto atual, ele não será listado na string de consulta. No exemplo acima, o domínio de propriedade da empresa está incluído.

O cabeçalho X-HubSpot-Signature permite que o integrador verifique se uma solicitação veio do HubSpot. Veja solicitar assinaturas para detalhes.

Exemplo de resposta:
{"message": "Successfully deleted object"}

O HubSpot tentará analisar as respostas aos hooks de ação como JSON e procurar uma propriedade de mensagem. O usuário receberá uma mensagem em caso de sucesso ou falha.

O código de status da resposta de 2XX mostrará uma mensagem de sucesso e 4XX ou 5XX mostrará mensagens de erro.

 

Tipos de ação

As seções a seguir fornecem detalhes sobre cada tipo de ação que pode ser especificado.

Ações Iframe

Quando um usuário clica em uma ação iframe, uma caixa de diálogo modal com um iframe apontando para o URL fornecido será aberta.

Exemplo de ação iframe:
// { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/iframe- contents", "label": "Edit", "associatedObjectProperties": [ "some_crm_property" ] }
Definições:
  • type: deve ser IFRAME para indicar que essa é uma ação iframe.
  • width, height: as dimensões de iframe desejadas.
  • uri: a URI aberta no iframe.
  • label: o rótulo exibido no menu suspenso de ação.
  • associatedObjectProperties: uma lista de propriedades no contato, empresa, negócio ou tíquete associado. Os valores de propriedade do objeto atual serão anexados à URI como parâmetros de consulta ao abrir o iframe.

Sinalizar para o modal fechar

Quando o usuário concluir uma ação do iframe, o diálogo modal deve fechar e retornar o usuário à tela CRM original. Para fechar o modelo de diálogo, o aplicativo pode usar um window.postMessage. As seguintes mensagens são aceitas:

  • {"action": "DONE"} - O usuário conclui a ação com sucesso.
  • {"action": "CANCEL"} - O usuário cancelou a ação.
Exaemplo: window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*");

Observação: modais iframe acessados por uma ação iframe terá uma largura responsiva. 

 

Ações do hook de ação

Ações do hook de ação enviam uma solicitação do lado do servidor para um aplicativo. A única UI que um usuário vê para essa ação é uma mensagem de sucesso ou de erro. Este tipo de ação é útil para operações simples que não exigem mais entrada de usuário.

Exemplo de ação de hook de ação:
// { "type": "ACTION_HOOK", "httpMethod": "POST", "uri": "https://example.com/action-hook", "label": "Example action", "associatedObjectProperties": [ "some_crm_property" ] }
Definições:
  • type: deve ser ACTION_HOOK para indicar que essa é uma ação de hook de ação.
  • httpMethod: o método HTTP a usar ao fazer a solicitação. Pode ser GET, POST, PUT, DELETE ou PATCH.
  • uri: a URI da solicitação a fazer.
  • label: o rótulo para exibir no menu suspenso de ação.
  • associatedObjectProperties: uma lista de propriedades no contato, empresa, negócio ou tíquete associado. Se httpMethod for GET ou DELETE, esses valores de propriedade serão adicionados à URI da solicitação como parâmetros de consulta. Caso contrário, eles serão enviados como um corpo de solicitação JSON.

Veja Lidar com hooks de ação para mais detalhes sobre como implementar o endpoint de ação.

Ações de confirmação

As ações de confirmação se comportam como os hooks de ação, exceto que uma caixa de diálogo de confirmação é mostrada para o usuário antes de executar a solicitação do lado do servidor.

 

// { "type": "CONFIRMATION_ACTION_HOOK", "httpMethod": "POST", "uri": "https://example.com/action-hook", "label": "Example action", "associatedObjectProperties": [ "some_crm_property" ], "confirmationMessage": "Are you sure you want to run example action?", "confirmButtonText": "Yes", "cancelButtonText": "No" }
Definições:
  • type: deve ser ACTION_HOOK para indicar que essa é uma ação de hook de ação.
  • httpMethod: o método HTTP a usar ao fazer a solicitação. Pode ser GET, POST, PUT, DELETE ou PATCH.
  • uri: a URI da solicitação a fazer.
  • label: o rótulo para exibir no menu suspenso de ação.
  • associatedObjectProperties: uma lista de propriedades no contato, empresa, negócio ou tíquete associado. Se httpMethod for GET ou DELETE, esses valores de propriedade serão adicionados à URI da solicitação como parâmetros de consulta. Caso contrário, eles serão enviados como um corpo de solicitação JSON.

Veja Lidar com hooks de ação para mais detalhes sobre como implementar o endpoint de ação.

Ações de confirmação

As ações de confirmação se comportam como os hooks de ação, exceto que uma caixa de diálogo de confirmação é mostrada para o usuário antes de executar a solicitação do lado do servidor.

Definições:
  • type: deve ser CONFIRMATION_ACTION_HOOK para indicar que essa é uma ação do hook de ação de confirmação.
  • httpMethod: o método HTTP a usar ao fazer a solicitação. Pode ser GET, POST, PUT, DELETE ou PATCH.
  • uri: a URI da solicitação a fazer.
  • label: o rótulo para exibir no menu suspenso de ação.
  • associatedObjectProperties: uma lista de propriedades no contato, empresa, negócio ou tíquete associado. Se httpMethod for GET ou DELETE, esses valores de propriedade serão adicionados à URI da solicitação como parâmetros de consulta. Caso contrário, eles serão enviados como um corpo de solicitação JSON.
  • confirmationMessage: a mensagem a exibir ao usuário na caixa de diálogo de confirmação.
  • confirmButtonText: o texto do botão "OK". Ele é opcional, pois o padrão do texto do botão é “OK”.
  • cancelButtonText: texto para o botão "Cancelar". Ele é opcional, pois o padrão do texto do botão é “Cancelar.”

Veja Lidar com hooks de ação para mais detalhes sobre como implementar o endpoint de ação.


Was this article helpful? *
This form is used for documentation feedback only. Learn how to get help with HubSpot...