Implementación

Esquema POST

La solicitud POST enviada al webhook estará en formato JSON con el siguiente esquema:

Carga útil de Webhook Proto

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

Descripción del campo

Campo Descripción
lead_id String única que identifica un cliente potencial determinado.

Recomendación de manejo: Úsala para anular la duplicación de los clientes potenciales que se reciben. Este será único en todos los formularios. Cuando informes problemas relacionados con un cliente potencial específico, este ID será obligatorio.

api_version Es la versión de la API a la que pertenece este esquema de cliente potencial. Se usará cuando se migre a un esquema nuevo y se puede ignorar por ahora.
form_id Es el ID único para cada formulario configurado en Google Ads. Con el producto actual, puedes adjuntar un formulario a nivel de la campaña (en lugar de adjuntarlo a nivel del grupo de anuncios o del anuncio).

Implicaciones: Los clientes potenciales se pueden segmentar solo a nivel del form_id (es decir, a nivel de la campaña).

Los clientes deben usar un número entero de 8 bytes para el procesamiento.

campaign_id El ID de la campaña de Google Ads o el ID de la línea de pedido (Display & Video 360) del formulario de clientes potenciales adjunto.

Los clientes deben usar un número entero de 8 bytes para procesar.

adgroup_id El ID del grupo de anuncios de Google Ads se utiliza para distinguir el grupo de anuncios específico de la campaña. (Disponible solo para clientes potenciales de anuncios discovery y de video)

Los clientes deben usar un número entero de 8 bytes para procesar.

creative_id El ID de creatividad de Google Ads se usa para distinguir la creatividad específica en el grupo de anuncios. (Disponible solo para clientes potenciales de anuncios discovery y de video)

Los clientes deben usar un número entero de 8 bytes para procesar.

gcl_id El ID de clic de Google es un parámetro único que se usa para hacer un seguimiento de cada clic en un anuncio.
google_key Es una clave que configura el anunciante con cada formulario.

Recomendación de manejo: Antes de procesar un cliente potencial recibido por webhook, validar google_key equivale a realizar la configuración en Google Ads para tener más confianza en que el cliente potencial sea válido. Mantén esta clave en confidencialidad y actualízala en Google Ads si hay motivos para creer que se filtró ampliamente.

is_test Este campo tiene una semántica “opcional”. Si el valor es verdadero, trata a este cliente potencial como cliente potencial de prueba. Si el valor es falso o si el campo no está presente, trata a este cliente potencial como un cliente potencial de producción válido.
user_column_data Una tupla clave-valor repetida que transmite datos enviados por el usuario.
  • user_column_data.column_id: Es el tipo de datos que envía el usuario.
  • User_column_data.column_value: Para cada tipo de datos, se propagará un tipo de valor según el tipo de datos. Todos nuestros tipos de datos actuales tienen el valor de user_column_data.string_value.
  • user_column_data.column_name: Es el texto legible del tipo de datos que envía el usuario. Es posible que este campo no siempre se propague; usa column_id en su lugar.
