Bloco do Firebase - Firestore e Cloud Messaging no Seu Chatbot

Visão Geral

O Bloco do Firebase conecta seu chatbot do ChatMaxima diretamente a um projeto do Firebase. Ele permite que seu fluxo leia e grave documentos no Cloud Firestore e envie notificações push FCM para os usuários do seu app móvel ou web, tudo a partir de um único bloco. Qualquer operação que você configurar é executada no ponto exato da conversa em que você solta o bloco, então seu bot pode buscar dados no Firestore, armazenar estado de volta nele ou acionar uma notificação push em resposta a um estado específico da conversa.

Os casos de uso típicos incluem armazenar dados de leads nas suas próprias coleções do Firestore, consultar o perfil de um usuário autenticado por ID, verificar o status de um pedido ou agendamento no backend do seu app e enviar notificações aos dispositivos de um usuário quando a conversa atinge um marco (pedido confirmado, compromisso agendado, ticket de suporte resolvido). O bloco cuida da autenticação, do cache de tokens e do roteamento de erros automaticamente, então você só precisa escolher uma operação e preencher os campos que importam para ela.

Pré-requisitos

Antes de adicionar o bloco do Firebase a um fluxo, certifique-se de ter:

• Um projeto do Firebase com o Cloud Firestore ativado. O Realtime Database não é suportado neste bloco (a v1 cobre apenas o Firestore).
• Uma chave JSON de conta de serviço baixada do seu projeto do Firebase. No Console do Firebase, vá para Configurações do Projeto, abra a aba Contas de Serviço e clique em Gerar nova chave privada. Salve o arquivo JSON baixado. Você colará o conteúdo dele no ChatMaxima na próxima etapa.
• FCM configurado no seu app cliente se você planeja enviar notificações push. Cada dispositivo deve ser registrado no Firebase e ter seu token de registro FCM armazenado em um lugar que o bot possa buscar (normalmente um array users/{user_id}.tokens no Firestore).

Nota: A chave da conta de serviço é um segredo de longa duração. Trate-a da mesma forma que trataria a senha de um banco de dados de produção. Não a inclua no controle de versão nem a compartilhe em chats.

Etapa 1: Conecte o Firebase como uma Integração

1. Vá para Painel → Integrações e clique em Adicionar Integração
2. Selecione Firebase no menu suspenso de plataformas
3. Insira um nome (por exemplo, Production Firebase ou My App Firestore) para reconhecê-lo depois
4. Cole todo o conteúdo do arquivo JSON da conta de serviço no campo JSON da Conta de Serviço
5. Clique em Verificar e Salvar

O ChatMaxima valida a credencial assinando um JWT com a chave privada, trocando-o por um token de acesso OAuth e fazendo uma chamada de teste ao endpoint listCollectionIds do Firestore. Se o projeto tiver o Firestore ativado e a conta de serviço tiver acesso, você verá Integração do Firebase conectada. A integração agora está disponível para todos os bots da sua equipe.

Nota: O token de acesso é armazenado em cache dentro do ChatMaxima e atualizado automaticamente antes de expirar. Você não precisa rotacionar ou inserir novamente o JSON da conta de serviço, a menos que queira migrar para um projeto diferente do Firebase.

Etapa 2: Adicione o Bloco do Firebase a um Fluxo

1. Abra seu chatbot no Studio
2. Clique com o botão direito no canvas (ou arraste da barra lateral esquerda) e escolha Firebase em Integrações Externas
3. Dê um clique duplo no bloco para abrir sua configuração
4. Selecione a integração que você criou na Etapa 1 no menu suspenso Selecionar Integração
5. Escolha uma operação e preencha os campos descritos abaixo

Operações Disponíveis

O bloco do Firebase suporta sete operações. As seis primeiras funcionam com o Cloud Firestore. A sétima envia uma notificação push do Cloud Messaging (FCM).

