> ## Documentation Index > Fetch the complete documentation index at: https://developers.hubspot.fr/docs/llms.txt > Use this file to discover all available pages before exploring further. # Engagements | Appels > Utilisez l'API d'engagement des appels pour enregistrer et gérer les appels dans les fiches d'informations CRM. > **[Run in Postman](https://app.getpostman.com/run-collection/dd75d149eaa15806754f)** > **Exigences de portée** 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](https://knowledge.hubspot.com/fr/records/view-and-filter-records). Vous pouvez enregistrer des appels soit [dans HubSpot](https://knowledge.hubspot.com/fr/records/manually-log-activities-on-records) soit via l'API d'appels. Ci-dessous, découvrez les méthodes de base pour gérer les appels via l'API. Pour connaître tous les points de terminaison disponibles et leurs exigences, consultez la [documentation de référence](https://developers.hubspot.fr/docs/api-reference/crm-calls-v3/guide.md). ## 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 Vous trouverez ci-dessous une liste des propriétés d'appel par défaut de HubSpot que vous pouvez inclure dans l'objet de propriétés. Vous pouvez également créer des propriétés personnalisées à l'aide de l'[API des propriétés](https://developers.hubspot.fr/docs/api-reference/crm-properties-v3/guide.md). | Champ | Description | | - | - | | `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 `OUTBOUND`, ou de la personne ayant composé le numéro pour les appels `INBOUND`. | | `hs_call_callee_object_type` | 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 `OUTBOUND`, ou de l'objet de la personne ayant composé le numéro pour les appels `INBOUND`. | | `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 `INBOUND`. Si l'utilisateur a lancé l'appel, la direction doit être définie sur `OUTBOUND`. | | `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](https://knowledge.hubspot.com/fr/calling/create-custom-call-and-meeting-outcomes), vous pouvez trouver leurs GUID de disposition à l'aide de [cette API](https://developers.hubspot.fr/docs/api-reference/crm-communications-v3/guide.md#get-call-engagement-dispositions). Par défaut, les libellés de résultat HubSpot et leurs valeurs internes sont : | | `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 `BUSY`, `CALLING_CRM_USER`, `CANCELED`, `COMPLETED`, `CONNECTING`, `FAILED`, `IN_PROGRESS`, `NO_ANSWER`, `QUEUED` et `RINGING`. | | `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](https://developers.hubspot.fr/docs/apps/legacy-apps/extensions/calling-extensions/recordings-and-transcriptions.md#log-a-call-with-your-app-s-endpoint-using-the-engagements-api). 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](https://developers.hubspot.fr/docs/api-reference/crm-crm-owners-v3/guide.md) 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'appels définis dans votre compte HubSpot.](https://knowledge.hubspot.com/fr/meetings-tool/how-do-i-create-and-use-call-and-meeting-types) | | `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 requête. Par exemple, pour créer un appel et l'associer à un contact et à un ticket, votre corps de requête peut ressembler à ce qui suit : ```json theme={null} // 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 } ] } ] } ``` Dans l'objet d'association, vous devez ajouter les éléments suivants : | Champ | Description | | - | - | | `to` | La fiche d'informations à laquelle vous souhaitez associer l'appel, en fonction de sa valeur unique `id`. | | `types` | Le type d'association entre l'appel et la fiche d'informations. Inclut `associationCategory` et `associationTypeId`. Les ID de types d'association par défaut sont répertoriés [ici](https://developers.hubspot.fr/docs/api-reference/crm-associations-v4/guide.md#association-type-id-values), ou vous pouvez récupérer la valeur des types d'associations personnalisés (c'est-à-dire les libellés) via l'[API des associations](https://developers.hubspot.fr/docs/api-reference/crm-associations-v4/guide.md#retrieve-association-types). | Pour en savoir plus sur la création d'appels par lots, consultez la [documentation de référence](https://developers.hubspot.fr/docs/api-reference/crm-calls-v3/guide.md#post-%2Fcrm%2Fv3%2Fobjects%2Fcalls%2Fbatch%2Fcreate). ## 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 des lots, consultez la [documentation de référence](https://developers.hubspot.fr/docs/api-reference/crm-calls-v3/guide.md#post-%2Fcrm%2Fv3%2Fobjects%2Fcalls%2Fbatch%2Fread). 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 : | Paramètre | Description | | - | - | | `properties` | Une liste séparée par des virgules [des propriétés](#call-properties-1) à 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.](https://developers.hubspot.fr/docs/api-reference/crm-associations-v4/guide.md) | 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 : | Paramètre | Description | | - | - | | `limit` | Le nombre maximum de résultats à afficher par page. | | `properties` | Une liste séparée par des virgules [des propriétés](#call-properties-1) à renvoyer. | Lorsque vous effectuez une requête réussie, la réponse inclut le `callId` que vous pouvez utiliser pour récupérer, mettre à jour et supprimer l'appel. ## Identifier les messages vocaux par rapport aux appels enregistrés 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](https://knowledge.hubspot.com/fr/calling/receive-calls-in-hubspot), pour différencier appels terminés et enregistrés des appels entrants avec messages vocaux, incluez les propriétés suivantes dans votre requête : `hs_call_status` et `hs_call_has_voicemail`. Si un appel a un message vocal, la valeur `hs_call_status` sera `missed` et la valeur `hs_call_has_voicemail` 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 : ```json theme={null} //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, consultez la [documentation de référence](https://developers.hubspot.fr/docs/api-reference/crm-calls-v3/guide.md#post-%2Fcrm%2Fv3%2Fobjects%2Fcalls%2Fbatch%2Fupdate). ### 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 requête `PUT` à `/crm/v3/objects/calls/{callId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}`. L'URL de la requête contient les champs suivants : | Champ | Description | | - | - | | `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](https://developers.hubspot.fr/docs/api-reference/crm-associations-v3/guide.md). | 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](https://knowledge.hubspot.com/fr/records/pin-an-activity-on-a-record) 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'`id` 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. Découvrez-en davantage sur l'utilisation des API d'[entreprises](https://developers.hubspot.fr/docs/api-reference/crm-companies-v3/guide.md#pin-an-activity-on-a-company-record)[, de contacts](https://developers.hubspot.fr/docs/api-reference/crm-contacts-v3/guide.md#pin-an-activity-on-a-contact-record), de [transactions](https://developers.hubspot.fr/docs/api-reference/crm-deals-v3/guide.md#pin-an-activity-on-a-deal-record), de [tickets](https://developers.hubspot.fr/docs/api-reference/crm-tickets-v3/guide.md#pin-an-activity-on-a-ticket-record) et d'[objets personnalisés](https://developers.hubspot.fr/docs/api-reference/crm-custom-objects-v3/guide.md). ## 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](https://knowledge.hubspot.com/fr/records/restore-deleted-activity-in-a-record). Pour supprimer un appel individuel par son ID d'appel, effectuez une requête `DELETE` à `/crm/v3/objects/calls/{callId}`. Pour en savoir plus sur la suppression des appels, consultez la [documentation de référence](https://developers.hubspot.fr/docs/api-reference/crm-calls-v3/guide.md#delete-%2Fcrm%2Fv3%2Fobjects%2Fcalls%2F%7Bcallid%7D).