user_column_data.column_id Contenido de User_column_data.string_value user_column_data.column_name (obsoleto)
“FULL_NAME” Nombre completo del usuario. “Nombre completo”:
“FIRST_NAME” Es el nombre del usuario. "Nombre"
“LAST_NAME” Es el apellido del usuario. "Apellido"
"EMAIL" Es el correo electrónico del usuario. "Correo electrónico del usuario"
“PHONE_NUMBER” Teléfono del usuario en formato E.164, p.ej., "+11234567890". "Teléfono del usuario"
“POSTAL_CODE” Código postal del usuario. "Código postal"
“COMPANY_NAME” Nombre de la empresa del usuario "Nombre de la empresa"
"JOB_TITLE" Cargo del usuario. "Cargo"
“WORK_EMAIL” Correo electrónico laboral del usuario "Correo electrónico laboral"
"WORK_PHONE" Teléfono laboral del usuario "Teléfono del trabajo"
“STREET_ADDRESS” Dirección del usuario "Dirección"
“CIUDAD” Ciudad del usuario "Ciudad"
“REGIÓN” Región del usuario. “Región”
“PAÍS” País del usuario "País"
“VEHICLE_MODEL” ¿Qué modelo te interesa? No disponible
“VEHICLE_TYPE” ¿Qué tipo de vehículo te interesa? No disponible
“PREFERRED_DEALERSHIP” Seleccione su concesionario preferido No disponible
“VEHICLE_PURCHASE_TIMELINE” ¿Cuándo planeas comprar un vehículo? No disponible
“VEHICLE_Condition” ¿Te interesa un vehículo nuevo o usado? No disponible
PROPIETARIO DE VEHICLE ¿Tienes un vehículo? “N/A”
"VEHICLE_PAYMENT_TYPE" ¿Qué opción de propiedad del vehículo te interesa? No disponible
“COMPANY_SIZE” ¿De qué tamaño es tu empresa? No disponible
“ANNUAL_SALES” ¿Cuál es tu volumen anual de ventas? No disponible
"AÑOS_IN_BUSINESS" ¿Cuántos años llevas en el negocio? No disponible
“JOB_DEPARTMENT” ¿En qué departamento trabajas? No disponible
"JOB_ROLE" ¿Cuál es tu puesto de trabajo? No disponible
“EDUCATION_PROGRAM” ¿Qué programa te interesa? No disponible
“EDUCATION_CURSE” ¿Qué curso te interesa? No disponible
“PRODUCT” ¿Qué producto te interesa? No disponible
"SERVICIO" ¿Qué servicio te interesa? No disponible
"OFERTA" ¿Qué oferta te interesa? No disponible
"CATEGORÍA" ¿Qué categoría te interesa? No disponible
“PREFERRED_CONTACT_METHOD” Seleccione su forma de contacto preferida No disponible
"PREFERRED_LOCATION" Seleccione su ubicación preferida No disponible
“PREFERRED_CONTACT_TIME” ¿Cuál es el mejor horario para contactarte? No disponible
“PURCHASE_TIMELINE” ¿Cuándo pretendes realizar una compra? No disponible
"AÑOS_OF_EXPERIENCE" ¿Cuántos años de experiencia laboral tienes? No disponible
“JOB_INDUSTRY” ¿En qué sector trabajas? No disponible
"LEVEL_OF_EDUCATION" ¿Qué nivel de estudios alcanzaste? No disponible
“PROPERTY_TYPE” ¿Qué tipo de propiedad buscas? No disponible
"REALTOR_HELP_GOAL" ¿Para qué necesitas la ayuda de un agente inmobiliario? No disponible
“PROPERTY_COMMUNITY” ¿Qué comunidad le interesa? No disponible
"PRICE_RANGE" ¿Qué intervalo de precios buscas? No disponible
"NUMBER_OF_BEDROOMS" ¿Cuántas habitaciones buscas? No disponible
“FURNISHED_PROPERTY” ¿Buscas una propiedad completamente amoblada? No disponible
"PETS_ALLOWED_PROPERTY" ¿Buscas propiedades donde se permitan mascotas? No disponible
"NEXT_PLANNED_PURCHASE" ¿Cuál es el próximo producto que planeas comprar? No disponible
“EVENT_SIGNUP_INTEREST” ¿Te gustaría registrarte en un evento? No disponible
SHOPPING_PLACES PREFERRED ¿Dónde te interesa realizar compras? No disponible
“FAVORITE_BRAND” ¿Cuál es tu marca favorita? No disponible
"TRANSPORTATION_COMMERCIAL_LICENSE_TYPE" ¿Qué tipo de licencia comercial válida tienes? No disponible
“EVENT_BOOKING_INTEREST” ¿Te interesa reservar un evento? No disponible
"DESTINATION_COUNTRY" ¿Cuál es tu país de destino? No disponible
“DESTINATION_CITY” ¿Cuál es tu ciudad de destino? No disponible
"Sale_COUNTRY" ¿Cuál es tu país de origen? No disponible
“Sale_CITY” ¿Cuál es tu ciudad de origen? No disponible
"Sale_DATE" ¿Cuál es tu fecha de salida? No disponible
“RETURN_DATE” ¿Cuál es tu fecha de regreso? No disponible
“NUMBER_OF_TRAVELERS” ¿Con cuántas personas viajarás? No disponible
TRAVEL_PRESUPUESTO ¿Qué presupuesto de viaje tienes? No disponible
“TRAVEL_ACCOMMODATION” ¿Dónde deseas alojarte durante tu viaje? No disponible

Manejo de clientes potenciales

Los controladores de clientes potenciales deben responder con los siguientes códigos HTTP:

Respuesta HTTP Cuerpo de la respuesta (JSON) ¿Es un error recuperable?
200 {} No disponible
4XX {"mensaje: Texto de error de formato libre que describe lo que estaba mal con la solicitud"} No
5XX {"message: Mensaje opcional de error retraible intermitente"}

Duplicados

No se garantiza que un solo cliente potencial se entregue exactamente una vez, por lo que el webhook de control de clientes potenciales debe manejar los duplicados con facilidad.