Implementação

Esquema POST

A solicitação POST enviada para o webhook será no formato JSON com o seguinte esquema:

Payload Proto do webhook

// Represent user lead data for single column
message UserLeadColumnData {
  // Human-readable text of the field type (e.g.: Full Name,  What is your
  // preferred dealership?). This field might not always be populated.
  optional string column_name = 1;

  // Column value based on column type
  oneof column_value {
    string string_value = 2;
  }
  // Column id. Populated for all types of fields. (e.g.: FULL_NAME)
  optional string column_id = 3;
}

// Message to construct webhook JSON payload
message WebhookLead {
  // Unique id to represent lead
  optional string lead_id = 1;
  // User inputted data per column
  repeated UserLeadColumnData user_column_data = 2;
  // API version
  optional string api_version = 3;
  // Form id to which lead belonged to.
  optional int64 form_id = 4;
  // Campaign id that the lead form is associated with
  optional int64 campaign_id = 5;
  // Key to be used by advertiser to verify the request
  // is from Google.
  optional string google_key = 6;
  // Denotes if the lead is a test lead.
  optional bool is_test = 7;
  // Click ID for the lead submission.
  optional string gcl_id = 8;
  // Adgroup id which generated the lead.
  optional int64 adgroup_id = 9;
  // Creative id which generated the lead.
  optional int64 creative_id = 10;
  // Asset group id represents the container for holding assets, associated
  // urls, hints and criteria that will be used to select assets and for
  // optimization. This field is only populated for Performance Max campaigns.
  int64 asset_group_id = 11;
}

Descrição do campo

Campo Descrição
lead_id String exclusiva que identifica um lead.

Como lidar com recomendações:use essa opção para eliminar as duplicações de leads que são recebidos. Ele será exclusivo em todos os formulários. Ao informar problemas relacionados a um lead específico, esse ID será necessário.

api_version Versão da API à qual este esquema de lead pertence. Ele será usado ao migrar para um novo esquema e pode ser ignorado por enquanto.
form_id ID exclusivo para cada formulário configurado no Google Ads. O produto atual permite anexar um formulário com um nível de campanha (em vez de anexar no nível do grupo de anúncios ou do anúncio).

Implicações:os leads só podem ser divididos no nível form_id, ou seja, na campanha.

Os clientes precisam usar um número inteiro de 8 bytes para processar.

campaign_id O ID da campanha do Google Ads ou do item de linha (Display & Video 360) do formulário de lead anexado.

Os clientes precisam usar um número inteiro de 8 bytes para processar.

adgroup_id O ID do grupo de anúncios do Google Ads é usado para distinguir o grupo de anúncios específico na campanha. (Disponível apenas para leads de anúncios Discovery e em vídeo)

Os clientes precisam usar um número inteiro de 8 bytes para processar.

creative_id O ID do criativo do Google Ads é usado para distinguir o criativo específico no grupo de anúncios. (Disponível apenas para leads de anúncios Discovery e em vídeo)

Os clientes precisam usar um número inteiro de 8 bytes para processar.

gcl_id ID de clique do Google, um parâmetro exclusivo usado para acompanhar cada clique em um anúncio.
google_key Uma chave configurada pelo anunciante com cada formulário.

Recomendação de processamento:antes de processar um lead recebido por webhook, validar google_key é o mesmo que configurar no Google Ads para ter mais confiança de que o lead é válido. Mantenha essa chave confidencial e atualize no Google Ads se houver motivos para acreditar que ela vazou para muitas pessoas.

is_test Este campo tem semântica "opcional". Se o valor for verdadeiro, trate esse lead como um lead de teste. Se o valor for falso ou se o campo não estiver presente, trate esse lead como um lead de produção válido.
user_column_data Uma tupla de chave-valor repetida que transmite dados enviados pelo usuário.
  • user_column_data.column_id: tipo de dados enviado pelo usuário.
  • User_column_data.column_value: para cada tipo de dados, um tipo de valor será preenchido dependendo do tipo de dados. Todos os nossos tipos de dados atuais têm o valor de user_column_data.string_value.
  • user_column_data.column_name: texto legível por humanos do tipo de dados enviado pelo usuário. Esse campo nem sempre é preenchido. Use column_id .
