Dieser Artikel gibt eine Übersicht über mögliche Verbindungen von matelso zu HubSpot. Die Verbindungen nutzen die Integrations 2.0 Custom Push Konfiguration. #

Dieser Artikel ist nur eine Übersicht und keine aktuelle Anleitung. Sie können die Informationen aus diesem Artikel als Grundlage verwenden, um eine eigene Integration aufzubauen. Sollten Sie dabei Hilfe benötigen, empfehlen wir den matelso Consulting Service.

1. HubSpot API Direktverbindung #

ACHTUNG: Seit dem 30.11.2022 akzeptiert die HubSpot API keine API-Schlüssel mehr. Die Authentifizierung ist derzeit nur noch über private App Access Token oder OAuth möglich. Matelso unterstützt die Authentifizierung über OAuth, der folgende Artikel bezieht sich aber noch auf die alte Methode.

Die direkte Verbindung zu HubSpot generiert für jeden Anruf an eine Call-Tracking-Nummer einen Deal. Diese Variante erfordert kein zusätzliches Skript und kann über das Control Panel eingerichtet werden.

Einrichtung in der CP

Zunächst navigieren wir zu „Konfiguration“->“Integrationen 2.0″.

Dann erstellen wir einen CustomPush über die Vorauswahltaste.

Dann vergeben wir einen Namen und den Zeitpunkt des Pushs.

In diesem Beispiel heißt der Push „HubSpot-Direct“ und als Zeitpunkt wird „POST CALL“ genutzt. Hier können auch Filter gesetzt werden, in diesem Beispiel nutzen wir das nicht.

Im nächsten Schritt tragen wir den Endpunkt der HubSpot API in den Bereich „Wohin?“. Um einen Deal anzulegen, nutzen wir den Endpunkt „https://api.hubapi.com/crm/v3/objects/deals“.

Es wird keine HTTP-Basic-Authentifizierung verwendet und die Fehlerbehandlung wird auf dem Standard belassen.

Der letzte Bereich, den wir ausfüllen müssen, ist der Bereich „Was?“. Hier setzen wir zunächst die HTTP-Methode auf „POST“. Außerdem setzen wir einen HTTP-Header „Content-Type“.

Da die Authentifizierung der HubSpot-API über den API-Schlüssel funktioniert, müssen wir den API-Schlüssel als GET-Parameter festlegen.

Im letzten Konfigurationsschritt füllen wir den POST-Body der Anfrage mit einem in der HubSpot-API definierten JSON-Objekt.

{
"properties": {
"amount":"1.00",
"dealname": "Neuer Anruf von {{callData.aNumber.number.numberFormatter (INTERNATIONAL)}}",
"dealstage": "appointment scheduled",
"pipeline": "default"
}
}

Dieses Objekt enthält eine Eigenschaft mit dem Namen „properties“. In diesem Objekt „properties“ sind 4 Eigenschaften enthalten.

Zeile 3 „Betrag“: Der Betrag/Wert des Geschäfts. Hier setzen wir statisch 1, da wir diesen Wert noch nicht kennen.

Zeile 4 „dealname“: Hier legen wir den Namen des Geschäfts fest, der in HubSpot erstellt wird. In unserem Beispiel beginnt der Name mit „Neuer Anruf von“, gefolgt von dem DDD-Schlüssel für die Anrufernummer. z.B. „Neuer Anruf von +4971196589120“.

Zeile 5 „dealstage“: Hier legen wir die Phase des Geschäfts fest. In unserem Beispiel setzen wir das Geschäft auf „appointmentscheduled“.

Zeile 6 „pipeline“: Legt fest, in welcher Pipeline der Deal erstellt wird.

2. HubSpot in Verbindung mit einem PHP-Script #

Bei dieser Konfiguration wird der Push an ein PHP-Skript gesendet. Dieses Skript sucht in HubSpot nach einem Kontakt mit der Anrufernummer und legt diesen Kontakt an, falls er nicht existiert. Anschließend wird eine Notiz mit den Anrufinformationen zu diesem Kontakt gespeichert.

PHP-Skript
Um die Logik der Kontaktsuche/Kontakterstellung abzubilden, wird ein PHP-Skript benötigt. Dieses Skript muss als .php-Datei auf einem Webserver mit PHP-Modul installiert werden.

Dieses Skript muss als .php-Datei auf einem Webserver mit PHP-Modul gespeichert werden. #

<?php

/* ----- config starts here ----- */
define("WEB_PASSWORD", "SICHERES_PASSWORT");
define("DEBUG_LOG", true);
define("HUBSPOT_API_KEY", "0ab12c34-****-****-****-************");

/* ----- check access password ----- */
if(WEB_PASSWORD != $_GET["webPasswd"]) {
return;
}

/* ----- read values from request ----- */
$aNumber = $_GET["aNumber"];

