Integração Zenvia → HubSpot

Índice

1. Visão Geral & Comparação de Fluxos
2. Arquitetura da Solução
3. Configuração no Builder Zenvia (Passo a Passo)
4. Endpoint & Configuração
5. JSON Body Completo (34 campos)
6. Mapeamento Variáveis Bot → HubSpot
7. cURL de Teste (Postman-ready)
8. Tratamento de Erros
9. Workflow HubSpot
10. Checklist de Implementação

1. Visão Geral

A integração permite que o bot da Zenvia envie dados de leads capturados via WhatsApp diretamente para o HubSpot CRM da PetLove, sem middleware, sem servidor externo e sem Operations Hub.

Comparação de Fluxos

2. Arquitetura

3. Configuração no Builder Zenvia

Passo a passo para configurar a "Chamada de API" no Construtor do Bot da Zenvia Conversion.

1 Criar bloco "Enviar para HubSpot"

No Construtor do Bot, crie um novo bloco após a coleta de dados do lead. Nomeie-o como EnviarParaHubSpot ou similar.

2 Adicionar conteúdo "Chamada de API"

Clique nos três pontinhos do bloco → Adicionar conteúdo → Chamada de API.

3 Configurar Método e URL

4 Configurar Cabeçalho (Header)

No campo Cabeçalho, adicione:

Content-Type: application/json

Não é necessário nenhum token de autenticação. A Forms API é pública por design.

5 Configurar Corpo (Body)

No campo Corpo, cole o JSON abaixo. Substitua os valores fixos pelas variáveis do bot usando a sintaxe <? $nome_variavel ?>.

Veja a Seção 5 para o JSON completo e a Seção 6 para o mapeamento de variáveis.

6 Tratar a Resposta

A resposta fica disponível em <? $resposta_api.body ?>. No bloco seguinte, você pode:

• Verificar sucesso: se $resposta_api.code == 200, seguir fluxo normal
• Em caso de erro, logar para análise ou reenviar

4. Endpoint & Configuração

5. JSON Body Completo (34 campos)

Copiar e colar no campo Corpo da Chamada de API. Substituir valores fixos por variáveis do bot.

Copiar{
  "fields": [
    // ---- DADOS DO CONTATO (coletados pelo bot) ----
    { "name": "email",       "value": "<? $email_lead ?>" },
    { "name": "firstname",   "value": "<? $primeiro_nome ?>" },
    { "name": "lastname",    "value": "<? $sobrenome ?>" },
    { "name": "phone",       "value": "<? $telefone ?>" },

    // ---- DADOS DO PET ----
    { "name": "pet_name",    "value": "<? $nome_pet ?>" },
    { "name": "pet_species", "value": "<? $especie_pet ?>" },

    // ---- DADOS ZENVIA CORE ----
    { "name": "zenvia_conversation_id",   "value": "<? $conversation_id ?>" },
    { "name": "zenvia_channel",           "value": "whatsapp" },
    { "name": "first_message",            "value": "<? $primeira_mensagem ?>" },
    { "name": "zenvia_event_id",          "value": "<? $event_id ?>" },
    { "name": "zenvia_subscription_id",   "value": "sub_petlove_whatsapp" },
    { "name": "zenvia_event_type",        "value": "MESSAGE" },
    { "name": "zenvia_message_id",        "value": "<? $message_id ?>" },
    { "name": "zenvia_direction",         "value": "IN" },
    { "name": "zenvia_from",              "value": "<? $telefone_lead ?>" },
    { "name": "zenvia_to",                "value": "551140042500" },
    { "name": "zenvia_content_type",      "value": "text" },
    { "name": "zenvia_timestamp",         "value": "<? $timestamp ?>" },
    { "name": "zenvia_message_status",    "value": "delivered" },
    { "name": "zenvia_whatsapp_name",     "value": "<? $whatsapp_name ?>" },
    { "name": "zenvia_bot_flow_id",       "value": "<? $flow_id ?>" },
    { "name": "zenvia_metadata",          "value": "<? $metadata_json ?>" },

    // ---- REFERRAL / CLICK-TO-WHATSAPP ADS ----
    { "name": "zenvia_referral_headline",    "value": "<? $referral_headline ?>" },
    { "name": "zenvia_referral_source_type", "value": "<? $referral_type ?>" },
    { "name": "zenvia_referral_source_url",  "value": "<? $referral_url ?>" },
    { "name": "zenvia_referral_ctwa_id",     "value": "<? $ctwa_id ?>" },
    { "name": "zenvia_contact_id",           "value": "<? $zenvia_contact_id ?>" },
    { "name": "zenvia_flow_response_data",   "value": "<? $flow_response ?>" },

    // ---- STATUS & ERROS ----
    { "name": "zenvia_visitor_picture",      "value": "<? $visitor_picture ?>" },
    { "name": "zenvia_status_description",   "value": "<? $status_desc ?>" },
    { "name": "zenvia_status_error_code",    "value": "<? $error_code ?>" },
    { "name": "zenvia_status_error_reason",  "value": "<? $error_reason ?>" },
    { "name": "zenvia_channel_provider",     "value": "<? $channel_provider ?>" },
    { "name": "zenvia_message_payload",      "value": "<? $msg_payload ?>" }
  ],
  "context": {
    "pageUri": "https://api.zenvia.io/whatsapp",
    "pageName": "Zenvia WhatsApp - PetLove"
  }
}