Operação	Categoria	O Que Faz
Obter Documento	Firestore	Lê um único documento por coleção e ID de documento
Adicionar Documento	Firestore	Cria um novo documento. O Firestore gera o ID automaticamente se você deixar em branco
Definir Documento	Firestore	Sobrescreve o documento em um ID específico. Substitui todos os campos
Atualizar Documento	Firestore	Mescla apenas os campos que você fornece em um documento existente
Excluir Documento	Firestore	Remove um documento em um ID específico
Consultar Coleção	Firestore	Filtra, ordena e limita uma coleção de documentos
Enviar Notificação	Cloud Messaging	Envia uma notificação para um dispositivo, vários dispositivos ou um tópico

Toda entrada (coleção, ID de documento, valores de campo, token FCM, título e corpo da notificação) suporta variáveis do ChatMaxima com a sintaxe {variable}, então você pode preenchê-las a partir de blocos de pergunta anteriores, chamadas de API anteriores ou dados recebidos em um bloco de Webhook.

Configuração da Operação

Obter Documento

Lê um documento por ID. Use isso para consultar o perfil de um usuário, buscar o estado atual de um pedido ou puxar qualquer registro cujo ID você já tenha.

Campo	Descrição
Coleção	Nome da coleção do Firestore (por exemplo, users, orders). Escolha na lista detectada ou digite uma nova
ID do Documento	O ID a ser lido. Suporta variáveis como {user_id}
Armazenar a resposta na variável	Nome da variável do ChatMaxima que guarda o resultado

Adicionar Documento

Cria um novo documento em uma coleção. Deixe o ID do Documento em branco para que o Firestore gere um automaticamente, ou forneça o seu próprio (por exemplo, {lead_id}).

Campo	Descrição
Coleção	Coleção de destino
ID do Documento (opcional)	Deixe em branco para ID automático, ou forneça um personalizado
Mapeamento de Campos	Linhas de chave/valor. As chaves são nomes de campo do Firestore, os valores podem ser literais ou referências {variable}
Armazenar a resposta na variável	O documento salvo (com seu ID gerado) é armazenado aqui

Definir Documento

Sobrescreve o documento em collection/document_id com exatamente os campos que você listar. Quaisquer campos que estavam anteriormente no documento mas não estão no seu mapeamento são removidos. Use isso quando quiser uma substituição limpa em vez de uma mesclagem.

Atualizar Documento

Mescla apenas os campos que você fornece em um documento existente. Campos que não estão no seu mapeamento permanecem intocados. Esta é a operação de gravação mais segura para atualizar incrementalmente o perfil de um usuário ou o registro de um pedido.

Excluir Documento

Remove o documento em collection/document_id. A variável de resposta conterá {"success": true} se a exclusão for bem-sucedida.

Consultar Coleção

Executa uma consulta estruturada do Firestore em uma coleção. Suporta filtros, ordenação e um limite de linhas.

Campo	Descrição
Coleção	Coleção a consultar
Filtros de Consulta	Linhas de field, operator, value. Combinadas com AND
Ordenar Por Campo	Nome de campo opcional para ordenar
Direção da Ordenação	Crescente ou Decrescente
Limite	Número máximo de documentos a retornar. Deixe em branco para sem limite

Operadores de filtro suportados:

Operador	Significado
EQUAL	Campo igual ao valor
NOT_EQUAL	Campo diferente do valor
LESS_THAN	Campo menor que o valor
LESS_THAN_OR_EQUAL	Campo menor ou igual ao valor
GREATER_THAN	Campo maior que o valor
GREATER_THAN_OR_EQUAL	Campo maior ou igual ao valor
ARRAY_CONTAINS	Campo é um array que contém o valor
IN	Valor do campo é um dos valores listados
ARRAY_CONTAINS_ANY	Array do campo contém qualquer um dos valores listados
NOT_IN	Valor do campo não é nenhum dos valores listados

Enviar Notificação

Envia uma notificação push FCM. Escolha um de três destinos:

Enviar Para	Quando Usar
Um Único Dispositivo	Um token de registro FCM específico
Vários Dispositivos	Multicast para muitos tokens em uma etapa. Aceita uma variável que resolve para um array JSON, uma string separada por vírgulas ou um array nativo
Um Tópico	Transmite para todos os dispositivos inscritos em um tópico (por exemplo, premium-users)

Campos de configuração:

