Llamadas

Utiliza la API de interacciones de llamadas para registrar y gestionar llamadas en 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. A continuación, aprenderás los métodos básicos de gestión de llamadas a través de la API. Para ver todos los puntos de terminación disponibles y sus requisitos, haz clic en la pestaña Puntos de terminación en la parte superior de este artículo.

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 tu nueva llamada con un registro existente (por ejemplo, contactos, empresas).

Propiedades

A continuación se muestra 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

Use this table to describe parameters / fields
CampoDescription
hs_timestamp

Requerido. Este campo marca la hora de creación de la llamada y determina dónde se encuentra la llamada 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 el marcador de la llamada para llamadas INBOUND.

hs_call_callee_object_type_id

El ID 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 del marcador 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 en INBOUND. Si el usuario inició la llamada, la dirección debe establecerse en 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 de llamadas personalizadas, puedes encontrar sus GUID de 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
  • Se dejó mensaje en directo: a4c4c377-d246-4b32-a13b-75a56a4cd0ff
  • Se dejó correo de voz: b2cf5968-551e-4856-9783-52b3da59a7d0
  • Sin respuesta: 73a0d17f-1163-4015-bdd5-ec830791da20
  • Número incorrecto: 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, 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

La fuente 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 en 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 establecidos 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 tu solicitud. El objeto debe incluir los siguientes campos:

Use this table to describe parameters / fields
CampoDescription
toObjectId

El ID del registro con el que deseas asociar la llamada.

associationType

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 recuperar el valor a través de la API de asociaciones.

Por ejemplo, para crear una llamada y asociarla con un contacto y un ticket, el cuerpo de tu solicitud podría tener un aspecto similar al siguiente:

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

Obtén más información sobre cómo crear llamadas por lotes haciendo clic en la pestaña Puntos de terminación en la parte superior de este artículo.

Recuperar llamadas

Puedes recuperar llamadas individualmente o en masa. Obtén más información sobre la recuperación por lotes haciendo clic en la pestaña Puntos de terminación en la parte superior de este artículo.

Para recuperar una llamada individual 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: 

Use this table to describe parameters / fields
ParameterDescription
propiedades

Una lista separada por comas de las propiedades que se devolverán. 

asociaciones

Una lista separada por comas de los tipos de objetos para recuperar los ID asociados. No se devolverán en la respuesta las asociaciones especificadas que no existan. 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: 

Use this table to describe parameters / fields
ParameterDescription
límite

El número máximo de resultados que se mostrarán por página.

propiedades

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 recuperar, actualizar y eliminar la llamada. 

Identify voicemails vs. recorded calls

Para llamadas y mensajes de voz grabados, se almacena una grabación en la propiedad hs_call_recording_url. Si tu cuenta tiene acceso a 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 missed.

Actualizar llamadas

Puedes actualizar las llamadas individualmente o por lotes. Para actualizar una llamada individual por su ID de llamada, realiza 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 un valor de propiedad, pasa una cadena vacía para la propiedad en el cuerpo de la solicitud.

Obtén más información sobre la actualización por lotes haciendo clic en la pestaña Puntos de terminación en la parte superior de este artículo.

Asociar llamadas existentes con registros

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

Use this table to describe parameters / fields
CampoDescription
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 recuperar 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 línea de tiempo del registro. La llamada ya debe estar asociada con el registro antes de anclarla, y solo debes anclar una actividad por registro. Para anclar una llamada, incluye el id de la llamada 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 del registro.

Para eliminar una llamada individual por su ID de llamada, realiza una solicitud DELETE en /crm/v3/objects/calls/{callId}.

Obtén más información sobre la eliminación por lotes haciendo clic en la pestaña Puntos de terminación en la parte superior de este artículo.


¿Te resultó útil este artículo?
Con este formulario puedes enviar tu opinión sobre nuestros documentos para desarrolladores. Si tienes comentarios sobre el producto de HubSpot, puedes enviarlos al Foro de ideas.