HubSpotin tekninen integraatio-opas
HubSpot-ylläpitäjille, tietoturva-arvioijille ja IT:lle — miten Revialin molemmat HubSpot-sovellukset todentavat, API-kulutus, puheluanalyysin käsittelyketju, virhetilanteet ja auditointi.
Tämä opas kuvaa, mitä Revial tekee HubSpot-tililläsi, jotta voit hyväksyä, määrittää ja myöhemmin auditoida integraation. Yhdistäminen: Yhdistetään Revial HubSpotiin. Jokainen luettava ja kirjoitettava ominaisuus sekä kummankin sovelluksen scopet: Mitä Revial synkronoi HubSpotin kanssa.
1. Mitä hyväksyt
Revial käyttää kahta erillistä HubSpot-sovellusta, joilla kummallakin on oma client ID, tunniste ja scopet:
| Ominaisuus | HubSpot CRM -sovellus | HubSpot-puhelut |
|---|---|---|
| Tarkoitus | CRM-tietueiden synkronointi; yhteenvetojen, mäpättyjen ominaisuuksien ja diilien kirjoitus | HubSpotiin kirjattujen puheluiden analysointi |
| API:t | CRM v3 -objektit, haku, pipelinet, ominaisuudet; v4-liitokset | CRM v3 -puhelut ja omistajat; calling extensions -litteroinnit |
| Protokolla | OAuth 2.0 -valtuutuskoodi | OAuth 2.0 -valtuutuskoodi |
| Pääsymalli | Delegoitu — toimii asentaneena käyttäjänä | Delegoitu — toimii asentaneena käyttäjänä |
| Kirjoittaa HubSpotiin | Kyllä (katso datasivun luku 9) | Ei tällä hetkellä |
2. Mitä ylläpitäjäsi tarvitsee tehdä
| Tilanne | Mitä tehdä |
|---|---|
| Tilisi rajoittaa sovellusten asennuksia | Anna asennusoikeudet omaavan käyttäjän yhdistää |
| Haluat erillisen integraatiokäyttäjän | Luo se sillä näkyvyydellä, joka Revialilla kuuluu olla, ja yhdistä sillä |
| Käytät puheluanalyysia | Yhdistä puhelusovellus ja yhdistä omistajat Revial-käyttäjiin |
| Haluat Revialin kirjoittavan ominaisuuksiin | Luo ne HubSpotiin ja mäppää ne Revialissa |
Puhelusovelluksen webhook-tilaukset on määritetty kerran Revialin HubSpot-sovellukseen; tililläsi ei tarvitse määrittää mitään.
3. Todennus ja tunnistemalli
Molemmat sovellukset käyttävät samoja päätepisteitä:
| Ominaisuus | Arvo |
|---|---|
| Valtuutus | https://app.hubspot.com/oauth/authorize |
| Tunniste | https://api.hubapi.com/oauth/v1/token |
| Tunnisteen tarkistus | https://api.hubapi.com/oauth/v1/access-tokens/{token} — tallentaa portaalin tunnuksen, käyttäjän tunnuksen ja sähköpostin |
| Peruutus | DELETE https://api.hubapi.com/oauth/v1/refresh-tokens/{token} |
| PKCE | Ei käytössä |
| Pääsytunnisteen elinikä | 30 minuuttia; jokaisella päivityksellä palautetaan uusi päivitystunniste |
State. Satunnainen state, voimassa viisi minuuttia ja sidottu Revial-käyttäjään; paluukutsu tarkistaa käyttäjän ylläpitäjäroolin uudelleen. Puhelusovellus kuluttaa state-arvonsa ennen jatkamista, joten kutakin voi käyttää vain kerran.
Säilytys. Pääsy- ja päivitystunnisteet salataan levossa (AES-256-GCM), eikä niitä koskaan lähetetä selaimeen.
Päivitysvirheet. 401 tai invalid_grant on pysyvä virhe. CRM-sovelluksessa yhteys merkitään uudelleenvaltuutusta vaativaksi ja organisaation ylläpitäjälle ilmoitetaan; tunnin välein ajettava synkronointi ohittaa sen. Puhelusovelluksessa yhteyden jonossa olevat puhelut hylätään, kunnes yhteys yhdistetään uudelleen.
Kuka voi yhdistää Revialin puolella. Organisaation omistaja tai ylläpitäjä tilauksella, joka sisältää CRM-integraation; pyyntömäärää rajoitetaan. Yksi CRM-sovellusyhteys ja yksi puhelusovellusyhteys organisaatiota kohden. Portaalin voi yhdistää vain yhden organisaation puhelusovellukseen.
4. Asentava käyttäjä
Kaikki tapahtuu asentavan käyttäjän nimissä. Tietueet, joita käyttäjä ei näe, eivät päädy Revialiin, ja Revialin luomat muistiinpanot ja diilit luodaan kyseisen käyttäjän tunnisteella. Mitkä HubSpot-roolit saavat asentaa sovelluksia, määritetään HubSpot-tililläsi.
5. Synkronoinnin tahti ja API-kulutus (CRM-sovellus)
- Tahti: noin tunnin välein, alkaen heti yhdistämisen jälkeen.
- Ensimmäinen synkronointi: list-API, 100 tietuetta sivulla, enintään 50 000 objektityyppiä kohden.
- Seuraavat synkronoinnit: haku-API viimeisen muokkauspäivän mukaan suodatettuna, 100 sivulla (HubSpot rajaa hakutulokset 10 000:een kyselyä kohden).
- Aktiviteetit: enintään 3 000 synkronointia kohden; suurempi ruuhka jatkuu myöhemmissä synkronoinneissa siitä, mihin se jäi.
- Liitokset: aktiviteeteille 100 tunnisteen eräluvut; yksi pyyntö muuttunutta diiliä kohden.
- Poistot: vain poistetut (arkistoidut) diilit tunnistetaan ja poistetaan.
- Pyyntöjen rajoitus: noin 3 pyyntöä sekunnissa työprosessia kohden. 429-vastauksissa odotetaan
Retry-After-ajan verran (2 sekuntia, jos otsake puuttuu) ja 5xx-vastauksissa viivettä kasvatetaan eksponentiaalisesti, enintään 3 uudelleenyritystä; pyynnön aikakatkaisu on 30 sekuntia. - Ajoa kohden: 5 sivua ajoa kohden, jatkuu automaattisesti.
6. Puheluanalyysin käsittelyketju (puhelusovellus)
- Webhook — HubSpot ilmoittaa Revialille, kun puhelu luodaan tai sen tallenteen linkki muuttuu. Revial tarkistaa
X-HubSpot-Signature-v3-HMAC:n sovelluksen secretillä ja hylkää yli viisi minuuttia vanhat pyynnöt. Tuntemattomien portaalien tapahtumat ohitetaan. - Jono — jokainen puhelu viedään jonoon; portaali- ja puhelukohtainen lukitus varmistaa, että se käsitellään kerran.
- Omistajan tarkistus — puhelut, joilla ei ole omistajaa tai joiden omistajaa ei ole yhdistetty tai joka on suljettu pois, ohitetaan.
- Tallenne — Revial hakee tallenteen (enintään 500 Mt, 10 minuutin aikakatkaisu, vain HTTPS; tunniste lähetetään vain HubSpotin osoitteisiin) tai, jos tallennetta ei voi hakea, HubSpotin oman litteroinnin. Toimiva lähde muistetaan portaalikohtaisesti.
- Säilytys ja litterointi — tallenteet säilytetään Revialin EU-tallennustilassa ja poistetaan 365 päivän kuluttua. Jos organisaatiolle on otettu käyttöön tallenteiden poisto heti litteraatin valmistuttua, ääni poistetaan jo siinä vaiheessa. Äänen litteroi Revialin litterointipalveluntarjoaja, joka poistaa oman kopionsa käsittelyn jälkeen.
- Tapaaminen — yhdistetylle käyttäjälle luodaan Revial-tapaaminen, joka analysoidaan.
Jos tallennetta ei ole vielä liitetty, puhelua yritetään muutaman kerran ja se hylätään sitten luomatta tapaamista. Tällaisesta puhelusta ei jää Revialiin mitään merkintää — jos odottamasi puhelu ei koskaan ilmesty analysoitavaksi, ota yhteyttä tukeen.
7. Kenttien mäppäykset (CRM-sovellus)
Ylläpitäjät mäppäävät Revialin yhteenvetokenttiä ja mukautettuja poimintakenttiä kontaktien, yritysten, diilien ja tapaamisten ominaisuuksiin kohdassa Organisaatio → CRM-asetukset → Ominaisuuksien yhdistäminen. Ominaisuudet listataan crm.schemas.*.read-scopeilla. Muunnos- ja ylikirjoitussäännöt ovat datasivun luvussa 9.3.
8. Tapaamisten yhdistäminen CRM-tietueisiin
Ensimmäinen osuma voittaa: tapaamisen suorat tunnukset; avoin diili, johon tapaaminen on jo linkitetty; osallistujien sähköpostit → kontaktit → heidän diilinsä (pisteytettyinä); yritys verkkosivun tai sähköpostin verkkotunnuksen perusteella; yritys nimen perusteella. Pisteytys suosii avoimia diilejä, osallistujaa ensisijaisena kontaktina, muita osallistujia diilissä, otsikon samankaltaisuutta, pidemmälle edenneitä vaiheita ja tuoreutta. Suljetut diilit jätetään pois; ilmaisten sähköpostipalveluiden verkkotunnukset ohitetaan yritystunnistuksessa.
9. Tietoturva, rajat ja virhetilanteet
- Erilliset sovellukset: puheluanalyysin voi myöntää ilman CRM-kirjoitusoikeutta ja päinvastoin.
- Salaisuudet: tunnisteet salattu levossa; selaimelle näytetään vain yhteyden tila.
- Webhookien eheys: signature v3 ja viiden minuutin toistoikkuna.
- Tallenteiden turvallinen haku: uudelleenohjaus- ja yksityisosoitetarkistukset jokaisella välillä.
- Datan säilytys: synkronoidut tietueet ja raa'at API-vastaukset tallennetaan Revialiin ja poistetaan, kun CRM-sovelluksen yhteys katkaistaan.
10. Auditointi ja yhteyden katkaiseminen
HubSpotissa: tilisi asetusten Connected apps listaa molemmat Revial-sovellukset ja mahdollistaa niiden poistamisen; Revialin luomissa tietueissa näkyy asentanut käyttäjä.
CRM-sovelluksen yhteyden katkaiseminen Revialissa poistaa Revialin synkronoidun kopion, tunnisteet ja kenttien mäppäykset. Se ei peruuta tunnistetta — poista sovellus HubSpotissa, jos haluat päättää käyttöoikeuden.
Puhelusovelluksen yhteyden katkaiseminen Revialissa peruuttaa päivitystunnisteen HubSpotissa, poistaa omistajien yhdistämiset ja ohittaa portaalin myöhemmät webhookit. Jo luodut tapaamiset ja tallennetut tallenteet (365 päivän vanhenemiseen asti) säilyvät.
11. Vianmääritys
| Oire | Todennäköinen syy | Korjaus |
|---|---|---|
| Tietueita puuttuu synkronoinnin jälkeen | Asentavan käyttäjän näkyvyys | Yhdistä käyttäjällä, joka näkee ne |
| "CRM: Authentication expired" | Sovellus poistettu tai käyttöoikeus peruutettu | Yhdistä uudelleen |
| Puheluita ei analysoida | Omistajaa ei yhdistetty, puhelulla ei omistajaa tai tallennetta ei vielä ole | Yhdistä omistaja; tarkista, että puhelulla on tallenne |
| "HubSpot-puheluiden yhdistäminen epäonnistui" | Portaali on jo yhdistetty toiseen organisaatioon tai kirjautuminen epäonnistui | Ota yhteyttä tukeen |
| Puhelukortissa näkyy virhe | Puhelusovelluksen tunniste peruutettu | Yhdistä uudelleen |
| Poistettu yritys näkyy yhä Revialissa | Vain diilien poistot tunnistetaan | Odotettua |
Mitä Revial synkronoi HubSpotin kanssa
HubSpot-ylläpitäjällesi ja sille, joka arvioi integraation tietojen käyttöoikeudet — jokainen HubSpot-kenttä, jonka Revial lukee, kaikki mitä se kirjoittaa takaisin ja mitä jätetään tarkoituksella pois.
Yhdistetään Revial Pipedriveen
Pipedrive-ylläpitäjällesi ja sille, joka hyväksyy integraation tietojen käyttöoikeudet — kuka valtuuttaa, scopet, mitä Revial lukee ja kirjoittaa, ja mitä se tarkoituksella jättää tekemättä.