Interacciones | Llamadas

Run in Postman

Requisitos de ámbito

Utiliza la API de interacciones de llamadas para registrar y gestionar llamadas en los registros del CRM y en la página de índice de llamadas. Puedes registrar llamadas en HubSpot o a través de la API de llamadas. En este artículo encontrarás los métodos básicos para la gestión de llamadas a través de la API. Para ver todos los endpoints disponibles y sus requisitos, consulta la documentación de referencia.

Crear una interacción de llamada

Para crear una interacción de llamada, haz una solicitud POST a /crm/v3/objects/calls. En el cuerpo de la solicitud, agrega detalles de la llamada en el objeto propiedades. También puedes agregar el objeto asociaciones para asociar la llamada con un registro existente (por ejemplo, contactos o empresas).

Propiedades

A continuación, encontrarás una lista de las propiedades de llamada predeterminadas de HubSpot que puedes incluir en el objeto de propiedades. También puedes crear propiedades personalizadas utilizando la API de propiedades.

Campo	Descripción
`hs_timestamp`	Requerido. Este campo marca la hora de creación de la llamada y determina dónde se encuentra en la cronología del registro. Puedes usar una marca de tiempo Unix en milisegundos o en formato UTC.
`hs_call_body`	La descripción de la llamada, incluidas las notas que deseas agregar.
`hs_call_callee_object_id`	El ID del registro de HubSpot asociado con la llamada. Este será el destinatario de la llamada para llamadas `OUTBOUND`, o quien inicia la llamada para llamadas `INBOUND`.
`hs_call_callee_object_type`	El tipo del objeto al que pertenece el registro asociado de la llamada (por ejemplo, especifica si el registro es un contacto o una empresa). Este será el objeto del destinatario para las llamadas `OUTBOUND`, o el objeto de quien inicia las llamadas para las llamadas `INBOUND`.
`hs_call_direction`	La dirección de la llamada desde la perspectiva del usuario de HubSpot. Si el usuario es el destinatario de la llamada, la dirección debe establecerse como `INBOUND`. Si el usuario inició la llamada, la dirección debe establecerse como `OUTBOUND`.
`hs_call_disposition`	El resultado de la llamada. Para establecer la disposición de llamada, debes usar el valor interno de GUID. Si tu cuenta configuró resultados personalizados para las llamadas, puedes encontrar los GUID de la disposición usando esta API. Las etiquetas de resultados predeterminadas de HubSpot y sus valores internos son: Ocupado: `9d9162e7-6cf3-4944-bf63-4dff82258764` Conectado: `f240bbac-87c9-4f6e-bf70-924b57d47db7` Dejó mensaje en directo: `a4c4c377-d246-4b32-a13b-75a56a4cd0ff` Dejó mensaje de voz: `b2cf5968-551e-4856-9783-52b3da59a7d0` No hay respuesta: `73a0d17f-1163-4015-bdd5-ec830791da20` Número equivocado: `17b47fee-58de-441e-a44c-c6300d46f273`
`hs_call_duration`	La duración de la llamada en milisegundos.
`hs_call_from_number`	El número de teléfono desde el que se hizo la llamada.
`hs_call_recording_url`	La URL que almacena la grabación de la llamada. Las URL a archivos .mp3 o .wav se pueden reproducir en registros del CRM. Solo se aceptarán HTTPS o URL seguras.
`hs_call_status`	El estado de la llamada. Los estados son `BUSY`, `CALLING_CRM_USER`, `CANCELED`, `COMPLETED`, `CONNECTING`, `FAILED`, `IN_PROGRESS`, `NO_ANSWER`, `QUEUED` y `RINGING`.
`hs_call_title`	El título de la llamada.
`hs_call_source`	El origen de la llamada. Esto no es obligatorio, pero es necesario para aprovechar el pipeline de grabación y transcripciones. Si la propiedad está configurada, debe establecerse como `INTEGRATIONS_PLATFORM`.
`hs_call_to_number`	El número de teléfono que recibió la llamada.
`hubspot_owner_id`	El ID del propietario asociado con la llamada. Este campo determina el usuario que aparece como creador de la llamada en la cronología del registro.
`hs_activity_type`	El tipo de llamada. Las opciones se basan en los tipos de llamadas definidos en tu cuenta de HubSpot.
`hs_attachment_ids`	Los ID de los archivos adjuntos de la llamada. Los ID de varios archivos adjuntos están separados por un punto y coma.

Asociaciones

Para crear y asociar una llamada con registros existentes, incluye el objeto asociaciones en la solicitud. Por ejemplo, para crear una llamada y asociarla con un contacto y un ticket, el cuerpo de la solicitud podría verse así:

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

En el objeto asociaciones, debes incluir lo siguiente:

Campo	Descripción
`to`	El registro que deseas asociar con la llamada, especificado por su valor `id` único.
`types`	El tipo de asociación entre la llamada y el registro. Incluye `associationCategory` y `associationTypeId`. Los ID de los tipos de asociación predeterminados se enumeran en esta página, o puedes obtener el valor de los tipos de asociación personalizados (es decir, etiquetas) a través de la API de asociaciones.

Para saber más sobre la creación de llamadas por lotes, consulta la documentación de referencia.

Obtener llamadas

Puedes buscar llamadas individualmente o en bloque. Obtén más información sobre la obtención de lotes consultando la documentación de referencia. Para buscar una sola llamada por su ID de llamada, haz una solicitud GET a /crm/v3/objects/calls/{callId}. Puedes incluir los siguientes parámetros en la URL de la solicitud:

