Como funciona a API de Conversões da OpenAI Ads
A API de Conversões da OpenAI Ads envia para a OpenAI, direto do sistema, o que acontece com os leads e os negócios da imobiliária. Com isso, você acompanha no Gerenciador de Anúncios da OpenAI quais campanhas trouxeram contatos e quais desses contatos avançaram no funil, foram ganhos ou foram perdidos. Como o envio parte do sistema, ele não depende do navegador do visitante.
Você configura a integração uma vez. Depois disso, o sistema envia os eventos sozinho: quando um lead é cadastrado e quando um negócio muda de etapa, é ganho, é perdido ou é excluído. Cada envio fica registrado no histórico do lead ou do negócio.
Para configurar a integração, você precisa da permissão Configurações > Integrações > Integrações > Editar (ou de Administrar Configurações). Para escolher o evento de cada etapa do funil, você precisa da permissão Negócios > Etapas para Negócios > Editar.
Navegação no módulo
Rotina: Configurações > Integrações > Integrações > cartão API de Conversões da OpenAI Ads
A tela abre com o título Editando Integrações com Aplicativos de Terceiros. Localize o cartão API de Conversões da OpenAI Ads, que fica logo depois do cartão API de Conversões do Meta.
Antes de começar
Você vai precisar de duas informações da conta de anúncios da imobiliária na OpenAI.
Informação | Onde encontrar |
|---|---|
Pixel ID | Na aba Conversões do Gerenciador de Anúncios da OpenAI. |
Chave de API | É a chave fornecida pela OpenAI para o envio de conversões. A janela de configuração traz o link Documentação, que leva às instruções da própria OpenAI. |
Se tiver dúvida sobre onde gerar a Chave de API na sua conta da OpenAI, consulte o suporte.
Ativar a integração
No rodapé do cartão, ligue a chave Ativo. A alteração é gravada na mesma hora.
O botão Configurar só fica disponível com a chave Ativo ligada.
O ícone no canto do cartão mostra a situação da integração:
Ícone | O que significa |
|---|---|
Visto verde | "Integração está ativa". A chave Ativo está ligada e o Pixel ID e a Chave de API estão preenchidos. |
Alerta laranja | A chave Ativo está ligada, mas faltam credenciais. A mensagem diz "Configure o Pixel ID e a Chave de API para ativar o envio de eventos." |
X vermelho | "A integração está desativada". |
Com a chave Ativo desligada, nenhum evento é enviado à OpenAI Ads, nem de lead, nem de funil. Isso vale mesmo que as outras opções da configuração continuem ligadas.
Informar as credenciais
Clique em Configurar. A janela API de Conversões da OpenAI Ads abre no painel Configurações. Preencha os campos:
Campo | Descrição | Obrigatório |
|---|---|---|
Pixel ID | Identificador do Pixel da OpenAI que vai receber os eventos. Fica na aba Conversões do Gerenciador de Anúncios. | Sim |
Chave de API | Chave que autoriza o envio dos eventos. O campo esconde o conteúdo digitado. O botão ao lado, Copiar a chave de API, copia a chave. | Sim |
Clique em Gravar para gravar e fechar a janela, ou em Gravar e Continuar para gravar e seguir na configuração.
Sem os dois campos preenchidos, a integração não envia nada e o cartão continua com o alerta laranja.
A Chave de API é uma credencial de segurança. Trate-a como uma senha e não a compartilhe. Só quem tem permissão para gravar esta configuração consegue ver a chave.
Enviar o evento de lead criado
No painel Lead Criado, ligue a chave Enviar evento de lead criado ao cadastrar lead no sistema e grave.
Com ela ligada, cada lead novo cadastrado no sistema, inclusive o cadastrado à mão em Pessoas > Leads, gera o evento Lead criado para a OpenAI. O envio acontece uma única vez, no cadastro. Editar o lead depois não gera um novo envio.
Leads trazidos por importação de arquivo não são enviados à OpenAI.
Enviar eventos do funil de negócios
Além do lead, a integração pode contar à OpenAI o que acontece durante a negociação. Assim a OpenAI consegue otimizar as campanhas pela qualidade das oportunidades, e não só pelo volume de cadastros.
No painel Funil de Negócio, ligue a chave Enviar eventos de funil (troca de etapa, ganho, perda e exclusão). Logo abaixo aparecem três campos:
Campo | Descrição | Obrigatório |
|---|---|---|
Evento ao Ganhar | Evento enviado quando o negócio é marcado como ganho. Em branco, é enviado o evento Venda ou locação concluída. O evento de ganho leva junto o valor do negócio (campo Valor), quando ele está preenchido. | Não |
Evento ao Perder | Evento enviado quando o negócio é marcado como perdido. Em branco, é enviado um evento personalizado de negócio perdido. | Não |
Evento ao Excluir | Evento enviado quando o negócio é excluído. Em branco, é enviado um evento personalizado de negócio excluído. | Não |
Os três campos são listas, porque a OpenAI só aceita estes eventos:
- Lead criado
- Visita ou reunião agendada
- Cadastro concluído
- Imóvel visualizado
- Imóvel adicionado à seleção
- Negociação iniciada
- Venda ou locação concluída
- Página visualizada
- Assinatura iniciada
- Período de teste iniciado
- Evento personalizado (leva o nome da etapa)
A troca de etapa usa o evento escolhido no cadastro de cada etapa, como mostra a próxima seção.
Escolher o evento em cada etapa do funil
Rotina: Configurações > Negócios > aba Funis
Na aba Funis, localize o funil e clique no lápis da etapa desejada (Editar esta Etapa do Funil). A janela Etapa de Negócio abre.
No campo Evento (OpenAI Ads Conversions API), escolha o evento que deve ser enviado à OpenAI quando um negócio entrar nessa etapa. Depois clique em Gravar.
Se você deixar o campo em branco, a etapa não fica de fora: o sistema envia um evento personalizado com o título da etapa. Assim as etapas continuam diferentes umas das outras no Gerenciador de Anúncios.
Só o evento personalizado leva junto os dados da etapa, como o título da etapa, a etapa anterior e o funil. Ao escolher qualquer outro evento da lista, a OpenAI recebe apenas o evento.
Repita nas outras etapas que quiser acompanhar. O mesmo campo aparece ao criar uma etapa nova, pelo botão Adicionar uma nova Etapa de Negócio.
O campo aparece em todas as etapas, mesmo com a integração desligada. Ele só tem efeito com a chave Ativo do cartão ligada e com a opção Enviar eventos de funil ativada.
Utilizar o modo de teste
No painel Modo de Teste, a chave Enviar eventos como teste serve para validar a integração antes de usar os eventos de verdade.
Enquanto ela estiver ligada, a OpenAI confere cada evento, mas não o grava. No histórico do lead e do negócio, os registros de envio aparecem com a marca [TESTE], para não serem confundidos com eventos reais.
Com o modo de teste ligado, nenhuma conversão fica registrada na OpenAI. Depois de validar, desligue a chave e clique em Gravar.
Conferir se a integração funcionou
- Com o Pixel ID e a Chave de API preenchidos, ligue Enviar eventos como teste e clique em Gravar.
- Cadastre um lead de teste em Pessoas > Leads, com e-mail ou telefone.
- Abra o lead e clique no botão de histórico (Abrir janela de históricos).
- Confira se aparece a mensagem "[TESTE] Lead enviado para a API de Conversões da OpenAI Ads.". Se aparecer uma mensagem de erro, veja a seção Quando o envio não acontece.
- Para testar o funil, vá em Negócios > Negócios em Painel, mova para outra etapa um negócio que tenha lead vinculado e confira o histórico do negócio.
- Depois de validar, desligue Enviar eventos como teste e grave.
O que aparece no lead e no negócio
A integração não muda nenhum campo do lead nem do negócio. O resultado de cada envio aparece no histórico:
Onde | Mensagem | Quando aparece |
|---|---|---|
Histórico do lead | "Lead enviado para a API de Conversões da OpenAI Ads." | O evento de lead criado foi enviado. |
Histórico do negócio | "Negócio enviado para a API de Conversões da OpenAI Ads (evento...)." | Um evento de troca de etapa, ganho, perda ou exclusão foi enviado. Entre parênteses aparece o nome do evento, do jeito que a OpenAI o recebe. |
Histórico do lead ou do negócio | "Erro ao enviar para a API de Conversões da OpenAI Ads:" seguido do motivo | O envio não aconteceu ou foi recusado pela OpenAI. |
Com o modo de teste ligado, essas mensagens começam com [TESTE].
Logo abaixo de cada mensagem, o histórico guarda os dados que foram enviados à OpenAI. Esse complemento fica disponível por 3 meses. A mensagem de envio continua no histórico depois disso.
No cadastro do lead, o campo Código da Campanha mostra o código do anúncio quando o lead veio de uma campanha paga, inclusive dos anúncios do ChatGPT (OpenAI).
Quando o envio não acontece
- Chave Ativo desligada: nada é enviado, nem de lead, nem de funil.
- Pixel ID ou Chave de API em branco: nada é enviado.
- Chave do lead ou do funil desligada: com Enviar evento de lead criado ao cadastrar lead no sistema desligada, os leads não são enviados. Com Enviar eventos de funil desligada, os negócios não são enviados.
- Lead importado: leads trazidos por importação de arquivo não são enviados.
- Lead sem e-mail e sem telefone: a OpenAI não teria como reconhecer a pessoa. O evento não é enviado e o histórico mostra o motivo "evento omitido (sem identificador de contato)". A exceção é quando o site envia junto a identificação do navegador do visitante.
- Data do Contato antiga: lead com Data do Contato de mais de 7 dias atrás não é enviado, e o histórico registra que o evento foi ignorado.
- Data do Contato no futuro: lead com Data do Contato mais de 10 minutos à frente do horário atual não é enviado. O histórico mostra "evento ignorado (data do evento mais de 10 minutos no futuro)".
- Negócio sem lead vinculado: nada é enviado e nada aparece no histórico do negócio. Os dados de contato usados nos eventos do negócio vêm do lead mais recente vinculado a ele.
- Negócio recém-cadastrado: a entrada do negócio na primeira etapa, no momento do cadastro, não gera evento. O envio acontece nas trocas de etapa seguintes.
Deduplicação com o Pixel do site
Se o site da imobiliária também usa o Pixel da OpenAI, o mesmo lead pode aparecer duas vezes nos relatórios do Gerenciador de Anúncios: uma vez registrado pelo site e outra pelo sistema. Segundo o aviso da própria tela, isso não afeta o funcionamento das campanhas.
Para evitar a contagem dupla, o Pixel do site precisa reaproveitar o identificador que o sistema publica depois do envio do formulário. O painel Deduplicação com o Pixel do Site, na janela da integração, traz as instruções técnicas. Repasse-as a quem cuida das tags do seu site.
O mesmo painel orienta a enviar junto do lead o código de clique do anúncio e a referência de navegador do Pixel. São essas informações que permitem à OpenAI atribuir a conversão à campanha certa.
Para saber se o seu site já faz essa configuração, consulte o suporte.
Diferenças em relação à integração com o Meta
As duas integrações funcionam lado a lado, cada uma com a própria configuração. Ligar uma não liga a outra, e a mesma etapa do funil pode ter um evento diferente para cada uma.
Ponto | API de Conversões do Meta | API de Conversões da OpenAI Ads |
|---|---|---|
Credenciais | Pixel ID e Access Token | Pixel ID e Chave de API |
Evento de lead | Lead | Lead criado |
Eventos de ganho, perda, exclusão e etapa | Nome digitado livremente | Escolhido em uma lista, porque a OpenAI recusa nomes fora dela |
Campo na etapa do funil | Nome do Evento (Meta Conversions API) | Evento (OpenAI Ads Conversions API) |
Modo de teste | Usa o Test Event Code gerado no Meta | Não tem código: a OpenAI só confere o evento, sem gravar |
Perguntas frequentes
➜ Liguei a integração e nada aparece no histórico do lead. O que devo verificar? Confira se a chave Ativo do cartão está ligada, se o Pixel ID e a Chave de API estão preenchidos e se a chave Enviar evento de lead criado ao cadastrar lead no sistema está ligada. Lembre que só leads cadastrados depois disso são enviados, e que leads importados ficam de fora.
➜ Mudei um negócio de etapa e não apareceu nada no histórico. Por quê? Confira se a chave Enviar eventos de funil está ligada e se o negócio tem um lead vinculado. Negócio sem lead vinculado não gera envio.
➜ Posso digitar o nome do evento, como faço no Meta? Não. A OpenAI só aceita os eventos da lista, por isso os campos são de seleção. Para identificar uma etapa pelo nome, deixe o campo em branco: o sistema envia um evento personalizado com o título da etapa.
➜ Preciso escolher um evento em todas as etapas? Não. Etapa sem evento escolhido também é enviada, como evento personalizado com o título da etapa.
➜ Os dados do cliente são enviados abertos para a OpenAI? Não. Antes de sair do sistema, o e-mail, o telefone e o nome do lead são convertidos, de forma irreversível, em uma sequência que não revela o dado original.
➜ Posso usar a OpenAI Ads e o Meta ao mesmo tempo? Sim. Cada integração tem a própria configuração e envia os próprios eventos. Desligar uma não interfere na outra.
Nenhum comentário para exibir
Nenhum comentário para exibir