Você pode registrar observações em registros do CRM para adicionar informações à linha do tempo do registro ou associar um anexo a um registro. Por exemplo, se você precisar acompanhar uma conversa offline que teve com um contato, poderá adicionar uma observação ao registro do contato com detalhes e documentos relacionados à conversa. Outros usuários na conta poderão visualizar e referenciar essa observação.
Você pode gerenciar observações no HubSpot ou por meio da API de observações. Abaixo, aprenda os métodos básicos de gerenciamento de observações por meio da API. Você pode revisar todos os pontos de extremidade disponíveis na guia Ponto de extremidade na parte superior deste artigo.
Para criar uma observação, envie uma solicitação POST
para /crm/v3/objects/notes
.
No corpo da solicitação, adicione detalhes da observação em um objeto de propriedades. Você também pode adicionar um objeto de associações para associar sua nova observação a um registro existente (por exemplo, contatos, empresas).
No objeto de propriedades, você pode incluir os seguintes campos:
Campo | Descrição |
---|---|
hs_timestamp | Obrigatório. Este campo marca a hora de criação da observação e determina onde ela se encontra na linha do tempo do registro. Você pode usar um carimbo de data e hora do Unix em milissegundos ou no formato UTC. |
hs_note_body | O conteúdo de texto da observação, limitado a 65.536 caracteres. |
hubspot_owner_id | O ID do proprietário associado à observação. Este campo determina o usuário listado como o criador da observação na linha do tempo do registro. |
hs_attachment_ids | Os IDs dos anexos da observação. Vários IDs de anexo são separados por ponto e vírgula. |
Para criar e associar uma observação a registros existentes, inclua um objeto de associações na solicitação. Por exemplo, para criar uma observação e associá-la a uma empresa e a um negócio, o corpo da solicitação pode ser semelhante ao seguinte:
// Example POST request to https://api.hubspot.com/crm/v3/objects/notes
{
"properties": {
"hs_timestamp": "2021-11-12T15:48:22Z",
"hs_note_body": "Spoke with decision maker Carla. Attached the proposal and draft of contract.",
"hubspot_owner_id": "14240720",
"hs_attachment_ids": "24332474034;24332474044"
},
"associations": [
{
"to": {
"id": 301
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 190
}
]
},
{
"to": {
"id": 401
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 214
}
]
}
]
}
No objeto de associações, você deve incluir o seguinte:
Campo | Descrição |
---|---|
to | O registro que deseja associar à observação, especificado por seu valor de id exclusivo. |
types | O tipo de associação entre a observação e o registro. Inclua associationCategory e associationTypeId . Os IDs de tipo de associação padrão são listados aqui, ou você pode recuperar o valor de tipos de associação personalizados (ou seja, rótulos) por meio da API de associações. |
Saiba mais sobre a criação em massa de empresas na guia* Pontos de extremidade* na parte superior deste artigo.
Você pode recuperar observações individualmente ou em lotes. Para recuperar uma observação individual, faça uma solicitação GET
para /crm/v3/objects/notes/{noteId}
.
Para solicitar uma lista de todas as observações, faça uma solicitação GET
para /crm/v3/objects/notes
.
Para ambos os pontos de extremidade, você pode incluir os seguintes parâmetros de consulta no URL da solicitação:
Descrição | Parâmetro |
---|---|
properties | Uma lista separada por vírgulas das propriedades a serem retornadas em resposta. Se a empresa solicitada não tiver um valor para uma propriedade, ela não será exibida na resposta. |
associations | Uma lista separada por vírgulas de tipos de objeto para recuperar IDs associados. Todas as associações especificadas que não existem não serão retornadas na resposta. Saiba mais sobre a API de associações. |
Por exemplo, para recuperar observações com o conteúdo do texto e qualquer ID de contato associado, o URL da solicitação pode ser semelhante ao seguinte:
https://api.hubapi.com/crm/v3/objects/notes?limit=10&properties=hs_note_body&associations=contact&archived=false
.
Saiba mais sobre como recuperar um lote de observações pelo ID interno ou valor de propriedade exclusivo na guia Pontos de extremidade na parte superior deste artigo.
Você pode atualizar observações individualmente ou em massa. Para atualizar uma observação individual pelo seu ID, faça uma solicitação PATCH
para /crm/v3/objects/notes/{noteId}
.
No corpo da solicitação, inclua as propriedades de observação que deseja atualizar:
xxxxxxxxxx
// Example PATCH request to https://api.hubspot.com/crm/v3/objects/notes/{noteID}
{
"properties": {
"hs_note_body": "Spoke with decision maker Carla.",
"hs_attachment_ids": "24332474034;24332474044"
}
}
O HubSpot ignorará valores para propriedades somente leitura e inexistentes. Para limpar um valor de propriedade, passe uma string vazia para a propriedade no corpo da solicitação.
Saiba mais sobre a atualização em massa de empresas na guia* Pontos de extremidade* na parte superior deste artigo.
Para associar uma observação a outros registros do CRM, como um contato, faça uma solicitação PUT
para /crm/v3/objects/notes/{noteId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
. A URL da solicitação contém os campos a seguir:
Campo | Descrição |
---|---|
noteId | O ID da observação. |
toObjectType | O tipo de objeto ao qual você deseja associar a observação (por exemplo, contato ou empresa) |
toObjectId | O ID do registro ao qual você deseja associar a observação. |
associationTypeId | Um identificador exclusivo para indicar o tipo de associação entre a observação e o outro objeto. O ID pode ser representado numericamente ou em maiúsculas (por exemplo, note_to_contact ). Você pode recuperar o valor por meio da API de associações. |
Por exemplo, a URL da sua solicitação pode ser parecida com o seguinte:
https://api.hubspot.com/crm/v3/objects/notes/17147287858/associations/contact/581751/202
Para remover uma associação entre uma chamada e um registro, faça uma solicitação DELETE
para o mesmo URL acima:
/crm/v3/objects/notes/{noteId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
Você pode fixar uma observação em um registro para que permaneça no topo da linha do tempo do registro. A chamada já deve estar associada ao registro antes da fixação e você só pode fixar uma atividade por registo. Para fixar uma observação, inclua o id
da observação no campo hs_pinned_engagement_id
ao criar ou atualizar um registro por meio das APIs de objeto. Saiba mais sobre como usar as APIs de empresas,contatos, negócios, tickets e objetos personalizados.
Você pode excluir observações individualmente ou em massa, o que adicionará a observação à lixeira no HubSpot. Você pode restaurar posteriormente a observação da linha do tempo do registro.
Para excluir uma observação individual pelo seu ID, faça uma solicitação DELETE
para /crm/v3/objects/notes/{noteId}
.
Saiba mais sobre a exclusão em massa de observações na guia* Pontos de extremidade* na parte superior deste artigo.