Anrufe

ÜberblickEndpunkte

Verwenden Sie die Anrufinteraktions-API, um Anrufe in CRM-Datensätzen und auf der Indexseite für Anrufe zu protokollieren und zu verwalten. Sie können Anrufe entweder in HubSpot oder über die Anrufe-API protokollieren. Im Folgenden erfahren Sie, wie Sie Anrufe über die API verwalten können. Um alle verfügbaren Endpunkte und deren Anforderungen anzuzeigen, klicken Sie oben in diesem Artikel auf die Registerkarte Endpunkte.

Eine Anrufinteraktion erstellen

Um eine Anrufinteraktion zu erstellen, führen Sie eine POST-Anfrage an /crm/v3/objects/calls durch.

Fügen Sie im Anfragetext Anrufdetails in einem properties-Objekt hinzu. Sie können auch ein associations-Objekt hinzufügen, um Ihren neuen Anruf einem vorhandenen Datensatz (z. B. Kontakten, Unternehmen) zuzuordnen.

Eigenschaften

Im properties-Objekt können Sie die folgenden Felder einschließen:

Use this table to describe parameters / fields
FeldDescription
hs_timestamp

Erforderlich. Dieses Feld markiert den Zeitpunkt der Erstellung des Anrufs und bestimmt, wo Sie den Anruf in der Datensatzchronik finden. Sie können entweder einen Unix-Zeitstempel im Millisekunden- oder UTC-Format verwenden. 

hs_call_body

Die Beschreibung des Anrufs, einschließlich aller Anmerkungen, die Sie hinzufügen möchten.

hs_call_callee_object_id

Die ID des HubSpot-Datensatzes, der dem Anruf zugeordnet ist. Dies ist der Empfänger des Anrufs für OUTBOUND-Anrufe oder der Wähler des Anrufs für INBOUND-Anrufe.

hs_call_callee_object_type_id

Die ID des Objekts, zu dem der zugeordnete Datensatz des Anrufs gehört (gibt z. B. an, ob der Datensatz ein Kontakt oder ein Unternehmen ist). Dies ist das Objekt des Empfängers für OUTBOUND-Anrufe oder das Objekt des Wählers für INBOUND-Anrufe.

hs_call_direction

Die Richtung des Anrufs aus der Perspektive des HubSpot-Benutzers. Wenn der Benutzer der Anrufempfänger ist, sollte die Richtung auf INBOUND festgelegt werden. Wenn der Benutzer den Anruf initiiert hat, sollte die Richtung auf OUTBOUND festgelegt werden.

hs_call_disposition

Das Ergebnis des Anrufs. Um die Anrufdisposition einzustellen, müssen Sie den internen GUID-Wert verwenden. Wenn für Ihren Account benutzerdefinierte Anrufergebnisse eingerichtet sind, können Sie deren Dispositions-GUIDs mithilfe dieser API finden. Die standardmäßigen HubSpot-Ergebnislabels und ihre internen Werte sind:

  • Besetzt: 9d9162e7-6cf3-4944-bf63-4dff82258764
  • Verbunden: f240bbac-87c9-4f6e-bf70-924b57d47db7
  • Hat Live-Nachricht hinterlassen: a4c4c377-d246-4b32-a13b-75a56a4cd0ff
  • Hat Voicemail hinterlassen: b2cf5968-551e-4856-9783-52b3da59a7d0
  • Keine Antwort: 73a0d17f-1163-4015-bdd5-ec830791da20
  • Falsche Nummer: 17b47fee-58de-441e-a44c-c6300d46f273
hs_call_duration

Die Dauer des Anrufs in Millisekunden.

hs_call_from_number

Die Telefonnummer, von der aus der Anruf getätigt wurde.

hs_call_recording_url

Die URL, die die Anrufaufzeichnung speichert. URLS zu .mp3- oder .wav-Dateien können in CRM-Datensätzen wiedergegeben werden. Nur HTTPS, sichere URLs werden akzeptiert.

hs_call_status

Der Status des Anrufs. Die Status sind BUSY, CALLING_CRM_USER, CANCELED, COMPLETED, CONNECTING, FAILED, IN_PROGRESS, NO_ANSWER, QUEUED und RINGING.

hs_call_title

Der Titel des Anrufs.

hs_call_source

Die Quelle des Anrufs. Diese ist nicht erforderlich, aber sie ist notwendig, um die Aufnahme- und Transkriptionspipeline zu nutzen. Wenn die Eigenschaft festgelegt wird, muss sie auf INTEGRATIONS_PLATFORM festgelegt werden.

hs_call_to_number

Die Telefonnummer, die den Anruf erhalten hat.

