Registar mensagens do WhatsApp no HubSpot a partir de um número Coexistence

Como chega uma mensagem de WhatsApp a um contacto do HubSpot?

Em três passos. A Meta entrega a mensagem ao destino do webhook definido para o número, que aqui é um nó Webhook do n8n. O fluxo de trabalho procura no HubSpot um contacto com o número de telefone do remetente e cria um se nada corresponder. Depois cria um registo de comunicação com o texto da mensagem e associa-o a esse contacto.

O HubSpot criou o objeto Communications para este caso. Representa uma mensagem de WhatsApp, LinkedIn ou SMS enviada ou recebida fora do HubSpot e aparece na cronologia do registo, tal como uma chamada ou um email registados. As propriedades obrigatórias são o tipo de canal, hs_communication_logged_from definido como CRM, o corpo, um proprietário e uma data e hora.

Nada disto exige uma app do marketplace do HubSpot. O nó HTTP Request do n8n pode reutilizar a credencial do HubSpot que já configurou para o nó HubSpot, e a chamada é um único POST por mensagem.

{
  "properties": {
    "hs_communication_channel_type": "WHATS_APP",
    "hs_communication_logged_from": "CRM",
    "hs_communication_body": "do you have anything friday?",
    "hubspot_owner_id": "75480934",
    "hs_timestamp": "2026-10-11T14:20:00.000Z"
  }
}

As mensagens escritas no telemóvel também são registadas?

Podem ser, e é isso que um número Coexistence acrescenta. Quando alguém da equipa responde a partir da app WhatsApp Business, a Meta envia um eco dessa mensagem enviada para o mesmo destino do webhook. Um fluxo de trabalho que trate as mensagens recebidas e os ecos escreve os dois lados da conversa na cronologia, de modo que um comercial que abra o contacto no HubSpot vê o que o cliente perguntou e o que a loja respondeu.

Separe pelo campo do webhook. As mensagens recebidas chegam em messages e as respostas do telemóvel chegam em smb_message_echoes. Registe as primeiras como recebidas e as segundas como enviadas, e a cronologia fica por ordem.

As respostas que o próprio fluxo de trabalho envia através da Cloud API já são conhecidas por ele, por isso registe-as no momento do envio, em vez de esperar por um webhook.

E o canal de caixa de entrada do WhatsApp do próprio HubSpot?

É uma integração diferente. A caixa de entrada de conversas do HubSpot liga um número de WhatsApp ao próprio HubSpot, e a sua base de conhecimento indica que o número não pode estar ligado a outra integração de WhatsApp. Está disponível no Marketing Hub ou no Service Hub Professional e Enterprise.

Um número ligado através do EasyCoexistence funciona ao contrário: a Meta encaminha os webhooks para um URL que lhe pertence e o HubSpot recebe os registos através da sua API. A conversa é respondida a partir do telemóvel ou pelo seu fluxo de trabalho, e o HubSpot é o sistema de registo que guarda o histórico associado ao contacto, ao negócio ou ao ticket.

A chamada exige uma permissão de escrita de contactos na app privada ou na credencial que a faz, que é a mesma permissão de que o fluxo de trabalho já precisa para criar o contacto.

Como deve o fluxo de trabalho associar um remetente a um contacto?

Pelo número de telefone, normalizado antes da pesquisa. A Meta envia o remetente como dígitos com o indicativo do país e sem o sinal de mais, por exemplo 14155550188. Os contactos do HubSpot são escritos à mão, pelo que a mesma pessoa pode estar guardada como +1 415 555 0188 ou (415) 555-0188.

O padrão fiável é manter uma propriedade de contacto dedicada com o número só em dígitos, preenchê-la quando o fluxo de trabalho cria um contacto e pesquisar por essa propriedade. Pesquisar diretamente o campo de telefone em texto livre funciona para os contactos criados pelo fluxo de trabalho e falha muitos dos que foram criados por uma pessoa, o que gera duplicados.

Quando uma pesquisa não devolve nada, crie o contacto com o nome de perfil do payload do webhook como primeiro nome e o número só em dígitos nos dois campos. Uma pessoa pode fundir ou renomear mais tarde, e a conversa já fica associada.

Erros comuns

• Registar apenas as mensagens recebidas. A cronologia mostra então perguntas sem respostas, porque as respostas escritas no telemóvel chegam como eventos smb_message_echoes.
• Deixar hs_communication_logged_from por definir. O HubSpot exige que seja CRM ao criar uma comunicação através da API.
• Pesquisar contactos pelo campo de telefone original. O formato só com dígitos da Meta raramente coincide com o que uma pessoa escreveu, e cada falha cria um contacto duplicado.

Perguntas frequentes

Continue a ler