Enviar ocorrências de evento (BETA)

Após definir um esquema de tipo de evento e recuperar seu fullyQualifiedName, você pode enviar dados de ocorrência do evento por meio da API de eventos do aplicativo. Ao enviar dados de eventos, você precisa seguir o esquema já criado. As solicitações que não corresponderem ao esquema não passarão na validação e não serão capturadas pelo aplicativo.

Envio de ocorrências de evento

Enviar uma única ocorrência
Enviar um lote de ocorrências

Para enviar uma única ocorrência de evento, faça uma solicitação de POST para /integrators/timeline/v4/events.No corpo da solicitação, inclua dados de evento seguindo o esquema definido do tipo de evento juntamente com o valor fullyQualifiedName em um campo eventTypeName.

{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "123456",
  "id": "login-1",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  }
},

Para enviar um lote de ocorrências de evento, faça uma solicitação de POST para /integrators/timeline/v4/events/batch.No corpo da solicitação, inclua até 500 objetos de ocorrência de evento separados por vírgula em uma matriz inputs. Mesmo que alguma ocorrência não seja validada, as ocorrências validadas serão aceitas e mantidas.

{
  "inputs": [
    {
      "EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
      "id": "login_event_100",
      "objectId": "769851",
      "properties": {
        "customerName": "Tim",
        "loginLocation": "mobileApp"
      },
      "extraData": {
        "surveyData": [
          {
            "question": "How was your login experience?",
            "answer": "Fine!"
          },
          {
            "question": "How likely are you to recommend logging in to a co-worker?",
            "answer": "Extremely likely"
          }
        ]
      }
    },
    {
      "EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
      "id": "login_event_101",
      "objectId": "769851",
      "properties": {
        "customerName": "Tim",
        "loginLocation": "website"
      },
      "extraData": {}
    }
  ]
}

Campos marcados com * são obrigatórios.

Campo	Tipo	Descrição
`eventTypeName`*	String	O nome totalmente qualificado do tipo de evento, usado para identificar o evento via API. Esse valor é automaticamente definido pelo HubSpot e pode ser obtido através da API depois da criação do tipo de evento. Este valor não pode ser alterado após a criação.
`objectId`*	String	O ID do registro de CRM para associar à ocorrência do evento. Este campo pode ser usado para todos os tipos de registros de CRM e é o identificador recomendado. Saiba mais sobre associação de registro de CRM.
`email`	String	Para associações de contato, você pode fornecer o endereço de e-mail do contato a ser associado. Saiba mais sobre associação de registro de CRM.
`utk`	String	Para associações de contato, você pode fornecer o token de usuário de um contato existente para associar. Saiba mais sobre associação de registro de CRM.
`domain`	String	Inclua este campo além de `objectId` para definir o valor da propriedade de `domain` da empresa. Saiba mais sobre associação de registro de CRM.
`timestamp`	String	Define a hora da ocorrência do evento (formato ISO 8601). Se não for fornecida, o HubSpot usará como padrão o carimbo de data/hora do envio de dados de ocorrência de evento.
`properties`	Objeto	Pares chave-valor de nomes de propriedades e valores de propriedades que você configurou para o tipo de evento. Saiba mais sobre propriedades de evento.
`extraData`	Objeto	Informações adicionais disponíveis para modelos de renderização de linhas do tempo. Deve estar em um formato JSON válido.
`timelineIFrame`	Objeto	Quando incluído, o cartão de linha do tempo conterá um hiperlink que permite que os usuários abram o conteúdo vinculado em um iframe. Saiba mais sobre como usar iframes.
`id`	String	Um identificador exclusivo para a ocorrência do evento. Deve ser exclusivo dentro do tipo de evento. Se não for fornecido, o HubSpot gerará um UUID aleatório. Quando houver vários eventos com o mesmo ID, o primeiro será aceito e todos os outros serão rejeitados.

Associação de registro de CRM

Cada ocorrência de evento deve ser associada a um registro de CRM, com o tipo de objeto de CRM definido pelo esquema de tipo de evento. A API de eventos de aplicativo inclui vários campos para associar dados de ocorrência de evento com registros de CRM. Para todos os objetos de CRM compatíveis, recomendamos usar o campo objectId. No entanto, há algumas situações em que outros campos devem ser usados.

utk/email: se você não souber o ID do contato, use o campo utk e/ou email para identificação. Fornecer esses dois identificadores também permite criar e atualizar contatos. Por exemplo:
- Se utk corresponde a um contato existente, mas email não corresponde, o HubSpot atualizará o contato (por utk) com o novo endereço de e-mail.
- Se nenhum objectId for fornecido, a ocorrência do evento será associada a um contato existente que corresponda ao utk/email, ou HubSpot criará um contato se nenhuma correspondência for encontrada.
- Observe que o utk sozinho não pode criar novos contatos. Você deve sempre incluir email com utk para que associação seja adequada.
domain: para associações de empresa, você deve fornecer o objectId, mas você também pode incluir domain para atualizar a propriedade de domain daquela empresa.

Veja abaixo a ordem de prioridade das propriedades de associação de registros de CRM, em que o menor número tem a maior prioridade:

Campo	Prioridade	Descrição
`objectId`	1	O ID do registro de CRM (recomendado).
`utk`	2	O token de usuário do contato (somente contatos).
`email`	3	O endereço de e-mail do contato (somente contatos).
`domain`	4	O domínio de empresas (apenas empresas).

Enviar dados adicionais

Além de enviar dados para propriedades do evento e atualização de propriedades de CRM via ocorrências de evento, você pode incluir dados adicionais para renderização de linha do tempo através do objeto extraData.

O objeto extraData só pode conter JSON válido. Se o JSON estiver malformado, a ocorrência será rejeitada e você receberá uma resposta de erro.

Valores de campo extraData podem ser acessados pelo tipo de evento detailTemplate usando a sintaxe {{extraData.fieldName}}. Todos os níveis de atributo de extraData estão disponíveis por meio de notação de ponto, como {{extraData.person1.preferredName}}. Por exemplo, os modelos abaixo usam os dados de propriedade customerName e loginLocation com o campo surveyData de extraData enviado através da ocorrência do evento. Captura de tela que mostra a aparência do modelo de renderização abaixo na linha do tempo de contato.

Captura de tela que mostra a aparência do modelo de renderização abaixo na linha do tempo de contato.

Dados de ocorrência do evento
Configuração do modelo de linha do tempo

{
  "eventTemplateId": "5488733",
  "objectId": "769851",
  "tokens": {
    "customerName": "Tim",
    "loginLocation": "mobileApp"
  },
  "extraData": {
    "surveyData": [
      {
        "question": "How was your login experience?",
        "answer": "Fine!"
      },
      {
        "question": "How likely are you to recommend logging in to a co-worker?",
        "answer": "Extremely likely"
      }
    ]
  }
}

"headerTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
"detailTemplate": "#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}",

Criar aplicativos

Adicionar recursos

Publicar no HubSpot Marketplace

Enviar ocorrências de evento (BETA)

Envio de ocorrências de evento

Associação de registro de CRM

Enviar dados adicionais

​Envio de ocorrências de evento

​Associação de registro de CRM

​Enviar dados adicionais

Envio de ocorrências de evento

Associação de registro de CRM

Enviar dados adicionais