Google Ads

Visão geral

O Google Ads é a plataforma de publicidade online do Google, onde anunciantes criam e gerenciam campanhas de anúncios exibidos em buscas, sites parceiros e vídeos. Com a integração no SquadOS, seus agentes podem automatizar o gerenciamento de campanhas, consultar métricas de desempenho via GAQL, criar e atualizar listas de clientes para segmentação de audiência e executar operações em lote sobre grupos de anúncios e campanhas.

• Site oficial: https://ads.google.com/
• Documentação na Composio: docs.composio.dev/toolkits/googleads

Autenticação

Esta ferramenta utiliza OAuth 2.0 (OAUTH2) para conectar.

Você vai precisar dos seguintes campos:

Campo	Obrigatório	Descrição
customer_id	Sim	ID da conta Google Ads (cliente) que os agentes devem operar. Disponível no painel do Google Ads no canto superior direito.

Como conectar no SquadOS

1. Acesse Ferramentas no menu lateral (/admin/tools).
2. Abra a aba Disponíveis e procure por Google Ads.
3. Clique no card para abrir o modal de detalhes e em Conectar.
4. Você é levado para a página de conexão segura hospedada pela Composio, onde autoriza o acesso à sua conta Google Ads via OAuth.
5. Ao concluir, você volta para o SquadOS com a conta conectada e a ferramenta disponível para os agentes. (Detalhes do fluxo em Ferramentas da Organização.)

Ações disponíveis

Adicionar ou remover da lista de clientes

GOOGLEADS_ADD_OR_REMOVE_TO_CUSTOMER_LIST

Adiciona ou remove contatos de uma lista de clientes no Google Ads. Observação: as alterações levam de 6 a 12 horas para ser refletidas na lista. Os endereços de e-mail devem estar em conformidade com as políticas do Google Ads e com as leis de privacidade/consentimento aplicáveis.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
emails	array	Sim	Lista de e-mails dos contatos a serem adicionados ou removidos da lista. Os e-mails devem ser strings válidas, normalizadas (minúsculas, sem espaços); endereços malformados reduzem as taxas de correspondência.
operation	string	Não	Operação a ser realizada na lista de clientes. "create" para adicionar ou "remove" para remover.
resource_name	string	Sim	Nome de recurso da lista de clientes. Por exemplo: customers/1234567890/userLists/1234567890.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Criar lista de clientes

GOOGLEADS_CREATE_CUSTOMER_LIST

Cria uma lista de clientes no Google Ads. Observação: exige uma conexão Google Ads autenticada com customer_id configurado. Listas baseadas em e-mail devem obedecer às políticas do Google Ads e às leis de privacidade/consentimento. Atualizações de membros podem levar várias horas para se propagar; a elegibilidade para segmentação não é imediata após a criação.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da lista de clientes.
description	string	Não	Descrição da lista de clientes.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter campanha por ID

GOOGLEADS_GET_CAMPAIGN_BY_ID

Retorna os detalhes de uma campanha no Google Ads pelo seu ID. Requer uma conexão OAuth ativa com o customer_id correto configurado; um customer_id ausente ou incorreto resultará em resultados vazios.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	ID da campanha a ser buscada no Google Ads.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter campanha por nome

GOOGLEADS_GET_CAMPAIGN_BY_NAME

Consulta o Google Ads via SQL para recuperar uma campanha pelo seu nome exato. Requer uma conexão Google Ads ativa com customer_id válido e escopos OAuth adequados.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da campanha a ser buscada no Google Ads. A correspondência usa igualdade SQL exata; campanhas pausadas ou inativas podem não retornar resultados — um resultado vazio indica que nenhuma campanha ativa com esse nome foi encontrada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter listas de clientes

GOOGLEADS_GET_CUSTOMER_LISTS

Lista todas as listas de clientes (audiências/listas de remarketing) no Google Ads. Estas são segmentos de usuários para segmentação, não contas do Google Ads — os IDs de lista são distintos dos IDs de conta. Quando múltiplas listas compartilham nomes semelhantes, revise todos os resultados retornados antes de selecionar um para operações subsequentes.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar clientes acessíveis

GOOGLEADS_LIST_ACCESSIBLE_CUSTOMERS

Recupera todas as contas de cliente do Google Ads acessíveis ao usuário autenticado. Retorna os nomes de recurso dos clientes (ex: customers/1234567890) que podem ser acessados com as credenciais OAuth atuais. Use esta ação para descobrir quais IDs de cliente estão disponíveis antes de fazer outras chamadas à API, ou para popular uma lista de contas disponíveis para o usuário selecionar.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Modificar grupos de anúncios

GOOGLEADS_MUTATE_AD_GROUPS

Cria, atualiza ou remove grupos de anúncios dentro de campanhas do Google Ads. Suporta operações em lote com múltiplas alterações de grupos de anúncios em uma única requisição. Use quando precisar gerenciar grupos de anúncios programaticamente — criando novos grupos, atualizando configurações/status ou removendo grupos desnecessários. Esta ação é irreversível para operações de remoção — grupos de anúncios excluídos não podem ser recuperados.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
operations	array	Sim	Lista de operações de grupos de anúncios (criar, atualizar ou remover). Pelo menos uma operação é obrigatória.
validate_only	boolean	Não	Se true, valida a requisição sem executá-la. Útil para testar antes de aplicar alterações reais.
partial_failure	boolean	Não	Se true, operações válidas terão sucesso mesmo que outras falhem. O padrão é false.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Modificar campanhas

GOOGLEADS_MUTATE_CAMPAIGNS

Cria, atualiza ou remove campanhas do Google Ads em lote. Suporta múltiplas operações (criar, atualizar, remover) em uma única requisição. Use ao gerenciar o ciclo de vida de campanhas, aplicar alterações em massa ou automatizar fluxos de gerenciamento de campanhas. Esta ação é irreversível para operações de remoção — campanhas excluídas não podem ser recuperadas. Considere usar validate_only=true para testar alterações antes de aplicá-las.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
operations	array	Sim	Lista de operações de campanha a executar. Cada operação pode ser criar, atualizar ou remover. Pelo menos uma operação é obrigatória.
validate_only	boolean	Não	Se true, valida a requisição sem executá-la. Útil para testar antes de aplicar alterações reais.
partial_failure	boolean	Não	Se true, operações válidas terão sucesso mesmo que outras falhem. As falhas parciais serão relatadas na resposta.
response_content_type	string	Não	Define se deve retornar o recurso completo ou apenas o nome do recurso. Opções: 'RESOURCE_NAME_ONLY' ou 'MUTABLE_RESOURCE'.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Consultar GAQL em stream

GOOGLEADS_SEARCH_STREAM_GAQL

Executa uma consulta na Google Ads Query Language (GAQL) e transmite todos os resultados em uma única resposta. Este método é mais eficiente do que a busca paginada para recuperação de dados em massa de campanhas, grupos de anúncios e métricas de desempenho (cliques, impressões, custo). Use quando precisar do conjunto completo de resultados sem paginação.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
query	string	Sim	A string de consulta GAQL. Deve seguir o formato SELECT ... FROM ... WHERE .... Exemplo: SELECT campaign.name, campaign.id, metrics.impressions FROM campaign WHERE campaign.status = 'ENABLED'.
summary_row_setting	string	Não	Define se deve incluir uma linha de resumo com métricas agregadas. Use 'UNSPECIFIED' para o padrão, 'DONOT_POST' para omitir o resumo ou 'GENERATE' para incluí-lo.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.