Usando a API de videoconferência, você pode configurar um aplicativo público para dar aos usuários do HubSpot a capacidade de adicionar um link de videoconferência ao criar uma reunião,, semelhante à integração do Google Meet e do Zoom. Usar essa API envolverá o seguinte:
- Configurar seu aplicativo público com webhooks de extensão de videoconferência. Você configurará seu aplicativo com os URIs que o HubSpot vai usar para notificar você quando reuniões estiverem sendo criadas, atualizadas ou excluídas.
- Configurar um back-end personalizado para lidar com a criação de reuniões e atualizar os webhooks.
- Se necessário, configurar seu back-end para lidar com webhooks de verificação de identificação do usuário.
Todas as solicitações para a API de videoconferência devem ser autenticadas usando o Chave de API de desenvolvedor da sua conta de desenvolvedor. Você pode incluir a chave em um parâmetro de consulta hapikey
no final do URL de solicitação. Você pode encontrar sua chave de API de desenvolvedor em sua conta de desenvolvedor.
Antes de começar, verifique se você criou uma conta de desenvolvedor e um aplicativo público dentro dela.
Para que o HubSpot saiba para onde enviar notificações quando as reuniões forem criadas, atualizadas ou excluídas, você primeiro configurará os URLs de webhook da extensão.
Para fazer isso, faça uma solicitação PUT
para /crm/v3/extensions/videoconferencing/settings/{appId}?hapikey=YOUR_HUBSPOT_DEVELOPER_API_KEY
.
No corpo da solicitação, será necessário incluir createMeetingUrl
para definir o URL ao qual o HubSpot enviará as cargas do webhook de criação de reunião. Opcionalmente, você pode incluir URLs de webhook adicionais. Esses valores podem ser atualizados posteriormente usando o mesmo URL de solicitação.
// Example request
{
"createMeetingUrl": "https://example.com/create-meeting",
"updateMeetingUrl": "https://example.com/update-meeting",
"deleteMeetingUrl": "https://example.com/delete-meeting"
}
Campo | Tipo | Descrição |
---|---|---|
createMeetingUrl Obrigatório | String | O URL que o HubSpot vai notificar quando uma nova reunião for criada. Isso incluirá uma carga JSON com os detalhes da reunião. O URL deve usar o protocolo https . |
updateMeetingUrl | String | O URL que o HubSpot vai notificar quando uma reunião existente for atualizada. Isso incluirá uma carga JSON com os detalhes atualizados da reunião. O URL deve usar o protocolo https . |
deleteMeetingUrl | String | O URL que o HubSpot vai notificar quando uma reunião existente for excluída. Isso incluirá um conferenceId da reunião excluída. O URL deve usar o protocolo https . |
userVerifyUrl | String | O URL que o HubSpot usará para verificar se um usuário existe no sistema externo de videoconferência. |
Exemplo de resposta:
xxxxxxxxxx
// Example 200 response
{
"createMeetingUrl": "https://example.com/create-meeting",
"updateMeetingUrl": "https://example.com/update-meeting",
"deleteMeetingUrl": "https://example.com/delete-meeting"
}
Para recuperar URLs de webhook configurados para um aplicativo existente, faça uma solicitação GET
para /crm/v3/extensions/videoconferencing/settings/{appId}
.
A resposta incluirá os URLs de webhook configurados no momento.
xxxxxxxxxx
// 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"
}
Depois que os URLs de webhook forem configurados, o HubSpot enviará cargas para esses URLs quando ocorrer um evento de criação, atualização ou exclusão de reunião.
Todos os webhooks enviados pelo HubSpot são assinados pelo HMAC usando o segredo do seu aplicativo. Saiba mais sobre isso na documentação de segurança de webhooks (o restante da página não se aplica a estes webhooks de extensão de videoconferência).
Quando uma reunião é criada, o HubSpot enviará uma solicitação para o URL especificado no campo createMeetingUrl
. A carga da solicitação inclui informações sobre a conta da HubSpot, o usuário associado e detalhes da reunião.
xxxxxxxxxx
// Example payload
{
"portalId": 123123,
"userId": 123,
"userEmail": "test.user@example.com",
"topic": "A Test Meeting",
"source": "MEETINGS",
"startTime": 1534197600000,
"endTime": 1534201200000
}
Campo | Tipo | Descrição |
---|---|---|
portalId | Número | O ID da conta da HubSpot que originou a solicitação. |
userId | Número | O ID do usuário da HubSpot atribuído à reunião. |
userEmail | String | O endereço de e-mail do usuário da HubSpot atribuído à reunião. |
topic | String | O título da reunião. |
source | String | Indica onde a reunião foi criada. Pode ser:
|
startTime | Número | O horário de início da reunião (em milissegundos de época). |
endTime | Número | O horário final da reunião (em milissegundos de época). |
Para lidar com este webhook, você 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. Os campos esperados na resposta são:
conferenceId
: um ID exclusivo associado à conferência neste evento.
Esse ID precisa ser globalmente exclusivo no seu sistema. O HubSpot vai retornar este ID
de volta a você no webhook de atualização.conferenceUrl:
o URL que os usuários podem usar para ingressar na conferência.conferenceDetails
: informações de "convite" em texto simples. Ele deve descrever
como os participantes do evento podem acessar a videoconferência desse
evento. Novas linhas serão mantidas em representações deste texto, mas nenhuma outra formatação é suportada.
Por exemplo, sua resposta pode parecer com a seguinte:
xxxxxxxxxx
//example response
{
"conferenceId": "some-unique-id",
"conferenceUrl": "https://example.com/join",
"conferenceDetails": "Click here to join: https://example.com/join"
}
Se você especificar um updateMeetingUrl
, 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. A carga da solicitação inclui informações sobre a conta da HubSpot, o usuário associado e detalhes da reunião.
xxxxxxxxxx
//example request
{
"conferenceId": "some-unique-id",
"userId": 123,
"userEmail": "test.user@example.com",
"portalId": 123123,
"topic": "A Test Meeting (updated)",
"startTime": 1534197600000,
"endTime": 1534201200000
}
Campo | Tipo | Descrição |
---|---|---|
conferenceId | String | O identificador exclusivo para a conferência fornecido por sua integração na resposta ao webhook de reunião. |
userId | Número | O ID do usuário da HubSpot atribuído à reunião. Este será sempre o mesmo usuário que o da carga de criação da reunião. |
userEmail | String | O endereço de e-mail do usuário da HubSpot atribuído à reunião. Este será sempre o mesmo usuário que o da carga de criação da reunião. |
portalId | Número | O ID da conta da HubSpot que originou a solicitação. |
topic | String | O título da reunião. |
startTime | Número | O horário de início da reunião (em milissegundos de época). |
endTime | Número | O horário final da reunião (em milissegundos de época). |
Nenhum corpo de resposta é obrigatório ao responder a essas solicitações. Apenas um código de resposta 200
ou 204
é obrigatório para que o HubSpot saiba que esse webhook foi recebido com sucesso.
Quando uma reunião é excluída no HubSpot, uma solicitação é enviada para o URL especificado no campo deleteMeetingUrl
. A carga incluirá conferenceId
da reunião excluída.
xxxxxxxxxx
// Example payload
{
"conferenceId": "some-unique-id"
}
Nenhum corpo de resposta é obrigatório ao responder a essas solicitações. Apenas um código de resposta 200
ou 204
é obrigatório para que o HubSpot saiba que esse webhook foi recebido com sucesso.
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 o HubSpot fazer uma chamada para o seu sistema para criar, atualizar ou excluir um link de videoconferência, primeiro ele verificará as configurações do aplicativo para um campo userVerifyUrl
. Se esse URL tiver sido definido, o HubSpot fará uma chamada para ele para recuperar seu identificador de usuário nativo. Vamos enviar esse identificador como o endereço de e-mail do usuário na chamada subsequente. Se você não configurou esse URL, o HubSpot sempre vai supor que a identidade do usuário foi verificada.
Essa configuração é opcional e cabe a você determinar se ela é necessária. 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 carga deste webhook contém o ID da conta da HubSpot e o Endereço de e-mail do usuário.
xxxxxxxxxx
//example request
{
"portalId": 123123,
"userEmail": "test.user@example.com"
}
Você pode retornar um código de resposta 200
ou qualquer outro código de erro (404
seria apropriado). Se retornar 200
, você deve retornar a uma carga útil que contém o novo ID que devemos usar no lugar do endereço de e-mail:
xxxxxxxxxx
//example response
{
"id": "any-string-id"
}