As extensões de CRM permitem que as informações de outros sistemas apareçam no contato, na empresa ou nos negócios do HubSpot. Os pontos de extremidade dos eventos de linha do tempo permitem fazer isso criando eventos de linha do tempo personalizados. Se você preferir que seus dados possam ser editados pelos usuários, mas nenhum dos objetos de CRM padrão atender às suas necessidades, considere o uso de objetos personalizados.
Por exemplo, você quer segmentar melhor seus contatos com base nas interações deles com a empresa e o conteúdo. Para fazer isso, você precisa de mais informações sobre eles. O aplicativo pode criar eventos personalizados (contatos que se registraram, mas não participaram de um webinar recente, qual variante de um fluxo de inscrição um contato concluiu, etc.) que forneçam mais contexto sobre as interações dos contatos com a empresa.
Antes de começar a criar eventos, crie um modelo de evento. Modelos de evento descrevem ações que seu aplicativo adicionará à linha do tempo de um contato, uma empresa ou um negócio no HubSpot. Exemplos dessas ações incluem a visualização de um vídeo, o registro para participar de um webinar ou a resposta a uma pesquisa. Um único aplicativo pode criar até 750 modelos de evento.
Por padrão, os modelos de evento são criados para contatos, mas podem ser criados para empresas ou negócios usando o campo objectType
. Para obter mais informações, veja a criação de um modelo de evento de linha do tempo.
Cada modelo de evento tem seu próprio conjunto de tokens e modelos. Você pode usar eventos criados para contatos como critérios ao criar novas listas de contatos ou fluxos de trabalho, como: "Create a list of all contacts with a Video Like where the video name contains XYZ", onde o nome do modelo de evento é "Video Like" e tem um token de evento denominado "video name".
Para este exemplo, criaremos o novo modelo de evento “Exemplo de Registro no Webinar”. Para autenticação, use a chave de API do desenvolvedor encontrada na sua conta de desenvolvedor de apps.
curl -X POST
-H "Content-Type: application/json" -d '
{
"name": "Example Webinar Registration",
"objectType": "contacts"
}' \
'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates?hapikey=<<developerAPIkey>>''
Lembre-se de substituir <<appId>>
pelo ID do próprio aplicativo, que pode ser encontrado nas páginas Meus aplicativos e Detalhes do aplicativo em sua conta do desenvolvedor. Você também precisará substituir <<developerHapikey>>
por sua própria chave de API de desenvolvedor; ela pode ser encontrada em Aplicativos > Receber a chave de API da HubSpot.
As propriedades headerTemplate
e detailTemplate
também podem ser fornecidas aqui. (Consulte “Definindo Modelos” abaixo.)
Essa solicitação POST
retornará a definição completa do modelo de evento salvo. Observe a propriedade id
nessa resposta. Este é o ID do modelo de evento; ele será necessário caso você precise fazer qualquer atualização nesse modelo de evento ou em tokens no futuro.
Você pode ver todos os modelos de evento definidos para um aplicativo usando esse comando GET, que também retornará os ID do modelo de evento:
xxxxxxxxxx
curl -X GET 'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates?hapikey=<<developerAPIkey>>'
Além de usar a API para criar e gerenciar modelos de eventos de linha do tempo, você também pode gerenciar modelos de evento em sua conta de desenvolvedor da HubSpot.
Nas configurações do aplicativo, acesse Eventos de linha do tempo e use o botão “Criar tipo de evento” para criar um novo modelo de evento para esse aplicativo. Se você já tiver criado algum modelo de evento anteriormente, ele aparecerá aqui.
Você começará com um rascunho do novo modelo de evento. Depois de definir o tipo de objeto e os modelos de cabeçalho e de detalhes do evento, clique em "Criar"."
Ao criar ou editar seu modelo de evento, defina quaisquer tokens que deseje usar com ele na guia Dados.
**Observação: **se você excluir um modelo, os eventos existentes que usam esse modelo serão removidos permanentemente das contas com seu aplicativo conectado. Você não poderá mais criar novos eventos desse tipo, mas continuará vendo dados de eventos antigos em listas e relatórios. Essas alterações podem demorar várias horas para serem refletidas no HubSpot.
Depois de definir um modelo de evento, provavelmente você vai querer definir também os respectivos tokens. Os tokens de modelos de evento permitem anexar dados personalizados aos eventos, que podem ser exibidos na linha do tempo e, para contatos, podem ser usados para segmentação de lista e automação. Você pode criar até 500 tokens por modelo de evento de linha do tempo.
Observação: os eventos de empresa e negócio não podem ser usados na automação ou segmentação de lista.
Usando o ID do modelo de evento criado na Etapa 1, adicionaremos alguns tokens para identificar o webinar em que nossos seus contatos se registraram.
curl -X POST -H "Content-Type: application/json" -d '
{
"name": "webinarName",
"label": "Webinar Name",
"type": "string"
}' \
'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>/tokens?hapikey=<<developerHapikey>>'
curl -X POST -H "Content-Type: application/json" -d '
{
"name": "webinarId",
"label": "Webinar Id",
"type": "string"
}' \
'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>/tokens?hapikey=<<developerHapikey>>'
curl -X POST -H "Content-Type: application/json" -d '
{
"name": "webinarType",
"label": "Webinar Type",
"type": "enumeration",
"options": [
{
"value": "regular",
"label": "Regular"
},
{
"value": "ama",
"label": "Ask me anything"
}
]
}' \
'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>/tokens?hapikey=<<developerHapikey>>'
Da mesma forma, o comando GET
retornará todos os tokens definidos em um modelo de evento:
xxxxxxxxxx
curl -X GET -H "Content-Type: application/json" 'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>?hapikey=<<developerHapikey>>'
Os tipos de token permitidos incluem:
string
number
enumeration
— Uma dentre um conjunto de opções. Veja o exemplo webinarType abaixo.date
— Todas as datas devem estar em milissegundos no horário do Unix.
Observação: não é possível definir os nomes log ou lookup para tokens de evento. Esses tokens são reservados como auxiliares por Handlebars.js, a biblioteca usada para renderizar eventos no aplicativo. Para obter mais informações, consulte os documentos de Handlebars.js aqui.
Os modelos de cabeçalho e de detalhes definem como exibir um evento de linha do tempo. Você pode especificar documentos de Marcação com modelos Handlebars. O modelo de cabeçalho deve ser uma descrição de uma linha do evento; o modelo de detalhes é a exibição detalhada do evento (exemplos abaixo).
Os tokens de evento são transmitidos como dados para os modelos. Usando nosso exemplo, você pode fazer referência ao token webinarName
no modelo usando {{webinarName}}
.
O extraData
de um evento (analisado em “Noções básicas sobre extraData" abaixo) pode ser referenciado apenas no modelo de detalhes.
Os modelos de cabeçalho e de detalhes podem ser definidos no modelo de evento usando pontos de extremidadede modelos de evento. Por exemplo, podemos adicionar modelos ao nosso 'Exemplo de Registro no Webinar', modificando-o com o comando PUT
:
xxxxxxxxxx
curl -X PUT -H "Content-Type: application/json" -d '
{
"id": "<<eventTemplateId>>",
"name": "Example Name Change",
"headerTemplate": "Registered for [{{webinarName}}](https://mywebinarsystem/webinar/{{webinarId}})",
"detailTemplate": "Registration occurred at {{#formatDate timestamp}}{{/formatDate}}"
}' \
'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>?hapikey=<<developerHapikey>>'
Observe o uso da diretiva #formatDate
. Definimos essa diretiva para permitir uma formatação de data de fácil compreensão para o usuário.
Assim que um evento for criado para um contato usando essa diretiva (consulte "Criando um evento" abaixo), veja o que será exibido na linha do tempo do contato:
Clicar em “Mostrar detalhes” exibe o modelo de detalhes:
Para definir o ícone que é exibido ao lado dos eventos, consulte "Configurando um ícone personalizado" abaixo.
O texto “Exemplo de nome do aplicativo” acima consiste no nome do aplicativo. Na linha do tempo do CRM, os eventos podem ser filtrados por aplicativo.
Agora que você viu que cada aspecto de um modelo de evento é definido progressivamente, poderá defini-lo em uma chamada do comando POST
.
xxxxxxxxxx
curl -X POST -H "Content-Type: application/json" -d '
{
"name": "Another Webinar Registration",
"objectType": "contacts",
"headerTemplate": "Registered for [{{webinarName}}](https://mywebinarsystem/webinar/{{webinarId}})",
"detailTemplate": "Registration occurred at {{#formatDate timestamp}}{{/formatDate}}",
"tokens": [
{
"name": "webinarName",
"label": "Webinar Name",
"type": "string"
},
{
"name": "webinarId",
"label": "Webinar Id",
"type": "string"
},
{
"name": "webinarType",
"label": "Webinar Type",
"type": "enumeration",
"options": [
{
"value": "regular",
"label": "Regular"
},
{
"value": "ama",
"label": "Ask me anything"
}
]
}
]
}' \
'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates?hapikey=<<developerAPIkey>>'
Agora que um modelo de evento está configurado com tokens e modelos, estamos prontos para criar eventos para os contatos, as empresas, os negócios e os tickets de nossos clientes. Os exemplos abaixo pressupõem que estamos trabalhando com o modelo de evento de contacts
criado acima. Se o modelo de evento acima não estiver configurado para ter os tokens webinarName
e webinarId
, você receberá um erro ao tentar criar o evento. Este é um exemplo do comando POST
para a criação de um evento:
Observação: as chaves de API do desenvolvedor e os tokens de acesso ao aplicativo privado não podem ser usados como autenticação ao criar eventos. Para criar um evento, a conta associada da HubSpot precisará conceder acesso ao seu aplicativo por meio de OAuth. Depois de obter um token de acesso de OAuth, você poderá usá-lo para adicionar eventos à conta.
xxxxxxxxxx
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer <<OAuth2AccessToken>>" \
-d '
{
"eventTemplateId": "<<eventTemplateId>>",
"email": "a.test.contact@email.com",
"tokens": {
"webinarName": "A Test Webinar",
"webinarId": "001001",
"webinarType": "regular"
}
}' \
'https://api.hubapi.com/crm/v3/timeline/events'
Ele gera um evento na linha do tempo de a.test.contact@email.com
' (considerando os modelos descritos em “Definindo modelos” acima):
O registro de data/hora do evento determina onde o evento aparecerá na linha do tempo do objeto. Por padrão, o registro de data/hora do evento consiste no momento em que o comando POST é enviado. Você pode personalizar o horário do evento fornecendo-o no corpo da solicitação em uma propriedade de registro e data/hora:
xxxxxxxxxx
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer <<OAuth2AccessToken>>" \
-d '
{
"eventTemplateId": "<<eventTemplateId>>",
"email": "a.test.contact@email.com",
"timestamp": "2020-03-18T15:30:32Z",
"tokens": {
"webinarName": "A Test Webinar",
"webinarId": "001001",
"webinarType": "regular"
}
}' \
'https://api.hubapi.com/crm/v3/timeline/events'
Isso será o ideal se você souber o horário exato em que uma ação ocorreu. Nesse exemplo, se tivermos o registro de data/hora da inscrição no webinar, deveremos fornecê-lo no comando POST.
Os registros de data/hora podem estar no horário da época em milissegundos ou no formato ISO 8601.
Para criar um evento, você precisa ser capaz de associar o evento a um contato, uma empresa ou um negócio na conta de um cliente.
Nos exemplos acima, objectType foi definido como contato e usamos o parâmetro email para associar o evento a um contato. Os endereços de e-mail devem ser exclusivos para contatos no HubSpot. Portanto, se houver um contato existente com o e-mail fornecido, esse contato será atualizado. Se não houver um contato existente, um novo será criado. Por padrão, esse novo contato terá apenas a propriedade de contato de e-mail fornecida. Saiba mais sobre marcação de dados de eventos em propriedades de contato para adicionar mais dados às propriedades de contato.
xxxxxxxxxx
// {
"eventTemplateId": "<<eventTemplateId>>",
"email": "a.test.contact@email.com",
"tokens": {
"webinarName": "A Test Webinar",
"webinarId": "001001",
"webinarType": "regular"
}
}
Se você estiver trabalhando com contatos conhecidos, também poderá usar vid
do contato para associar o evento. Nesses casos, você usaria objectId
no JSON da solicitação. Você precisa incluir o vid de um contato existente, pois você não poderá criar novos contatos usando objectId
. Este exemplo usa o objectId
, em vez do e-mail:
xxxxxxxxxx
// {
"eventTemplateId": "<<eventTemplateId>>",
"objectId": "29851",
"tokens": {
"webinarName": "A Test Webinar",
"webinarId": "001001",
"webinarType": "regular"
}
}
Você também pode associar um evento a um contato por usertoken ou utk
. Usertoken é usado pelo código de rastreamento da HubSpot para rastrear visitantes e é armazenado no cookie hubspotutk
. Use o parâmetro utk
para associar um evento a um contato por usertoken. Observação: não é possível associar eventos a visitantes anônimos usando usertoken. Portanto, se o evento estiver associado somente ao parâmetro utk
e o usertoken fornecido não estiver associado a um contato ainda, nenhum novo contato será criado, e o evento não estará visível no HubSpot. No entanto, o evento aparecerá na linha do tempo se um novo contato tiver sido associado ao usertoken de outra maneira (geralmente por meio de um envio de formulário incluindo hutk ou por meio do método de identificação da API do código de rastreamento). Por isso, recomendamos que você inclua o email
, além do utk
, para garantir que o evento seja associado a um contato novo ou existente.
Se você estiver trabalhando com um modelo de evento para contatos, poderá incluir vários parâmetros de identificação com o evento para que seja possível incluir qualquer combinação dos parâmetros email
, objectId
e utk
. Se vários parâmetros forem incluídos, o parâmetro objectId (vid) prevalecerá no momento de determinar qual contato deve ser associado ao evento, seguido do parâmetro utk
. O parâmetro email
é o de menor prioridade. Isso significa que você pode atualizar o endereço de e-mail de um objeto existente, incluindo um novo endereço de e-mail no parâmetro email
email com vid
de um objeto conhecido em objectId
. Este exemplo usa o endereço de e-mail e o token de usuário juntos:
xxxxxxxxxx
// {
"eventTemplateId": "<<eventTemplateId>>",
"email": "a.test.contact@email.com",
"utk": "89b5afb740d41f4cd6651ac5237edf09"
"tokens": {
"webinarName": "A Test Webinar",
"webinarId": "001001",
"webinarType": "regular"
}
Além de trabalhar com contatos, também é possível criar modelos de evento para empresas e negócios. Para esses modelos de evento, você deve usar objectId
para associar o evento à empresa ou ao negócio. Para empresas, objectId
deve ser definido com o companyId
da empresa a que você deseja associar o evento; para negócios, objectId
deve ser definido com o dealId
do objeto de negócios.
No exemplo abaixo, considerando que o modelo de evento foi definido como objectType
COMPANY
, esse evento seria associado ao objeto de empresa com companyId
528253914:
xxxxxxxxxx
// {
"eventTemplateId": "<<eventTemplateId>>",
"objectId": "3001",
"tokens": {
"dealProperty": "Custom property for deal"
}
}
O recurso de extensões de linha do tempo pode ser usado para exibir dados de um sistema externo usando um iFrame. Se um link for incluído, ele será exibido pelo evento. Quando clicado, o link abrirá uma janela modal com o conteúdo do iFrame. Os detalhes do iFrame são definidos no campo timelineIFrame, que é um objeto com os campos a seguir:
linkLabel
- O texto usado para mostrar o link que exibirá o IFrame.headerLabel
- O rótulo da janela modal que exibe o conteúdo do IFrame.url
- O URI do conteúdo do IFrame.width
- A largura da janela modal.height
- Height - A altura da janela modal.
Por exemplo, usando esses dados para um evento:
xxxxxxxxxx
// {
"eventTemplateId": "<<eventTemplateId>>",
"email": "a.test.contact@email.com",
"tokens": {
"webinarName": "A Test Webinar",
"webinarId": "001001",
"webinarType": "regular"
},
"timelineIFrame": {
"linkLabel":"View external data",
"headerLabel":"Example iframe",
"url":"https://www.example.com",
"width":800,
"height":300
}
}
Você criaria esse evento, incluindo o link “Exibir dados externos”:
Clicar nesse link abriria uma janela modal com a página definida no url
:
Em muitos casos, você vai querer modificar as propriedades dos contatos, das empresas ou dos negócios aos quais está adicionando eventos. Geralmente isso acontece nos casos em que a adição do evento criará, de fato, um contato. Você provavelmente desejará atualizar as propriedades de nome e sobrenome no contato para não criar um contato que tenha apenas um endereço de e-mail e um evento.
Você pode marcar dados no objeto associado a partir de um evento mapeando seus tokens de eventos personalizados para propriedades de contatos, empresa ou negócios.
Considere esse comando PUT
para atualizar um modelo de evento personalizado. Observe o campo objectPropertyName
:
xxxxxxxxxx
curl -X PUT -H "Content-Type: application/json" -d '
{
"label" : "Updated Webinar Name",
"objectPropertyName": "zz_webinar_name"
}' \
'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>/tokens/<<tokenName>>?hapikey=<<developerHapikey>>'
Ele usa objectPropertyName
para mapear esse token de evento personalizado à propriedade zz_webinar_name
do objeto contact
. Isso significa que, quando criamos um novo evento que especifica um webinarName
, a propriedade zz_webinar_name
do contact
associado também é definida. Você pode definir essas propriedades para propriedades personalizadas ou predefinidas do HubSpot.
Por exemplo, suponha que já tenhamos criado um token companyName
que faça referência a uma propriedade personalizada zz_company_name
. Em seguida, a criação de um evento como este faz com que as propriedades zz_company_name
e zz_webinar_name
sejam definidas no contato com o endereço de e-mail a.test.contact@email.com:
xxxxxxxxxx
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer <<OAuth2AccessToken>>" \
-d '
{
"eventTemplateId": "<<eventTemplateId>>",
"email": "a.test.contact@email.com",
"tokens": {
"webinarName": "Test Webinar will update contact property",
"companyName": "TestCo",
"webinarId": "001001",
"webinarType": "regular"
}
}' \
'https://api.hubapi.com/crm/v3/timeline/events'
Observação: se um token de evento estiver marcado para uma propriedade personalizada e essa propriedade personalizada não estiver presente para uma conta da HubSpot, o valor continuará definido para o evento, mas será ignorado para o objeto correspondente.
Noções básicas sobre extraData
Talvez seja preciso adicionar dados detalhados a um evento que não se encaixa na estrutura simples de token-valor usada pelo modelo de evento. Pode ser necessário adicionar uma lista ou detalhamento hierárquico a um evento de integração. É aqui que entra o extraData
.
Você pode adicionar um atributo extraData
ao corpo JSON do evento. O valor desse extraData
pode ser qualquer JSON válido. Por exemplo:
xxxxxxxxxx
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer <<OAuth2AccessToken>>" \
-d '
{
"eventTemplateId": "<<eventTemplateId>>",
"email": "a.test.contact@email.com",
"tokens": {
"webinarName": "Test Webinar will update contact property",
"companyName": "TestCo",
"webinarId": "001001",
"webinarType": "regular"
},
"extraData": {
"pollData": [
{
"question": "How excited are you for this webinar?",
"answer":"Quite!"
},
{
"question": "How frequently do you use our product?",
"answer":"Daily"
}
],
"coWorkers": [
{
"name": "Joe Coworker",
"email":"joe.coworker@testco.com"
},
{
"name": "Jane Coworker",
"email":"jane.coworker@testco.com"
}
]
}
}' \
'https://api.hubapi.com/crm/v3/timeline/events'
Exemplo do uso de extraData
em um modelo de detalhes:
xxxxxxxxxx
//
Registration occurred at {{#formatDate timestamp}}{{/formatDate}}
#### Poll Questions
{{#each extraData.pollData}}
**{{question}}**: {{answer}}
{{/each}}
#### Co-Workers
{{#each extraData.coWorkers}}
* {{name}}
{{/each}}
Isso resultará em um evento de linha do tempo semelhante ao mostrado a seguir:
Observação: o atributo extraData
só pode ser referenciado no modelo de detalhes de um evento. Ele não pode ser usado no modelo de cabeçalho nem na segmentação de lista.
Para criar um apelo visual a seus itens de linha do tempo, você pode adicionar um ícone personalizado.
Este arquivo de imagem desse ícone deve:
- Ter dimensões quadradas
- Ter um fundo transparente
- Ter o conteúdo no centro do ícone
- Poder ser reduzido para até 30 x 30 pixels
- Ter um tamanho máximo de arquivo de 5 MB
Para definir o ícone usado para eventos de linha do tempo, vá para Eventos da linha do tempo. Clique na imagem do espaço reservado ou no ícone existente para definir ou atualizar.
Depois que os ícones forem definidos, eles aparecerão ao lado de todos os eventos de linha do tempo associados a este aplicativo: