Appels

PrésentationPoints de terminaison

Utilisez l'API d'engagement des appels pour documenter et gérer les appels sur les fiches d'informations CRM et sur la page index des appels. Vous pouvez enregistrer des appels soit dans HubSpot soit via l'API d'appels. Ci-dessous, découvrez les méthodes de base pour gérer les appels via l'API. Pour afficher tous les points de terminaison disponibles et leurs exigences, cliquez sur l'onglet Points de terminaison en haut de cet article.

Créer un engagement d'appel

Pour créer un engagement d'appel, effectuez une requête POST à /crm/v3/objects/calls.

Dans le corps de la requête, ajoutez les détails d'appel dans un objet properties. Vous pouvez également ajouter un objet d'association pour associer votre nouvel appel à une fiche d'informations existante (par exemple, des contacts ou des entreprises).

Propriétés

Dans l'objet de propriété, vous pouvez inclure les champs suivants :

Use this table to describe parameters / fields
ChampDescription
hs_timestamp

Obligatoire. Ce champ indique l'heure de création de l'appel et détermine où se trouve l'appel sur la chronologie de la fiche d'informations. Vous pouvez utiliser soit un horodatage Unix en millisecondes, soit un format UTC. 

hs_call_body

La description de l'appel, y compris les notes que vous souhaitez ajouter.

hs_call_callee_object_id

L'ID de la fiche d'informations HubSpot associée à l'appel. Il s'agit du destinataire de l'appel pour les appels SORTANTS, ou de la personne ayant composé le numéro pour les appels ENTRANTS.

hs_call_callee_object_type_id