/* ----- code starts here ----- */
// log a message to the output if DEBUG_LOG is set to true
function logDebug($msg) {
if (DEBUG_LOG == true) {
echo $msg . '<br/>';
}
}
// finds a contact in hubspot by the given phone number
function findContactByNumber($number) {
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.hubapi.com/crm/v3/objects/contacts/search?hapikey=" . HUBSPOT_API_KEY,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_0,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{ \"filterGroups\": [ { \"filters\": [ { \"value\": \"" . $number . "\", \"propertyName\": \"phone\", \"operator\": \"EQ\" } ] } ], \"properties\": [ \"id\", \"phone\" ], \"limit\": 100 }",
CURLOPT_HTTPHEADER => array(
"accept: application/json",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
return null;
} else {
return $response;
}
}
// create a new contact in hubspot with the given phone number and and email address based on the phone number
function createContact($number) {
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.hubapi.com/crm/v3/objects/contacts?hapikey=" . HUBSPOT_API_KEY,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_0,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{ \"properties\": { \"email\": \"" . $number . "@call.from.calltracking.de\", \"phone\": \"" . $number . "\" } }",
CURLOPT_HTTPHEADER => array(
"accept: application/json",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
return null;
} else {
return $response;
}
}
// create notice in hubspot
function createNotice($text, $contactId) {
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.hubapi.com/engagements/v1/engagements?hapikey=" . HUBSPOT_API_KEY,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_0,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{ \"engagement\": { \"active\": true, \"ownerId\": 1, \"type\": \"NOTE\", \"timestamp\": " . time() . "000 }, \"associations\": { \"contactIds\": [ " . $contactId . "], \"companyIds\": [ ], \"dealIds\": [ ], \"ownerIds\": [ ], \"ticketIds\":[ ] }, \"attachments\": [ ], \"metadata\": { \"body\": \"". $text . "\" } }",
CURLOPT_HTTPHEADER => array(
"accept: application/json",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
return null;
} else {
return $response;
}
}
// utility method for createContact and returns the id of the newly created contact
function createContactGetId($number) {
$createRes = createContact($number);
if($createRes == null) {
return -1;
}
$hsJson = json_decode($createRes, true);
return $hsJson['id'];
}

// try to find contact by number
$contactRes = findContactByNumber($aNumber);
if($contactRes == null) {
// empty result from find. Create new contact
$hsContactId = createContactGetId($aNumber);
logDebug('No search result. Create contact ' . $hsContactId);
} else {
// deserialize the hubspot response
$hsJson = json_decode($contactRes, true);
// check whether the resultset contains entries
if(count($hsJson['results']) > 0) {
// get the id from the first search result
$hsContactId = $hsJson['results'][0]['id'];
logDebug('Found contact ' . $hsContactId);
} else {
// no search result found. create new contact
$hsContactId = createContactGetId($aNumber);
logDebug('Create contact ' . $hsContactId);
}
}

// check if hsContactId is an integer
if (!is_int(intval($hsContactId))) {
logDebug("error finding or creating contact");
return;
}

// TODO: create notice with contact
createNotice("Ein Anruf von " . $aNumber, $hsContactId);
logDebug("Notiz angelegt");

?>

Das Skript ist in 4 Blöcke unterteilt. Jeder dieser Blöcke beginnt mit einer Zeile, die mit /* beginnt und mit */ endet.

Block 1 (Zeile 3): #

Beginnt mit: /* ----- config starts here ----- */
Enthält: In diesem Block werden Konfigurationswerte gesetzt. Hier muss
man auch als Leser dieses Artikel aktiv werden.
Was tun?: Das WEB_PASSWORD und der HUBSPOT_API_KEY müssen vom Verwender gesetzt werden. Im ersten Abschnitt zur direkten Integration ist ein Link wie man einen HUBSPOT_API_KEY erzeugen kann.
Wenn DEBUG_LOG auf true gesetzt wird, werden Informationen in die Ausgabe/Rückgabe des Script geschrieben. Diese können dann auch in den Push Logs gesehen werden.

Block 2 (Zeile 8): #

Beginnt mit: /* ----- check access password ----- */
Enthält: In diesem Abschnitt wird überprüft ob die Anfrage das korrekte WEB_PASSWORD enthält. Wenn dies nicht der Fall ist, wird die Anfrage an dieser Stelle beendet.
Durch diesen Abschnitt wird verhindert das Anfragen an das PHP Script von externen etwas in HubSpot verändern.

Block 3 (Zeile 13): #

Beginnt mit: /* ----- read values from request ----- */
Enthält: In diesem Abschnitt werden die Anfrageparameter in Variablen extrahiert.

Block 4 (Zeile 16): #

Beginnt mit: /* ----- code starts here ----- */
Enthält: Hilfsfunktionen und die eigentliche Logik, welche ausgeführt wird.

Damit das PHP Script auch die Informationen bekommt, muss im matelso Control Panel noch eine Push Konfiguration eingerichtet werden.

Zunächst navigieren wir zu „Konfiguration“->“Integrationen 2.0″.

Dann erstellen wir einen CustomPush über die Vorauswahltaste.

Dann vergeben wir einen Namen und den Zeitpunkt des Pushs. Wir benutzen hier ebenfalls keinen Filter.

Im Screenshot heißt der Push „HubSpot-PHP“ und als Zeitpunkt ist „POST CALL“ ausgewählt.

Im nächsten Schritt konfigurieren wir das „Wohin?“. Hierzu brauchen wir die URL und den Namen der PHP-Datei im Webspace. In diesem Beispiel heißt die Datei „matelso-push.php“ und liegt unter „https://scripts.matelso.com/matelso-push.php“.

Jetzt müssen wir nur noch die „What? Für dieses Beispielskript müssen 2 GET-Parameter übergeben werden („aNumber“ & „webPasswd“).

Der DDD-Key „“ wird für aNumber verwendet.