Verwenden Sie die Anrufinteraktion-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. Zur Ansicht aller verfügbaren Endpunkte und deren Anforderungen lesen Sie bitte die Referenzdokumentation.
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.
Nachfolgend finden Sie eine Liste der HubSpot-Standardanfrufeigenschaften, die Sie in das Eigenschaftsobjekt aufnehmen können. Sie können mit der Eigenschaften-API auch benutzerdefinierte Eigenschaften erstellen.
Feld
Beschreibung
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
Die Art 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:
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.
Um einen Anruf zu erstellen und bestehenden Datensätzen zuzuordnen, schließen Sie ein associations-Objekt in Ihre Anfrage ein. Um beispielsweise einen Anruf zu erstellen und ihn einem Kontakt und einem Ticket zuzuordnen, könnte Ihr Anfragetext wie folgt aussehen:
Im associations-Objekt sollten Sie Folgendes einschließen:
Feld
Beschreibung
to
Der Datensatz, den Sie dem Anruf zuordnen möchten, angegeben durch seinen eindeutigen id-Wert.
types
Der Typ der Zuordnung zwischen Anruf und Datensatz. Beziehen Sie die associationCategory und associationTypeId ein. Standardzuordnungstyp-IDs sind hier aufgeführt. Sie können den Wert für benutzerdefinierte Zuordnungstypen (d. h. Label) über die Zuordnungen-API abrufen.
Weitere Informationen zur Batch-Erstellung von Anrufen finden Sie in der Referenzdokumentation.
Sie können Anrufe einzeln oder mehrere gleichzeitig abrufen. Weitere Informationen zum Batch-Abruf finden Sie in der Referenzdokumentation.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:
Parameter
Beschreibung
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:
Parameter
Beschreibung
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.
Voicemails vs. aufgezeichnete Anrufe identifizieren
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 ist 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.
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:
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.Weitere Informationen zur Batch-Aktualisierung finden Sie in der Referenzdokumentation.
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:
Feld
Beschreibung
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
Um eine Zuordnung 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}
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-, Deals-, Tickets- und Benutzerdefinierte Objekte-APIs.
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.Weitere Informationen zum Löschen von Anrufen finden Sie in der Referenzdokumentation.