Campo	Descrição
Token / Tokens / Tópico do FCM	O destinatário, dependendo do tipo de destino. Variáveis suportadas
Título da Notificação	Manchete em negrito exibida na notificação push
Corpo da Notificação	Texto da mensagem exibido abaixo do título
Carga de Dados	Pares chave/valor opcionais entregues silenciosamente junto com a notificação. Úteis para deep linking (por exemplo, screen=orders, order_id={order_id}). Os valores são convertidos em string antes do envio, conforme as regras do FCM

Formato da Variável de Resposta

Toda operação armazena um resultado JSON na variável que você nomeia em Armazenar a resposta na variável. Os blocos seguintes podem referenciar campos usando notação de ponto, por exemplo {user_data.data.email}.

Leituras do Firestore (Obter Documento)

{
  "id": "user_42",
  "name": "projects/my-project/databases/(default)/documents/users/user_42",
  "data": {
    "name": "Priya",
    "email": "priya@example.com",
    "tokens": ["iphone_tok", "ipad_tok"]
  },
  "create_time": "2026-04-20T10:30:00Z",
  "update_time": "2026-04-21T14:15:00Z"
}

Gravações do Firestore (Adicionar / Definir / Atualizar)

O mesmo formato que Obter Documento. O campo id reflete o ID final do documento (gerado automaticamente se você não tiver fornecido um).

Exclusão do Firestore

{ "success": true }

Consultar Coleção

Um array de objetos de documento, cada um com o formato acima:

[
  { "id": "order_1", "data": { "status": "confirmed", "amount": 900 }, "create_time": "..." },
  { "id": "order_2", "data": { "status": "confirmed", "amount": 1200 }, "create_time": "..." }
]

Enviar Notificação (único / tópico)

{
  "success": true,
  "message_name": "projects/my-project/messages/0:17045...",
  "target_type": "token",
  "target_value": "iphone_tok"
}

Enviar Notificação (multicast)

{
  "success": true,
  "sent": 2,
  "failed": 1,
  "invalid_tokens": ["stale_tok"],
  "results": [
    { "token": "iphone_tok", "success": true, "message_name": "..." },
    { "token": "ipad_tok",   "success": true, "message_name": "..." },
    { "token": "stale_tok",  "success": false, "error": "Requested entity was not found.", "error_code": "UNREGISTERED" }
  ]
}

O array invalid_tokens lista os tokens que o Firebase sinalizou como obsoletos (UNREGISTERED, INVALID_ARGUMENT, NOT_FOUND). Use um bloco do Firebase de acompanhamento com Atualizar Documento para removê-los da sua própria coleção users do Firestore, de modo a parar de mirar dispositivos mortos.

Casos de Uso Comuns

Notificação Push de Confirmação de Pedido

Um cliente conclui o checkout no app, e você quer que o bot envie uma confirmação para todos os dispositivos que o usuário registrou.

1. Bloco de Pergunta: Capture ou verifique {user_id}
2. Bloco do Firebase (Obter Documento): Coleção users, ID do Documento {user_id}, armazene o resultado em {user_data}
3. Bloco de Condição: Ramifique em {order_status} == "confirmed"
4. Bloco do Firebase (Enviar Notificação, Vários Dispositivos): Tokens {user_data.data.tokens}, título Order confirmed, corpo Hi {user_data.data.name}, your order {order_id} is on its way
5. Bloco de Mensagem: We have sent a confirmation to your devices

Gravar Leads do Chatbot no Firestore

Use o Firestore como a fonte da verdade para leads recebidos, para que seu próprio app móvel possa reagir em tempo real.

1. Bloco de Pergunta: Pergunte por {name}, {email}, {phone}
2. Bloco do Firebase (Adicionar Documento): Coleção chatbot_leads, campos name={name}, email={email}, phone={phone}, source=chatbot
3. Bloco de Mensagem: Thanks {name}, we will be in touch shortly

Verificar Disponibilidade de Agendamento

Antes de confirmar um agendamento, consulte o Firestore para garantir que o horário ainda está aberto.

