Eventos de marketing

Um evento de marketing é um objeto de CRM, semelhante a contatos e empresas, que permite monitorar e associar eventos de marketing, como um webinar, a outros objetos CRM da HubSpot. Abaixo, saiba mais sobre como trabalhar com a API de eventos de marketing para integrar eventos de marketing a um app.

In this article

Requisitos do escopo

Para fazer uma solicitação de API para um dos endpoints de evento de marketing, são necessários os seguintes escopos:

  • crm.objects.marketing_events.read: concede permissão para recuperar dados de eventos de marketing e de presença.
  • crm.objects.marketing_events.write: concede permissão para criar, excluir ou fazer alterações nas informações do evento de marketing.

Ao autenticar chamadas feitas pelo seu app, você pode usar um token de acesso de app privado ou OAuth. Saiba mais sobre métodos de autenticação. Para obter a lista completa de endpoints disponíveis, clique na guia Endpoints na parte superior deste artigo.

Endpoints de participação em eventos

Os endpoints de status de participação no evento permitem que você registre um status de assinatura entre um contato do HubSpot e um evento de marketing. Por exemplo, você pode usar esse endpoint para registrar que um contato HubSpot se inscreveu em um evento de marketing.

Existem dois endpoints que você pode usar para atualizar o status de participação de um contato. Se você estava usando os endpoints /upsert ou /email-upsert anteriormente para atualizar o status de um participante, você pode usar os endpoints listados abaixo para manter a mesma funcionalidade ao mesmo tempo em que preenche a duração da participação do contato na linha do tempo do contato:

  • Se você quiser usar os IDs de contato de contatos existentes:
    • Faça uma solicitação POST para /marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/create, usando o ID do evento de seu aplicativo externo como externalEventId.
    • No corpo da solicitação, forneça um objeto inputs que inclua os seguintes campos:
      • interactionDateTime: a data e hora em que o contato se inscreveu para o evento.
      • vid: o ID de contato de um contato existente.
  • Caso queira usar o endereço de e-mail de um dos participantes do evento:
    • Faça uma solicitação POST para /marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/email-create.
    • No corpo da solicitação, forneça um objeto inputs que inclua os seguintes campos:
      • interactionDateTime: a data e hora em que o contato se inscreveu para o evento.
      • e-mail: o endereço de e-mail do participante como o valor do campo de e-mail em uma entrada 
    • Se o endereço de e-mail que você incluir não corresponder ao endereço de um contato existente, um novo contato será criado.

Para ambos os endpoints acima, forneça os seguintes valores para os parâmetros de caminho correspondentes:

  • externalEventId: o ID do evento de marketing.
  •  subscriberState: uma enumeração que corresponda ao novo status de participação do contato:
    • INSCRITO: indica que o contato da HubSpot se inscreveu para o evento.
    • COMPARECEU: indica que o contato da HubSpot participou do evento. Se estiver atualizando o status de um contato para COMPARECEU, você também pode incluir os timestamps joinedAt e leftAt como parâmetros no corpo da solicitação, especificados no formato ISO8601 Instant.
    • CANCELADA: indica que o contato da HubSpot, que já havia se inscrito para o evento, cancelou sua inscrição.

Uma vez que seu evento esteja concluído, você poderá marcá-lo como concluído e calcular as métricas de participação (por exemplo, duração da presença de todos os participantes) fazendo uma solicitação POST para /marketing/v3/marketing-events/events/{externalEventId}/complete. Observe que essa ação é irreversível, portanto, você só deve invocar esse endpoint depois que todos os eventos de alteração do status de participação já tiverem ocorrido. 

Please note: these APIs are idempotent so long as the ID of the contact and the interactionDateTime value in the event has not changed. This enables you to safely set subscriber state multiple times without HubSpot creating duplicate events in the marketing events properties.

Definir configurações de aplicativo

Algumas configurações são necessárias para permitir que os eventos de marketing sejam sincronizados corretamente com a HubSpot.

Se você enviar à HubSpot uma alteração no estado do assinante (por exemplo, uma inscrição ou cancelamento), a HubSpot primeiro verificará se existe um Evento de Marketing para o ID do evento especificado. Caso contrário, a HubSpot chamará o endpoint configurado do seu app para recuperar os detalhes do evento de marketing e, então, criar o evento na HubSpot e publicar a alteração do estado do assinante.

Isso é fornecido por conveniência. No entanto, ainda é recomendável que você mesmo crie os Eventos de Marketing por meio dos métodos CRUD fornecidos na guia Endpoints na parte superior deste artigo, e não confie nessa funcionalidade para criar seus eventos de marketing na HubSpot.

Etapa 1: Criar uma API no seu app

Para oferecer suporte a isso, o HubSpot exige que cada app que usa eventos de marketing defina uma API para obter informações sobre um evento de marketing específico.

Requisitos:

  • Aceita:
    • externalAccountId: um parâmetro de consulta que especifica o accountId do cliente no aplicativo externo.
    • appId: um parâmetro de consulta que especifica o ID do aplicativo HubSpot que está solicitando os detalhes do evento. Este será o ID do seu app.
    • externalEventId: um parâmetro de caminho na URL da solicitação que especifica o ID do evento no aplicativo externo sobre o qual o HubSpot requer detalhes.
  • Retorna:
    • Um objeto JSON que fornece detalhes para o evento de marketing, que inclui os seguintes campos detalhados na tabela abaixo:
Nome do campo Obrigatório Tipo Descrição do campo
eventName true string O nome do evento de marketing
eventOrganizer true string O nome do organizador do evento de marketing.
eventType false string Descreve que tipo de evento é este. Por exemplo: WEBINAR, CONFERÊNCIA, WORKSHOP
startDateTime false string($date-time) A data e hora de início do evento de marketing.
endDateTime false string($date-time) A data e hora de término do evento de marketing.
eventDescription false string A descrição do evento de marketing.
eventUrl false string Uma URL no aplicativo de evento externo no evento de marketing.
eventCancelled false bool Indica se o evento de marketing foi cancelado. Assume o padrão false

A HubSpot também enviará um cabeçalho X-HubSpot-Signature-v3 que você pode usar para verificar se a solicitação veio da HubSpot. Leia mais sobre request signatures para obter detalhes adicionais sobre a assinatura e como validá-la.

Etapa 2: Fornecer à HubSpot o caminho da URL para sua API

Agora que você criou a API em seu app que retornará um objeto que fornece os detalhes de um evento de marketing específico, você vai precisar fornecer à HubSpot o caminho de URL para sua API fazendo uma solicitação POST para /marketing/v3/marketing-events/{appId}/settings. Isso permitirá que a HubSpot determine como fazer solicitações ao seu app para obter os detalhes de um evento de marketing.

No corpo de sua solicitação POST, especifique sua URL usando o campo eventDetailsURL. A eventDetailsURL deve atender aos dois requisitos a seguir:

  • Conter uma sequência de caracteres %s que a HubSpot usará para substituir no ID do evento (externalEventId) como um parâmetro de caminho.
  • Deve ser o caminho completo para o recurso da API, incluindo o prefixo https:// e o nome do domínio (por exemplo, my.event.app).

Por exemplo, se você configurar eventDetailsURL de https://my.event.app/events/%s e precisar fazer uma solicitação para obter detalhes de um evento com id 1234-event-XYZ para o app da HubSpot com o id app-101 e conta com o id ABC-account-789, a HubSpot fará uma solicitação GET para:

https://my.event.app/events/1234-event-XYZ?appId=app-101&externalAccountId=ABC-account-789


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..