Extensão de videoconferência

A API de videoconferência aos integradores a capacidade de se conectar ao fluxo de criação de reuniões no HubSpot e adicionar informações de conferência de vídeo. Usar essa API envolverá as seguintes etapas: 

  1. Configurar seu aplicativo com os webhooks de extensão de videoconferência. Você fornecerá URIs à HubSpot que ela usará para te notificar quando os clientes estiverem criando ou atualizando reuniões. 
  2. Tratar dos webhooks da criação de reuniões e, opcionalmente, dos webhooks de atualização de reunião. 
  3. Tratar dos webhooks de verificação de identidade do usuário se necessário. 

API de configurações 

Os desenvolvedores usarão essa API de configurações para configurar um aplicativo existente. Você pode usar o token de acesso do seu app privado para autenticar a solicitação. 

 

Definição de objeto de configurações 

O objeto de configurações tem os campos a seguir: 

createMeetingUrl: o URL para o qual as solicitações para novas videoconferências serão enviadas. Ela deve usar o protocolo https

updateMeetingUrl: (opcional) o URL para o qual as atualizações de reuniões existentes serão enviadas. Normalmente chamada quando o usuário muda o tópico ou o horário de uma reunião. Ela deve usar o protocolo https. 

deleteMeetingUrl: (opcional) o URL para o qual as reuniões excluídas no HubSpot serão notificadas. 

userVerifyUrl: (opcional) o URL usado para verificar se um usuário existe no seu sistema. 

Crie ou atualize as configurações de extensão de videoconferência 

Exemplo de solicitação:

PUT /crm/v3/extensions/videoconferencing/settings/{appId}

JSON
//example request

{
"createMeetingUrl": "https://example.com/create-meeting",
"updateMeetingUrl": "https://example.com/update-meeting",
"deleteMeetingUrl": "https://example.com/delete-meeting"
}

Exemplo de resposta: 

JSON
// example 200 response
{
"createMeetingUrl": "https://example.com/create-meeting",
"updateMeetingUrl": "https://example.com/update-meeting",
"deleteMeetingUrl": "https://example.com/delete-meeting"
}

Exemplo de resposta:

Valores opcionais devem ser excluídos da solicitação. Fornecer strings vazias ou outros valores provavelmente resultará em comportamento indesejado.

Buscar configurações de extensão de videoconferência

Exemplo de solicitação:

GET /crm/v3/extensions/videoconferencing/settings/{appId}

Exemplo de resposta:

JSON
// example 200 response
{
"createMeetingUrl": "https://example.com/create-meeting",
"updateMeetingUrl": "https://example.com/update-meeting"
"deleteMeetingUrl": "https://example.com/delete-meeting"
"userVerifyUrl": "https://example.com/user-verify"
}

Criar webhook de reunião

Quando uma reunião é criada, a HubSpot enviará uma solicitação para createMeetingUri 

Exemplo de solicitação:

JSON
// example request
{
"portalId": 123123,
"userId": 123,
"userEmail": "test.user@example.com",
"topic": "A Test Meeting",
"source": "MEETINGS"
"startTime": 1534197600000,
"endTime": 1534201200000
}

Os campos desta solicitação são:

  • portalId: o ID da conta da HubSpot (chamada de portal).
  • userId: o ID exclusivo do usuário do HubSpot proprietário da reunião.
  • userEmail: o endereço de e-mail do usuário do HubSpot proprietário da reunião.
  • topic: o tópico/título da reunião.
  • source: REUNIÕES ou MANUAL, indicando o recurso de reunião no
    aplicativo HubSpot onde a reunião foi criada, REUNIÕES corresponde à
    função “link de reunião” e MANUAL corresponde a uma reunião criada no
    Comunicador do CRM.
  • startTime: o horário de início da reunião (em milissegundos de época)
  • endTime: o horário final da reunião (em milissegundos de época)

Para lidar com este webhook, o desenvolvedor deve gerar uma videoconferência para essa reunião (ou link para uma linha de conferência existente) e responder às informações sobre essa conferência.


Exemplo de resposta:

JSON
//example response
{
"conferenceId": "some-unique-id",
"conferenceUrl": "https://example.com/join",
"conferenceDetails": "Click here to join: https://example.com/join"
}

