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.

• Requisitos do escopo
• Endpoints de participação em eventos
• Definir configurações de aplicativo
  • Etapa 1: Criar uma API no seu app
  • Etapa 2: Fornecer à HubSpot o caminho da URL para sua API

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.

Você pode criar ou atualizar eventos de marketing enviando uma solicitação POST para o ponto de extremidade /marketing/v3/marketing-events/events/upsert. Você pode incluir CustomProperties que correspondam aos eventos que deseja atualizar no campo inputs no corpo da solicitação, juntamente com outros detalhes do seu evento (incluindo nome, hora de início e descrição).

Se já existir um evento de marketing com o ID especificado na solicitação, este será atualizado. Caso contrário, um novo evento será criado.

Por exemplo, a seguinte solicitação criaria um evento com um ID 4 chamado "Virtual cooking class":

Você pode consultar uma lista completa de todos os campos disponíveis para incluir na sua solicitação clicando na guia Pontos de extremidade na parte superior deste artigo.

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. 

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.

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:

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.

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