Parámetro	Descripción
`properties`	Una lista separada por comas de las propiedades que se devolverán.
`associations`	Una lista separada por comas de los tipos de objetos para obtener los ID asociados. En la respuesta no aparecerán las asociaciones que no existen. Más información sobre la API de asociaciones.

Para solicitar una lista de todas las llamadas, haz una solicitud GET a /crm/v3/objects/calls. Puedes incluir los siguientes parámetros en la URL de la solicitud:

Parámetro	Descripción
`limit`	El número máximo de resultados que se mostrarán por página.
`properties`	Una lista separada por comas de las propiedades que se devolverán.

Cuando realices una solicitud exitosa, la respuesta incluirá el callId que puedes usar para obtener, actualizar y eliminar la llamada.

Identificación de los mensajes de voz frente a las llamadas grabadas

Para llamadas y mensajes de voz grabados, se almacena la grabación en la propiedad hs_call_recording_url. Si tu cuenta tiene acceso a las llamadas entrantes, para diferenciar entre las llamadas que se completaron y grabaron frente a las llamadas entrantes con un mensaje de voz, incluye las siguientes propiedades en tu solicitud: hs_call_status y hs_call_has_voicemail. Si una llamada tiene un mensaje de voz, el valor hs_call_status será missed, y el valor hs_call_has_voicemail será true. El valor hs_call_has_voicemail será false para una llamada entrante en la que no se dejó ningún mensaje de voz o null si la llamada tiene un estado distinto a perdida.

Actualizar llamadas

Puedes actualizar las llamadas individualmente o en lotes. Para actualizar una sola llamada por su ID de llamada, haz una solicitud PATCH a /crm/v3/objects/calls/{callId}. En el cuerpo de la solicitud, incluye las propiedades de llamada que deseas actualizar:

//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 ignorará los valores de las propiedades de solo lectura e inexistentes. Para borrar el valor de una propiedad, pasa una cadena vacía para esa propiedad en el cuerpo de la solicitud. Obtén más información sobre la actualización por lotes consultando la documentación de referencia.

Asociar llamadas existentes con registros

Para asociar una llamada con registros, como un contacto y sus empresas asociadas, haz una solicitud PUT a /crm/v3/objects/calls/{callId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}. La URL de la solicitud contiene los siguientes campos:

Campo	Descripción
`callId`	El ID de la llamada.
`toObjectType`	El tipo de objeto con el que deseas asociar la llamada (por ejemplo, contacto o empresa)
`toObjectId`	El ID del registro con el que deseas asociar la llamada.
`associationTypeId`	Un identificador único para indicar el tipo de asociación entre la llamada y el otro objeto. El ID se puede representar numéricamente o con palabras separadas por guion bajo (por ejemplo, `call_to_contact`). Puedes obtener el valor a través de la API de asociaciones.

Por ejemplo, la URL de tu solicitud puede tener un aspecto similar al siguiente: https://api.hubspot.com/crm/v3/objects/calls/17591596434/associations/contact/104901/194

Eliminar una asociación

Para eliminar una asociación entre una llamada y un registro, realiza una solicitud DELETE en la misma URL que la anterior: /crm/v3/objects/calls/{callId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}

Anclar una llamada en un registro

Puedes anclar una llamada en un registro para que permanezca en la parte superior de la cronología de actividades del registro. La llamada debe estar asociada al registro antes de poder anclarla y solo se puede anclar una actividad por registro. Para anclar una llamada, incluye el id de las llamadas en el campo hs_pinned_engagement_id al crear o actualizar un registro a través de las API de objetos. Obtén más información sobre el uso de las API de empresas ,contactos, negocios, tickets y objetos personalizados.

Eliminar llamadas

Puedes eliminar llamadas individualmente o por lotes, lo que agregará la llamada a la papelera de reciclaje en HubSpot. Más tarde podrás restaurar la llamada desde la cronología de actividades del registro. Para eliminar una sola llamada por su ID, haz una solicitud DELETE a /crm/v3/objects/calls/{callId}. Para saber más sobre cómo eliminar llamadas, consulta la documentación de referencia.

Cuenta y configuración

Gestión de aplicaciones

Autenticación

Automatización

CMS

Preferencias de comunicación

Conversaciones

CRM

Eventos

Archivos

Marketing

Programador

Webhooks

Interacciones | Llamadas

Run in Postman

Crear una interacción de llamada

Propiedades

Asociaciones

Obtener llamadas

Identificación de los mensajes de voz frente a las llamadas grabadas

Actualizar llamadas

Asociar llamadas existentes con registros

Eliminar una asociación

Anclar una llamada en un registro

Eliminar llamadas

Run in Postman

​Crear una interacción de llamada

​Propiedades

​Asociaciones

​Obtener llamadas

​Identificación de los mensajes de voz frente a las llamadas grabadas

​Actualizar llamadas

​Asociar llamadas existentes con registros

​Eliminar una asociación

​Anclar una llamada en un registro

​Eliminar llamadas

Crear una interacción de llamada

Propiedades

Asociaciones

Obtener llamadas

Identificación de los mensajes de voz frente a las llamadas grabadas

Actualizar llamadas

Asociar llamadas existentes con registros

Eliminar una asociación

Anclar una llamada en un registro

Eliminar llamadas