L'ID de l'objet auquel la fiche d'informations associée à l'appel appartient (par exemple, spécifie si la fiche d'informations est un contact ou une entreprise). Il s'agit de l'objet du destinataire pour les appels SORTANTS, ou de l'objet de la personne ayant composé le numéro pour les appels ENTRANTS.

hs_call_direction

La direction de l'appel du point de vue de l'utilisateur HubSpot. Si l'utilisateur est le destinataire de l'appel, la direction doit être définie sur ENTRANT. Si l'utilisateur a lancé l'appel, la direction doit être définie sur SORTANT.

hs_call_disposition

Le résultat de l'appel. Pour définir la disposition des appels, vous devez utiliser la valeur interne du GUID. Si votre compte a configuré des résultats d'appel personnalisés, vous pouvez trouver leurs GUID de disposition à l'aide de cette API. Par défaut, les libellés de résultat HubSpot et leurs valeurs internes sont :

  • Occupé : 9d9162e7-6cf3-4944-bf63-4dff82258764
  • Connecté : f240bbac-87c9-4f6e-bf70-924b57d47db7
  • A laissé un message en direct : a4c4c377-d246-4b32-a13b-75a56a4cd0ff
  • A laissé un message vocal : b2cf5968-551e-4856-9783-52b3da59a7d0
  • Aucune réponse : 73a0d17f-1163-4015-bdd5-ec830791da20
  • Mauvais numéro : 17b47fee-58de-441e-a44c-c6300d46f273
hs_call_duration

La durée de l'appel en millisecondes.

hs_call_from_number

Le numéro de téléphone à partir duquel l'appel a été effectué.

hs_call_recording_url

L'URL qui stocke la fiche d'informations de l'appel. LES URL des fichiers .mp3 ou .wav peuvent être lues sur des fiches d'information CRM. Seules les URL HTTPS sécurisées seront acceptées.

hs_call_status

Le statut de l'appel. Les statuts sont OCCUPÉ, CALLING_CRM_USER, ANNULÉ, TERMINÉ, CONNEXION, ÉCHEC, EN_COURS, AUCUNE_RÉPONSE, FILE D'ATTENTE et SONNERIE.

hs_call_title

Le titre de l'appel.

hs_call_source

La source de l'appel. Cette information n'est pas obligatoire, sauf pour exploiter le pipeline des enregistrements et des transcriptions. Si la propriété est définie, elle doit être définie sur INTEGRATIONS_PLATFORM.

hs_call_to_number

Le numéro de téléphone qui a reçu l'appel.

hubspot_owner_id

L'ID du propriétaire associé à l'appel. Ce champ détermine l'utilisateur listé comme le créateur d'appel sur la chronologie de la fiche d'informations.

hs_activity_type

Le type d'appel. Les options sont basées sur les types d'appel définis dans votre compte HubSpot.

hs_attachment_ids

Les ID des pièces jointes de l'appel. Les ID de pièces jointes multiples sont séparés par un point-virgule.

Associations

Pour créer et associer un appel à des fiches d'informations existantes, incluez un objet d'association dans votre demande. L'objet doit inclure les champs suivants :

Use this table to describe parameters / fields
ChampDescription
toObjectId

L'ID de la fiche d'informations avec laquelle vous souhaitez associer l'appel.

associationType

Un identifiant unique pour indiquer le type d'association entre l'appel et l'autre objet. L'ID peut être représenté numériquement ou en snake case (ex : call_to_contact). Vous pouvez récupérer la valeur via l'API des associations.

Par exemple, pour créer un appel et l'associer à un contact et à un ticket, votre corps de demande peut ressembler à ce qui suit :

// 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 } ] }] }

Pour en savoir plus sur la création d'appels par lots, cliquez sur l'onglet Points de terminaison en haut de cet article.

Récupérer des appels

Vous pouvez récupérer des appels individuellement ou en lot. Pour en savoir plus sur la récupération par lot, cliquez sur l'onglet Points de terminaison en haut de cet article.

Pour récupérer un appel individuel par son ID d'appel, effectuez une requête GET à /crm/v3/objects/calls/{callId}. Vous pouvez inclure les paramètres suivants dans l'URL de la requête : 

Use this table to describe parameters / fields
ParameterDescription
properties

Une liste séparée par des virgules des propriétés à renvoyer. 

associations

Une liste séparée par des virgules des types d'objets pour lesquels récupérer les ID associés. Les associations spécifiées qui n'existent pas ne seront pas renvoyées dans la réponse. Découvrez-en davantage sur l'API des associations.

Pour demander une liste de tous les appels, effectuez une requête GET à /crm/v3/objects/calls. Vous pouvez inclure les paramètres suivants dans l'URL de la requête : 

Use this table to describe parameters / fields
ParameterDescription
limit

Le nombre maximum de résultats à afficher par page.

properties

Une liste séparée par des virgules des propriétés à renvoyer. 

Lorsque vous effectuez une requête réussie, la réponse inclut l'ID d'appel que vous pouvez utiliser pour récupérer, mettre à jour et supprimer l'appel. 

Identify voicemails vs. recorded calls

Pour les appels enregistrés et les messages vocaux, un enregistrement est stocké dans la propriété hs_call_recording_url. Si votre compte a accès aux appels entrants, pour différencier appels terminés et enregistrés des appels entrants avec messages vocaux, incluez les propriétés suivantes dans votre demande : hs_call_status et hs_call_has_voiceemail. 

Si un appel a un message vocal, la valeur hs_call_status sera missed et la valeur hs_call_has_voiceemail sera true. La valeur hs_call_has_voicemail sera false pour un appel entrant où aucun message vocal n'a été laissé, ou null si l'appel a un statut autre que Manqué.

Mettre à jour les appels

Vous pouvez mettre à jour les appels individuellement ou par lots. Pour mettre à jour un appel individuel par son ID d'appel, effectuez une requête PATCH à /crm/v3/objects/calls/{callId}. 

Dans le corps de la requête, incluez les propriétés d'appel que vous souhaitez mettre à jour :

//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 ignorera les valeurs des propriétés inexistantes ou en lecture seule. Pour effacer une valeur de propriété, passez une chaîne vide comme valeur de propriété dans le corps de la requête.

Pour en savoir plus sur la mise à jour par lots, cliquez sur l'onglet Points de terminaison en haut de cet article.

Associer des appels existants à des fiches d'informations

Pour associer un appel à des fiches d'informations, comme un contact et ses entreprises associées, effectuez une demande PUT à /crm/v3/objects/calls/{callId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}. L'URL de la requête contient les champs suivants :

Use this table to describe parameters / fields
ChampDescription
callId

L'ID de l'appel.

toObjectType

Le type d'objet auquel vous souhaitez associer l'appel (par exemple, contact ou entreprise)

toObjectId

L'ID de la fiche d'informations avec laquelle vous souhaitez associer l'appel.

associationTypeId

Un identifiant unique pour indiquer le type d'association entre l'appel et l'autre objet. L'ID peut être représenté numériquement ou en snake case (ex : call_to_contact). Vous pouvez récupérer la valeur via l'API des associations.

Par exemple, l'URL de votre requête peut ressembler à ce qui suit :

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

Supprimer une association

Pour supprimer une association entre un appel et une fiche d'informations, faites une requête DELETE à la même URL que ci-dessus :

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

Épingler un appel sur une fiche d'informations

Vous pouvez épingler un appel sur une fiche d'informations afin qu'il reste en haut de la chronologie de la fiche d'informations. L'appel doit déjà être associé à la fiche d'informations avant d'être épinglé, et vous ne pouvez épingler qu'une seule activité par fiches d'informations. Pour épingler un appel, incluez l'identifiant de l'appel dans le champ hs_pinned_engagement_id lors de la création ou de la mise à jour d'une fiche d'informations via les API objet. En savoir plus sur l'utilisation des API d'entreprises, de contacts, de transactions, de tickets et d'objets personnalisés.

Supprimer des appels

Vous pouvez supprimer les appels individuellement ou par lots, ce qui placera l'appel à la corbeille dans HubSpot. Vous pouvez ensuite restaurer l'appel à partir de la chronologie des fiches d'informations.

Pour supprimer un appel individuel avec son ID d'appel, effectuez une requête DELETE à /crm/v3/objects/calls/{callId}.

Pour en savoir plus sur la suppression par lot, cliquez sur l'onglet Points de terminaison en haut de cet article.

Cet article vous a-t-il été utile ?
Ce formulaire est destiné à recueillir les avis sur la documentation pour les développeurs. Si vous souhaitez faire part de votre avis sur les produits HubSpot, veuillez le partager sur le forum des idéesde la communauté.