1. Bloco do Firebase (Consultar Coleção): Coleção bookings, filtro slot_id EQUAL {slot_id} e status NOT_EQUAL cancelled, limite 1, armazene em {existing_bookings}
2. Bloco de Condição: Ramifique conforme {existing_bookings} esteja vazio
3. Se vazio: Bloco do Firebase (Adicionar Documento) para criar o agendamento, depois Bloco de Mensagem para confirmar
4. Se houver correspondência: Bloco de Mensagem That slot was just taken, please pick another

Transmitir para um Tópico

Envie um comunicado de um para muitos a todos os dispositivos inscritos em um tópico.

1. Bloco de Gatilho: O administrador aciona o fluxo com uma Campanha
2. Bloco do Firebase (Enviar Notificação, Tópico): Tópico premium-users, título New feature released, corpo Tap to try it out, dados screen=whats_new

Limpar Tokens FCM Obsoletos

Após um envio multicast, remova os tokens mortos do perfil do usuário para que envios futuros vão apenas a dispositivos ativos.

1. Bloco do Firebase (Enviar Notificação, Vários Dispositivos): Armazene o resultado em {push_result}
2. Bloco de Condição: Ramifique conforme {push_result.invalid_tokens} não esteja vazio
3. Bloco de Código ou Bloco de API: Calcule a lista de tokens depurada
4. Bloco do Firebase (Atualizar Documento): Coleção users, ID do Documento {user_id}, campo tokens={pruned_tokens}

Boas Práticas

• Defina o escopo da conta de serviço adequadamente. Crie uma conta de serviço dedicada para o ChatMaxima e conceda a ela apenas as funções de Firestore e FCM de que precisa. Não use a chave padrão do Admin SDK em produção
• Armazene tokens FCM como um array. Os usuários costumam ter vários dispositivos. Mantê-los em um único campo tokens por usuário torna os envios multicast triviais
• Trate a ramificação de erro. Todo bloco do Firebase tem uma segunda saída que dispara quando a operação falha. Roteie-a para uma mensagem de recuperação ou uma nova tentativa, em vez de deixar o fluxo travar
• Remova tokens obsoletos. O FCM retorna UNREGISTERED quando um token está morto. Use o campo invalid_tokens na resposta multicast para limpar os perfis dos seus usuários
• Mantenha os valores da carga de dados pequenos. O FCM exige que todos os valores da carga de dados sejam strings e que o tamanho total da mensagem fique abaixo de 4 KB. O ChatMaxima converte os valores em string automaticamente, mas grandes blobs JSON serão rejeitados pelo Firebase
• Não vaze o JSON da conta de serviço. Depois de salvo no ChatMaxima, o JSON não é exposto de volta na interface. Trate o arquivo baixado com o mesmo cuidado de qualquer outro segredo de produção

Perguntas Frequentes

Quais produtos do Firebase o bloco suporta?

Cloud Firestore (leitura / gravação / consulta) e Cloud Messaging (API FCM HTTP v1). Realtime Database, Firebase Authentication, Cloud Functions e In-App Messaging não são tratados por este bloco.

Posso usar o mesmo bloco para Firestore e FCM?

Sim. Uma única credencial de integração do Firebase autoriza ambos os produtos. Solte blocos do Firebase separados para cada operação de que precisar (por exemplo, um bloco Obter Documento para consultar os tokens do usuário, depois um bloco Enviar Notificação para enviar a esses tokens).

Onde meu JSON da conta de serviço é armazenado?

Dentro da tabela chatbot_integration_tokens, com escopo limitado à sua equipe. O JSON nunca é retornado ao navegador após ser salvo. O ChatMaxima o usa do lado do servidor para gerar tokens de acesso OAuth de curta duração para o Firebase.

Por que a notificação chega mas a carga de dados está ausente?

O FCM exige que os valores da carga de dados sejam strings. Se você passar uma variável numérica ou booleana diretamente, o ChatMaxima a converte em string para você, mas alguns apps clientes esperam formatos específicos. Verifique como seu app lê RemoteMessage.getData() no Android ou userInfo no iOS.

Meu envio multicast mostra que alguns tokens falharam. O que faço?