6. Mapeamento Variáveis Bot → HubSpot

Dados do Contato

Dados do Pet

Dados Zenvia Core (22 campos)

Dados Referral / Click-to-WhatsApp Ads (6 campos novos)

Dados de Status & Enriquecimento (6 campos novos)

7. cURL de Teste

Copiar e colar no Postman (Import → Raw Text) ou executar no terminal para validar.

7.1 — Submissão mínima (teste rápido)

Copiarcurl -X POST \
  "https://api.hsforms.com/submissions/v3/integration/submit/50501903/a5edb59a-d033-4905-84d4-c00cbed2403e" \
  -H "Content-Type: application/json" \
  -d '{
  "fields": [
    { "name": "email", "value": "teste.zenvia@petlove.com" },
    { "name": "firstname", "value": "Teste" },
    { "name": "phone", "value": "+5511999887766" },
    { "name": "zenvia_channel", "value": "whatsapp" },
    { "name": "first_message", "value": "Teste de integracao" }
  ],
  "context": {
    "pageUri": "https://api.zenvia.io/whatsapp",
    "pageName": "Zenvia WhatsApp - PetLove"
  }
}'

7.2 — Resposta esperada

// HTTP 200 OK
{
  "inlineMessage": "Thanks for submitting the form."
}

7.3 — Resposta de erro (campo obrigatório ausente)

// HTTP 400 Bad Request
{
  "status": "error",
  "message": "The request is not valid",
  "errors": [
    { "message": "Required field 'email' is missing" }
  ]
}

8. Tratamento de Erros

9. Workflow HubSpot

Após a submissão via Forms API, o HubSpot dispara automaticamente workflows com trigger "Contact submits a form" filtrado pelo formulário Zenvia.

Ações recomendadas no workflow

10. Checklist de Implementação

Cronograma V1 — Gantt (02/03 → 26/03/2026)

11. Roadmap — Middleware (V2)

Por que um middleware?

A Forms API cria contatos e dispara workflows, mas não permite:

Arquitetura do Middleware (Fluxo A — Análise Técnica v3.2)

O que o middleware faz (passo a passo)

Capacidades técnicas

Prós e Contras

Escopo V2 vs V1

Referência: Análise Técnica — Integração Zenvia × HubSpot v1.0 (baseado no Brief Técnico v3.2), Jonathan Lima, 05/03/2026.

Suporte