Implementación

Esquema de POST

La solicitud POST que se envía al webhook estará en formato JSON con el siguiente esquema:

Carga útil de Proto de 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;
}

Descripción del campo

Campo Descripción
lead_id Es una cadena única que identifica a un cliente potencial determinado.

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

api_version Es la versión de la API a la que pertenece este esquema de clientes potenciales. Se usará cuando se migre a un esquema nuevo y se puede ignorar por el momento.
form_id Es el ID único de cada formulario configurado en Google Ads. El producto actual permite adjuntar un formulario a nivel de la campaña (en lugar de hacerlo a nivel del grupo de anuncios o del anuncio).

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

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

campaign_id El ID de la campaña o el ID de 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 usa para distinguir el grupo de anuncios específico en la campaña. (Disponible solo para los clientes potenciales de los anuncios de video y discovery)

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

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

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

gcl_id ID de clic de Google, 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 control: Antes de procesar un cliente potencial recibido a través delwebhook, validar google_key es lo mismo que configurarlo en Google Ads para tener más confianza en que el cliente potencial es válido. Mantén esta clave confidencial y actualízala en Google Ads si tienes motivos para creer que se filtró.

is_test Este campo tiene semántica "opcional". Si el valor es verdadero, trata este cliente potencial como cliente potencial de prueba. Si el valor es falso o si el campo no está presente, considera a este cliente potencial como un cliente potencial de producción válido.
user_column_data Es una tupla clave-valor repetida que transmite datos enviados por el usuario.
  • user_column_data.column_id: Es el tipo de datos que envió 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 por humanos del tipo de datos que envió 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" Es el 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. "User Email"
"PHONE_NUMBER" Número de teléfono del usuario en formato E.164, p.ej., "+11234567890". "Teléfono del usuario"
"POSTAL_CODE" Es el código postal del usuario. "Código postal"
"COMPANY_NAME" Es el nombre de la empresa del usuario. "Nombre de la empresa"
"JOB_TITLE" Es el cargo del usuario. "Título del cargo"
"WORK_EMAIL" Es el correo electrónico laboral del usuario. "Correo electrónico de trabajo"
"WORK_PHONE" Es el teléfono de trabajo del usuario. "Teléfono de trabajo"
"STREET_ADDRESS" Es la dirección del usuario. "Dirección"
"CITY" Es la ciudad del usuario. "Ciudad"
"REGION" Región del usuario. "Región"
"COUNTRY" Es el país del usuario. "País"
"VEHICLE_MODEL" ¿Qué modelo le interesa? N/A
"VEHICLE_TYPE" ¿Qué tipo de vehículo le interesa? N/A
"PREFERRED_DEALERSHIP" Seleccione su concesionario preferido N/A
"VEHICLE_PURCHASE_TIMELINE" ¿Cuándo planea comprar un vehículo? N/A
"VEHICLE_CONDITION" ¿Le interesa un vehículo nuevo o usado? N/A
"VEHICLE_OWNERSHIP" ¿Tiene un vehículo? “N/A”
"VEHICLE_PAYMENT_TYPE" ¿Qué opción de propiedad del vehículo le interesa? N/A
"COMPANY_SIZE" ¿De qué tamaño es su empresa? N/A
"ANNUAL_SALES" ¿Cuál es su volumen anual de ventas? N/A
"YEARS_IN_BUSINESS" ¿Cuántos años lleva en el negocio? N/A
"JOB_DEPARTMENT" ¿En qué departamento trabaja? N/A
"JOB_ROLE" ¿Cuál es su puesto de trabajo? N/A
"EDUCATION_PROGRAM" ¿Qué programa le interesa? N/A
"EDUCATION_COURSE" ¿Qué curso le interesa? N/A
"PRODUCT" ¿Qué producto le interesa? N/A
"SERVICE" ¿Qué servicio le interesa? N/A
"OFFER" ¿Qué oferta le interesa? N/A
"CATEGORY" ¿Qué categoría le interesa? N/A
"PREFERRED_CONTACT_METHOD" Seleccione su forma de contacto preferida N/A
"PREFERRED_LOCATION" Seleccione su ubicación preferida N/A
"PREFERRED_CONTACT_TIME" ¿Cuál es el mejor horario para contactarlo? N/A
"PURCHASE_TIMELINE" ¿Cuándo pretende realizar una compra? N/A
"YEARS_OF_EXPERIENCE" ¿Cuántos años de experiencia laboral tiene? N/A
"JOB_INDUSTRY" ¿En qué industria trabajas? N/A
"LEVEL_OF_EDUCATION" ¿Cuál es su último grado de estudios? N/A
"PROPERTY_TYPE" ¿Qué tipo de propiedad busca? N/A
"REALTOR_HELP_GOAL" ¿Para qué necesita la ayuda de un agente inmobiliario? N/A
"PROPERTY_COMMUNITY" ¿Qué comunidad le interesa? N/A
"PRICE_RANGE" ¿Qué intervalo de precios busca? N/A
"NUMBER_OF_BEDROOMS" ¿Cuántas habitaciones desea? N/A
"FURNISHED_PROPERTY" ¿Busca una propiedad completamente amoblada? N/A
"PETS_ALLOWED_PROPERTY" ¿Busca propiedades donde se permitan mascotas? N/A
"NEXT_PLANNED_PURCHASE" ¿Cuál es el próximo producto que planea comprar? N/A
"EVENT_SIGNUP_INTEREST" ¿Le gustaría registrarse en un evento? N/A
"PREFERRED_SHOPPING_PLACES" ¿Dónde le interesa realizar compras? N/A
"FAVORITE_BRAND" ¿Cuál es su marca favorita? N/A
"TRANSPORTATION_COMMERCIAL_LICENSE_TYPE" ¿Qué tipo de licencia comercial válida tiene? N/A
"EVENT_BOOKING_INTEREST" ¿Te interesa reservar un evento? N/A
"DESTINATION_COUNTRY" ¿Cuál es su país de destino? N/A
"DESTINATION_CITY" ¿Cuál es su ciudad de destino? N/A
"DEPARTURE_COUNTRY" ¿Cuál es su país de origen? N/A
"DEPARTURE_CITY" ¿Cuál es su ciudad de origen? N/A
"DEPARTURE_DATE" ¿Cuál es su fecha de salida? N/A
"RETURN_DATE" ¿Cuál es su fecha de regreso? N/A
"NUMBER_OF_TRAVELERS" ¿Con cuántas personas viajará? N/A
"TRAVEL_BUDGET" ¿Qué presupuesto de viaje tiene? N/A
"TRAVEL_ACCOMMODATION" ¿Dónde desea alojarse durante su viaje? N/A
asset_group_id Este campo solo se propaga para las campañas de máximo rendimiento. Indica el ID del contenedor que contiene el formulario de clientes potenciales.

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

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 que se puede reintentar?
200 {} N/A
4XX {"message: Texto de error de formato libre que describe el error de la solicitud"} No
5XX {"message: Intermittent retraible error optional message"}

Duplicados

No se garantiza que un solo cliente potencial se publique exactamente una vez, por lo que el webhook de manejo de clientes potenciales debe controlar los duplicados de forma fluida.