Os campos esperado nesta resposta são:

  • conferenceId: um ID exclusivo associado à conferência neste evento.
    Esse ID precisa ser globalmente exclusivo no seu sistema. Enviaremos este ID
    de volta a você no webhook de atualização.
  • conferenceUrl: o link de conexão da conferência criada. Ele pode ser
    colocado no campo “localização” dos eventos.
  • conferenceDetails: informações de "convite" em texto simples. Ele deve descrever
    como os participantes do evento podem acessar a videoconferência desse
    evento. As novas linhas serão mantidas em representações desse texto no nosso
    sistema, mas nenhuma outra formatação é compatível.

Atualizar o Webhook de reunião

Se você especificar um updateMeetingUri, a HubSpot enviará uma solicitação a essa URI sempre que os detalhes relevantes da reunião forem alterados. Essa notificação é necessária se você precisar manter o tópico ou horários mais atualizados para uma videoconferência.


Exemplo de solicitação:

JSON
//example request
{
"conferenceId": "some-unique-id",
"userId": 123,
"userEmail": "test.user@example.com",
"portalId": 123123,
"topic": "A Test Meeting (updated)",
"startTime": 1534197600000,
"endTime": 1534201200000
}

Os campos esperado nesta resposta são:

  • conferenceId: o ID exclusivo para a conferência fornecido por sua integração na resposta ao webhook de reunião.
  • userId: o ID exclusivo do usuário do HubSpot proprietário da reunião. Ele sempre será o mesmo userId da solicitação de criação de reunião.
  • userEmail: o endereço de e-mail do usuário do HubSpot proprietário da reunião. Ele sempre será o mesmo userEmai da solicitação de criação de reunião.
  • topic: o tópico/título da reunião.
  • startTime: o horário de início da reunião (em milissegundos de época)

endTime: o horário final da reunião (em milissegundos de época)

Nenhum corpo de resposta é obrigatório ao responder a essas solicitações. Precisamos apenas de
um código de resposta 200 ou 204 para nos informar que esse webhook foi recebido
com sucesso.

Excluir webhook de reunião

Quando uma reunião é excluída no HubSpot, enviaremos uma solicitação para deleteMeetingUri.
Exemplo de solicitação:

JSON
//example request
{
"conferenceId": "some-unique-id"
}

Essa solicitação contém o conferenceId da reunião que foi excluída.
Nenhum corpo de resposta é obrigatório ao responder a essas solicitações. Precisamos apenas de
um código de resposta 200 ou 204 para nos informar que esse webhook foi recebido
com sucesso.

Webhook de verificação do usuário

Os sistemas da HubSpot sempre se comunicam com você sobre seus usuários em termos do seu ID de usuário do HubSpot e seu endereço de e-mail de conta da HubSpot. Há uma chance de um usuário no sistema da HubSpot existir no seu sistema com um endereço ou identificador de e-mail diferente.

Antes de fazer uma chamada para o seu sistema para criar, atualizar ou excluir um link de conferência da web, verifique suas configurações para userVerifyUri. Se essa URI tiver sido definida, disponibilizaremos uma chamada para recuperar o identificador de usuário nativo. Vamos enviar esse identificador como o endereço de e-mail do usuário na
chamada subsequente.

Há locais no app HubSpot em que podemos fazer essa chamada para você validar que o usuário existe no seu sistema antes de exibir os componentes da UI com os quais ele pode interagir, como um tipo de pré-verificação. Se você não configurou essa URI, sempre supomos que a identidade do usuário foi verificada.

Depende de você permitir esse recurso. Se precisar manter um mapeamento de usuário no seu sistema, você pode simplesmente mapear o ID ou e-mail do usuário do HubSpot para seu ID de usuário interno em cada chamada.


A solicitação aparecerá assim:

JSON
//example request
{
"portalId": 123123,
"userEmail": "test.user@example.com"
}

Você pode retornar um código de erro 200 ou qualquer outro (404 seria apropriado). Se retornar um 200, você deve retornar a uma carga útil que contém o novo ID que devemos usar no lugar de "email":

JSON
//example response
{
"id": "any-string-id"
}

Assinatura do webhook

Todos os webhooks enviados pela HubSpot são assinados pela HubSpot usando o "segredo do app" do aplicativo. Veja a seção “Segurança” nesta página: (o resto desta página de Visão geral do webhooks não se aplica a esses webhooks de extensão de videoconferência.)


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