user_column_data.column_id User_column_data.string_value content user_column_data.column_name (descontinuado)
"FULL_NAME" Nome completo do usuário. "Nome completo"
"FIRST_NAME" Nome do usuário, "Nome"
"LAST_NAME" Sobrenome do usuário, "Sobrenome"
"EMAIL" E-mail do usuário "E-mail do usuário"
"PHONE_NUMBER" Número de telefone do usuário no formato E.164, por exemplo, "+11234567890". "User Phone"
"POSTAL_CODE" Código postal do usuário. "CEP"
"COMPANY_NAME" Nome da empresa do usuário. "Nome da empresa"
"JOB_TITLE" Cargo do usuário. "Cargo"
"WORK_EMAIL" E-mail de trabalho do usuário. "E-mail de trabalho"
"WORK_PHONE" Telefone de trabalho do usuário. "Telefone de trabalho"
"STREET_ADDRESS" Endereço do usuário. "Endereço de rua"
"CIDADE" Cidade do usuário. "Cidade"
"REGION" Região do usuário. "Região"
"COUNTRY" País do usuário. "País"
"VEHICLE_MODEL" Em qual modelo você tem interesse? N/A
"VEHICLE_TYPE" Em que tipo de veículo você tem interesse? N/A
"PREFERRED_DEALERSHIP" Selecione sua concessionária preferida N/A
"VEHICLE_PURCHASE_TIMELINE" Quando você planeja comprar um veículo? N/A
"VEHICLE_CONDITION" Qual é o estado do veículo que você procura? N/A
"VEHICLE_OWNERSHIP" Você tem carro? "N/A"
"VEHICLE_PAYMENT_TYPE" Em qual opção de propriedade de veículo você tem interesse? N/A
"COMPANY_SIZE" Qual é o porte da sua empresa? N/A
"ANNUAL_SALES" Qual é seu volume de vendas anual? N/A
"YEARS_IN_BUSINESS" Há quantos anos sua empresa atua na área? N/A
"JOB_DEPARTMENT" Em qual departamento seu cargo se encaixa? N/A
"JOB_ROLE" Qual é seu cargo? N/A
"EDUCATION_PROGRAM" Em qual programa você tem interesse? N/A
"EDUCATION_COURSE" Em qual curso você tem interesse? N/A
"PRODUTO" Em qual produto você tem interesse? N/A
"SERVICE" Em qual serviço você tem interesse? N/A
"OFFER" Em qual oferta você tem interesse? N/A
"CATEGORY" Em qual categoria você tem interesse? N/A
"PREFERRED_CONTACT_METHOD" Selecione uma forma de contato N/A
"PREFERRED_LOCATION" Selecione um local N/A
"PREFERRED_CONTACT_TIME" Qual é o melhor horário para entrar em contato com você? N/A
"PURCHASE_TIMELINE" Quando você tem intenção de fazer uma compra? N/A
"YEARS_OF_EXPERIENCE" Quantos anos de experiência você tem? N/A
"JOB_INDUSTRY" Você trabalha em qual setor? N/A
"LEVEL_OF_EDUCATION" Qual é seu nível de escolaridade? N/A
"PROPERTY_TYPE" Que tipo de imóvel você está procurando? N/A
"REALTOR_HELP_GOAL" Para que você precisa da ajuda de um corretor? N/A
"PROPERTY_COMMUNITY" Em qual comunidade você tem interesse? N/A
"PRICE_RANGE" Qual faixa de preço você está procurando? N/A
"NUMBER_OF_BEDROOMS" Quantos quartos você gostaria de ter? N/A
"FURNISHED_PROPERTY" Você está procurando um imóvel mobiliado? N/A
"PETS_ALLOWED_PROPERTY" Você está procurando imóveis que permitem animais de estimação? N/A
"NEXT_PLANNED_PURCHASE" Qual é o próximo produto que você planeja comprar? N/A
"EVENT_SIGNUP_INTEREST" Você gostaria de se inscrever em um evento? N/A
"PREFERRED_SHOPPING_PLACES" Onde você gosta de fazer compras? N/A
"FAVORITE_BRAND" Qual é sua marca preferida? N/A
"TRANSPORTATION_COMMERCIAL_LICENSE_TYPE" Que tipo de licença comercial válida você tem? N/A
"EVENT_BOOKING_INTEREST" Você tem interesse em agendar um evento? N/A
"DESTINATION_COUNTRY" Qual é seu país de destino? N/A
"DESTINATION_CITY" Qual é sua cidade de destino? N/A
"DEPARTURE_COUNTRY" Qual é seu país de partida? N/A
"DEPARTURE_CITY" Qual é sua cidade de partida? N/A
"DEPARTURE_DATE" Qual é sua data de partida? N/A
"RETURN_DATE" Qual é sua data de retorno? N/A
"NUMBER_OF_TRAVELERS" Com quantas pessoas você está viajando? N/A
"TRAVEL_BUDGET" Qual é o orçamento da sua viagem? N/A
"TRAVEL_ACCOMMODATION" Onde você gostaria de ficar durante sua viagem? N/A
asset_group_id Esse campo só é preenchido para campanhas Performance Max. Indica o ID do contêiner que contém o formulário de lead.

Os clientes precisam usar um número inteiro de 8 bytes para processar.

Gestão de leads

Os gerenciadores de leads precisam responder com os seguintes códigos HTTP:

Resposta HTTP Corpo da resposta (JSON) Erro que pode ser repetido?
200 {} N/A
4XX {"message: Free form error text, describing what was wrong with request"} Não
5XX {"message: Intermittent retraible error optional message"} Sim

Cópias

Não há garantia de que um único lead será entregue exatamente uma vez. Portanto, o webhook responsável pelo lead precisa processar duplicatas corretamente.