Veja o array invalid_tokens na variável de resposta. Esses são tokens que o Firebase considera mortos. Use um bloco Atualizar Documento para removê-los do array tokens do usuário no Firestore, de modo que não sejam mirados novamente.

O bloco pode enviar para um ID de usuário em vez de um token FCM?

Não diretamente. O FCM endereça dispositivos por token de registro, não por usuário. O padrão normal é: armazenar os tokens do usuário no Firestore em users/{user_id}, usar um bloco Obter Documento para buscá-los e depois passar o array de tokens para o bloco Enviar Notificação.

Posso consultar subcoleções?

O bloco atual consulta coleções de nível superior. Consultas aninhadas ou de subcoleção (por exemplo, users/{uid}/orders) estão no roadmap. Como alternativa, armazene dados desnormalizados em uma coleção de nível superior indexada por ID de usuário.

Como testo o bloco antes de entrar no ar?

Crie um projeto sandbox do Firebase com alguns documentos de teste. Conecte-o como uma integração separada do ChatMaxima, aponte o bloco para ela e execute o fluxo a partir do modo Prévia no Studio. Mude o bloco para a integração de produção quando estiver satisfeito.

Solução de Problemas

Verificar e Salvar falha com "Credencial rejeitada pelo Firestore"

1. Abra seu projeto do Firebase e confirme que o Cloud Firestore está ativado (Console → Firestore Database)
2. Verifique se a conta de serviço tem pelo menos a função Cloud Datastore User (IAM → Contas de Serviço)
3. Certifique-se de que você colou o arquivo JSON inteiro, incluindo o campo private_key com os escapes de nova linha \n intactos
4. Regenere a chave privada se o arquivo original foi editado ou copiado parcialmente

O bloco mostra "Integração do Firebase não encontrada"

1. Confirme que a integração existe em Painel → Integrações e está ativa
2. Se você criou a integração recentemente, atualize o modal do bloco usando o botão de atualizar ao lado do menu suspenso de integração
3. Exclua e recrie a integração se a credencial foi rotacionada no Firebase

O Firestore retorna "Documento não encontrado" (404)

1. Verifique se o nome da coleção está escrito exatamente como aparece no Firebase (sensível a maiúsculas)
2. Verifique o ID do documento. Se ele vem de uma variável, inspecione o registro da conversa para ver o valor real sendo substituído
3. Lembre-se de que o Firestore trata um documento ausente de forma diferente de um vazio. O bloco retorna not_found: true na variável de resposta para que você possa ramificar com base nisso

A notificação FCM não chega ao dispositivo

1. Confirme que o token FCM é válido. Os tokens expiram quando o app é desinstalado ou reinstalado
2. Verifique se o dispositivo tem permissões de notificação concedidas para o seu app
3. Inspecione a variável de resposta. Um envio bem-sucedido retorna message_name. Uma falha retorna error e, muitas vezes, um error_code como UNREGISTERED
4. Verifique se o dispositivo não está em modo de economia de bateria ou bloqueado pelo Não Perturbe no nível do sistema

O envio para o tópico tem sucesso mas ninguém recebe

1. A entrega de tópico é de melhor esforço e pode levar até um minuto
2. Confirme que os dispositivos realmente se inscreveram no tópico (messaging().subscribeToTopic('premium-users') no cliente)
3. Os nomes de tópico são sensíveis a maiúsculas e não podem começar com /topics/ na API v1. Use apenas o nome, por exemplo premium-users

A variável de resposta está vazia

1. Certifique-se de ter preenchido o campo Armazenar a resposta na variável no bloco
2. Verifique se o nome da variável não colide com uma palavra-chave reservada ou com a variável de outro bloco
3. Inspecione o registro da conversa para ver o resultado bruto da chamada ao Firebase

Próximas Etapas

• Bloco de API - Chame qualquer API REST externa a partir do seu fluxo
• Bloco de Webhook - Receba chamadas HTTP de entrada no seu fluxo
• Bloco de Condição - Ramifique o fluxo com base nos valores das variáveis
• Visão Geral do Studio - Explore todos os tipos de bloco e os recursos do construtor de fluxos