hubspot_owner_id

Die ID des zuständigen Mitarbeiters, der dem Anruf zugeordnet ist. Dieses Feld bestimmt den Benutzer, der in der Datensatzchronik als Anrufersteller aufgeführt ist.

hs_activity_type

Der Typ von Anruf Die Optionen basieren auf den in Ihrem HubSpot-Account festgelegten Anruftypen.

hs_attachment_ids

Die IDs der Anhänge des Anrufs. Mehrere Anhang-IDs sind durch ein Semikolon getrennt.

Zuordnungen

Um einen Anruf zu erstellen und bestehenden Datensätzen zuzuordnen, schließen Sie ein associations-Objekt in Ihre Anfrage ein. Das Objekt sollte die folgenden Felder enthalten:

Use this table to describe parameters / fields
FeldDescription
toObjectId

Die ID des Datensatzes, dem Sie den Anruf zuordnen möchten.

associationType

Eine eindeutige ID, die den Zuordnungstyp zwischen dem Anruf und dem anderen Objekt angibt. Die ID kann numerisch oder in Snake-Case (z. B. call_to_contact) dargestellt werden. Sie können den Wert über die Zuordnungen-API abrufen.

Um beispielsweise einen Anruf zu erstellen und ihn einem Kontakt und einem Ticket zuzuordnen, könnte Ihr Anfragetext wie folgt aussehen:

// Example request body { "properties": { "hs_timestamp": "2021-03-17T01:32:44.872Z", "hs_call_title": "Support call", "hubspot_owner_id": "11349275740", "hs_call_body": "Resolved issue", "hs_call_duration": "3800", "hs_call_from_number": "(857) 829 5489", "hs_call_to_number": "(509) 999 9999", "hs_call_recording_url": "https://api.twilio.com/2010-04-01/Accounts/AC890b8e6fbe0d989bb9158e26046a8dde/Recordings/RE3079ac919116b2d22", "hs_call_status": "COMPLETED" }, "associations": [ { "to": { "id": 500 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 194 } ] }, { "to": { "id": 1234 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 220 } ] }] }

Erfahren Sie mehr über das Erstellen von Anrufen, indem Sie oben in diesem Artikel auf die Registerkarte Endpunkte klicken.

Anrufe abrufen

Sie können Anrufe einzeln oder mehrere gleichzeitig abrufen. Erfahren Sie mehr über Massenabrufe, indem Sie oben in diesem Artikel auf die Registerkarte Endpunkte klicken.

Um einen einzelnen Anruf anhand seiner Anruf-ID abzurufen, führen Sie eine GET-Anfrage an /crm/v3/objects/calls/{callId} durch. Sie können die folgenden Parameter in die Anfrage-URL einschließen: 

Use this table to describe parameters / fields
ParameterDescription
properties

Eine durch Kommas getrennte Liste der Eigenschaften, die zurückgegeben werden sollen. 

associations

Eine durch Kommas getrennte Liste von Objekttypen, für die zugehörige IDs abgerufen werden sollen. Alle angegebenen Zuordnungen, die nicht vorhanden sind, werden nicht in der Antwort zurückgegeben. Erfahren Sie mehr über die Zuordnungen-API.

Um eine Liste aller Anrufe anzufordern, führen Sie eine GET-Anfrage an /crm/v3/objects/calls durch. Sie können die folgenden Parameter in die Anfrage-URL einschließen: 

Use this table to describe parameters / fields
ParameterDescription
limit

Die maximale Anzahl an Ergebnissen, die pro Seite angezeigt werden können.

properties

Eine durch Kommas getrennte Liste der Eigenschaften, die zurückgegeben werden sollen. 

Wenn Sie eine erfolgreiche Anfrage stellen, enthält die Antwort die callId, mit der Sie den Anruf abrufen, aktualisieren und löschen können. 

Identify voicemails vs. recorded calls

Für aufgezeichnete Anrufe und Voicemails wird eine Aufzeichnung in der hs_call_recording_url-Eigenschaft gespeichert. Wenn Ihr Account Zugriff auf Inbound-Calling hat, schließen Sie, um zwischen abgeschlossenen bzw. aufgezeichneten Anrufen und eingehenden Anrufen mit einer Voicemail zu unterscheiden, die folgenden Eigenschaften in Ihre Anfrage ein: hs_call_status und hs_call_has_voicemail.

Wenn ein Anruf eine Voicemail hat, ist der hs_call_status-Wert missed und der hs_call_has_voicemail-Wert true. Der hs_call_has_voicemail-Wert ist false für einen eingehenden Anruf, bei dem keine Voicemail hinterlassen wurde, oder null, wenn der Anruf einen anderen Status als „verpasst“ hat.

Anrufe aktualisieren

Sie können Anrufe einzeln oder mehrere gleichzeitig aktualisieren. Um einen einzelnen Anruf anhand seiner Anruf-ID zu aktualisieren, führen Sie eine PATCH-Anfrage an/crm/v3/objects/calls/{callId} durch. 

Fügen Sie im Anfragetext die Anrufeigenschaften ein, die Sie aktualisieren möchten:

//Example PATCH request to https://api.hubspot.com/crm/v3/objects/calls/{callID} { "properties": { "hs_timestamp": "2021-03-17T01:32:44.872Z", "hs_call_title": "Discovery call", "hubspot_owner_id": "11349275740", "hs_call_body": " Decision maker out, will call back tomorrow", "hs_call_duration": "3800", "hs_call_from_number": "(857) 829 5489", "hs_call_to_number": "(509) 999 9999", "hs_call_recording_url": "https://api.twilio.com/2010-04-01/Accounts/AC890b8e6fbe0d989bb9158e26046a8dde/Recordings/RE3079ac919116b2d22", "hs_call_status": "COMPLETED" } }'

HubSpot ignoriert Werte für schreibgeschützte und nicht vorhandene Eigenschaften. Um einen Eigenschaftswert zu löschen, übergeben Sie eine leere Zeichenfolge für die Eigenschaft im Anfragetext.

Erfahren Sie mehr über Massenaktualisierungen, indem Sie oben in diesem Artikel auf die Registerkarte Endpunkte klicken.

Vorhandene Anrufe zu Datensätzen zuordnen

Um einen Anruf Datensätzen zuzuordnen, z. B. einem Kontakt und seinen zugeordneten Unternehmen, führen Sie eine PUT-Anfrage an /crm/v3/objects/calls/{callId}/associations/{toObjectType}/{toObjectId}/{associationTypeId} durch. Die Anfrage-URL enthält die folgenden Felder:

Use this table to describe parameters / fields
FeldDescription
callId

Die ID des Anrufs.

toObjectType

Der Typ des Objekts, dem Sie den Anruf zuordnen möchten (z. B. Kontakt oder Unternehmen)

toObjectId

Die ID des Datensatzes, dem Sie den Anruf zuordnen möchten.

associationTypeId

Eine eindeutige ID, die den Zuordnungstyp zwischen dem Anruf und dem anderen Objekt angibt. Die ID kann numerisch oder in Snake-Case (z. B. call_to_contact) dargestellt werden. Sie können den Wert über die Zuordnungen-API abrufen.

Ihre Anfrage-URL könnte beispielsweise wie folgt aussehen:

https://api.hubspot.com/crm/v3/objects/calls/17591596434/associations/contact/104901/194

Eine Zuordnung entfernen

Um eine Verknüpfung zwischen einem Anruf und einem Datensatz zu entfernen, führen Sie eine DELETE-Anfrage an dieselbe URL wie oben durch:

/crm/v3/objects/calls/{callId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}

Einen Anruf in einem Datensatz anpinnen

Sie können einen Anruf in einem Datensatz anpinnen, damit er oben in der Chronik des Datensatzes bleibt.Der Anruf muss bereits vor dem Anpinnen dem Datensatz zugeordnet sein, und Sie können nur eine Aktivität pro Datensatz anpinnen. Um einen Anruf anzupinnen, fügen Sie die id des Anrufs in das hs_pinned_engagement_id-Feld ein, wenn Sie einen Datensatz über die Objekt-APIs erstellen oder aktualisieren. Erfahren Sie mehr über das Verwenden der Unternehmen-, Kontakte-, Angebote-, Tickets- und Benutzerdefinierte Objekte-APIs.

Anrufe löschen

Sie können Anrufe einzeln oder mehrere gleichzeitig löschen, wodurch der Anruf dem Papierkorb in HubSpot hinzugefügt wird. Sie können später den Anruf über die Datensatzchronik wiederherstellen.

Um einen einzelnen Anruf anhand seiner Anruf-ID zu löschen, führen Sie eine DELETE-Anfrage an /crm/v3/objects/calls/{callId} durch.

Erfahren Sie mehr über Massenlöschungen, indem Sie oben in diesem Artikel auf die Registerkarte Endpunkte klicken.

War dieser Artikel hilfreich?
Dieses Formular dient dazu, Feedback zu unserer Entwicklerdokumentation zu sammeln. Wenn Sie uns Ihre Meinung zu HubSpot-Produkten mitteilen möchten, teilen Sie diese bitte im Ideenforum der Community.