Bubble

Visão geral

Bubble é uma linguagem de programação visual e uma plataforma como serviço (PaaS) desenvolvida pelo Bubble Group. Ela permite criar aplicativos web completos sem escrever código, com banco de dados integrado, lógica de negócio e interface visual. Com a integração Bubble no SquadOS, seus agentes podem interagir diretamente com os dados e workflows de qualquer aplicativo Bubble via API.

Site oficial: https://bubble.io/
Documentação na Composio: docs.composio.dev/toolkits/bubble

Autenticação

Esta ferramenta utiliza chave de API (API_KEY) para conectar.

Você vai precisar dos seguintes campos:

Campo	Obrigatório	Descrição
`full`	Sim	URL raiz da sua Data API do Bubble. Se estiver usando o domínio padrão: `https://nome-do-app.bubbleapps.io`. Se estiver usando domínio customizado: `https://seudominio.com`.
`bearer_token`	Sim	Token de API gerado nas configurações do seu aplicativo Bubble, usado para autenticar requisições na Data API.

Como obter a credencial

Acesse o editor do seu aplicativo Bubble em bubble.io e selecione o app desejado.
Clique em Settings no menu lateral esquerdo.
Navegue até a aba API.
Marque a opção Enable Data API para ativar a Data API do seu aplicativo.
Na lista de tipos de dados exibida abaixo, selecione quais data types devem ser expostos pela API (marque apenas os necessários).
Role a página até a seção API tokens e clique em Generate a new API token para criar um novo token.
Copie o token gerado — esse é o valor que você usará no campo bearer_token ao conectar no SquadOS.
Para o campo full (Base URL), use o formato https://nome-do-app.bubbleapps.io (substituindo nome-do-app pelo subdomínio do seu app) ou o domínio customizado configurado no app.

Como conectar no SquadOS

Acesse Ferramentas no menu lateral (/admin/tools).
Abra a aba Disponíveis e procure por Bubble.
Clique no card para abrir os detalhes e em Conectar.
Você é levado para a página de conexão segura hospedada pela Composio, onde informa a URL base e o token de API obtidos acima.
Ao confirmar, você volta para o SquadOS com a conta já conectada e a ferramenta disponível para os agentes. (Detalhes do fluxo de conexão em Ferramentas da Organização.)

Ações disponíveis

Criar várias Things em lote

BUBBLE_DATA_BULK_CREATE_THINGS

Cria várias Things no Bubble de uma vez via JSON separado por novas linhas. Use quando precisar inserir muitos registros de uma só vez. É necessário ter a permissão Create via API habilitada.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`items`	array	Sim	Lista de objetos a serem criados. Deve conter entre 1 e 1000 itens.
`typename`	string	Sim	Nome do tipo de dado (Data Type) no Bubble em formato de API (minúsculas, sem espaços).
`subdomain`	string	Não	Subdomínio do app Bubble para direcionar `*.bubbleapps.io` (ex: `meu-app`).
`custom_domain`	string	Não	Host de domínio customizado (ex: `meuapp.exemplo.com`).
`full_url_override`	string	Não	URL completa para sobrescrever o endpoint de bulk. Se fornecida, a requisição será enviada para essa URL como está, ignorando `typename`, `custom_domain` e `subdomain`.

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 uma Thing

BUBBLE_DATA_CREATE_THING

Cria um novo registro (Thing) no Bubble. Use quando você tem um payload JSON completo para adicionar um novo registro.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`fields`	object	Sim	Objeto JSON mapeando nomes de campos para valores da nova Thing. Campos obrigatórios do tipo devem ser fornecidos (ex: `email` para o Data Type `user`).
`typename`	string	Sim	Nome do Data Type (Thing) a criar (diferencia maiúsculas e minúsculas).
`subdomain`	string	Não	Subdomínio do app Bubble para direcionar `*.bubbleapps.io` (ex: `meu-app`).
`custom_domain`	string	Não	Host de domínio customizado (ex: `meuapp.exemplo.com`).
`full_url_override`	string	Não	URL completa para sobrescrever o endpoint de criação. Se fornecida, a requisição será enviada para essa URL como está, ignorando `typename`, `custom_domain` e `subdomain`.

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.

Excluir Thing pelo ID

BUBBLE_DATA_DELETE_THING_BY_ID

Exclui uma Thing do Bubble pelo seu ID único. Use quando precisar remover um registro específico via Data API.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`uid`	string	Sim	Identificador único do registro a excluir.
`typename`	string	Sim	Nome do Data Type do Bubble (minúsculas, sem espaços).
`subdomain`	string	Não	Subdomínio do app Bubble para direcionar `*.bubbleapps.io` (ex: `meu-app`).
`custom_domain`	string	Não	Host de domínio customizado (ex: `meuapp.exemplo.com`).
`full_url_override`	string	Não	URL completa para sobrescrever o endpoint de exclusão. Se fornecida, a requisição será enviada para essa URL como está, ignorando `typename`, `custom_domain` e `subdomain`.

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.

Buscar Thing pelo ID

BUBBLE_DATA_GET_THING_BY_ID

Recupera uma única Thing (registro) de um Data Type do Bubble pelo seu ID único. Operação somente leitura que retorna os detalhes completos do registro. A resposta inclui todos os campos customizados definidos no Data Type, além dos campos padrão do Bubble (_id, created_by, created_date, modified_date). Use quando precisar: buscar detalhes de um registro conhecido pelo ID; verificar se um registro existe; obter os valores mais recentes de uma Thing. Requer que a Data API esteja habilitada nas configurações do app e que o Data Type esteja exposto via API.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`uid`	string	Sim	Identificador único da Thing a recuperar. É o valor retornado no campo `_id` ou `id` quando a Thing foi criada. O Bubble usa tipicamente formato como `1234567890123x123456789012345678`.
`typename`	string	Sim	Nome do Data Type do Bubble (diferencia maiúsculas e minúsculas). É o tipo definido no seu app Bubble (ex: `user`, `order`, `product`). Consulte a aba Data do seu app Bubble para ver os tipos disponíveis.
`subdomain`	string	Não	Subdomínio do app Bubble para direcionar `*.bubbleapps.io` (ex: `meu-app`).
`custom_domain`	string	Não	Host de domínio customizado (ex: `meuapp.exemplo.com`).
`full_url_override`	string	Não	URL completa para sobrescrever o endpoint GET. Se fornecida, a requisição será enviada para essa URL como está, ignorando `typename`, `custom_domain` e `subdomain`.

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.

Atualizar campos de uma Thing

BUBBLE_DATA_PATCH_THING_BY_ID

Modifica apenas os campos selecionados de uma Thing pelo ID único. Use depois de confirmar que a Thing existe.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`uid`	string	Sim	ID único do registro a modificar.
`typename`	string	Sim	Nome do Data Type no formato URL (minúsculas, sem espaços).
`subdomain`	string	Não	Subdomínio do app Bubble para direcionar `*.bubbleapps.io` (ex: `meu-app`).
`custom_domain`	string	Não	Host de domínio customizado (ex: `meuapp.exemplo.com`).
`field_updates`	object	Sim	Objeto JSON de campos a atualizar. Cada chave é o nome de um campo existente; cada valor deve bater com o tipo definido do campo.
`full_url_override`	string	Não	URL completa para sobrescrever o endpoint de patch. Se fornecida, a requisição será enviada para essa URL como está, ignorando `typename`, `custom_domain` e `subdomain`.

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.

Substituir uma Thing

BUBBLE_DATA_PUT_REPLACE_THING_BY_ID

Substitui todos os campos editáveis de uma Thing pelo ID único. Use quando precisar sobrescrever completamente uma Thing e resetar os campos omitidos para o valor padrão.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`uid`	string	Sim	ID único da Thing a sobrescrever.
`data`	object	Sim	Mapeamento de cada nome de campo editável para seu novo valor. Campos editáveis omitidos serão resetados para os valores padrão.
`typename`	string	Sim	Nome do Data Type do Bubble onde fazer a substituição.
`subdomain`	string	Não	Subdomínio do app Bubble para direcionar `*.bubbleapps.io` (ex: `meu-app`).
`custom_domain`	string	Não	Host de domínio customizado (ex: `meuapp.exemplo.com`).
`full_url_override`	string	Não	URL completa para sobrescrever o endpoint PUT. Se fornecida, a requisição será enviada para essa URL como está, ignorando `typename`, `custom_domain` e `subdomain`.

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.

Baixar arquivo

BUBBLE_FILE_DOWNLOAD

Baixa um arquivo dada uma URL. Use quando precisar recuperar o conteúdo de um arquivo e obter um s3key para testes de upload posteriores.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`url`	string	Sim	URL HTTP ou HTTPS do arquivo a baixar.

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 arquivo temporário

BUBBLE_FILE_TEMP_CREATE

Faz upload de bytes como arquivo temporário no Cloudflare R2 e retorna uma S3 key. Use quando precisar de uma referência de arquivo de curta duração antes de persistir em uma Thing.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome a ser atribuído ao arquivo temporário (incluindo extensão).
`content`	string	Sim	Conteúdo do arquivo em base64 ou texto puro.
`mimetype`	string	Sim	Tipo MIME do arquivo.
`subdomain`	string	Não	Subdomínio do app Bubble para direcionar `*.bubbleapps.io` (ex: `meu-app`).
`custom_domain`	string	Não	Host de domínio customizado (ex: `meuapp.exemplo.com`).
`full_url_override`	string	Não	URL completa para sobrescrever o endpoint de upload temporário. Se fornecida, a requisição será enviada para essa URL como está.

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.

Enviar arquivo

BUBBLE_FILE_UPLOAD

Envia um arquivo para o storage do Bubble. Use quando precisar armazenar arquivos arbitrários via endpoint /fileupload do Bubble.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`file`	object	Sim	Arquivo a ser enviado.
`subdomain`	string	Não	Subdomínio Bubble (ex: `meu-app`) para direcionar `https://<subdomain>.bubbleapps.io/fileupload`.
`custom_domain`	string	Não	Host de domínio customizado (ex: `app.exemplo.com`) para direcionar `https://<host>/fileupload`.
`additional_fields`	object	Não	Campos adicionais do formulário multipart a incluir na requisição de upload.
`full_url_override`	string	Não	URL completa para sobrescrever o endpoint de upload (ex: `https://httpbin.org/post`).

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 o Swagger JSON da API Bubble

BUBBLE_META_GET_SWAGGER_JSON

Recupera o Swagger JSON gerado automaticamente para as APIs habilitadas. Use depois de habilitar o arquivo Swagger nas configurações de API do seu app Bubble.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`subdomain`	string	Não	Subdomínio do app Bubble (ex: `meu-app`) para direcionar `*.bubbleapps.io`.
`swagger_url`	string	Não	URL completa do Swagger 2.0 JSON a buscar. Tem precedência se fornecida.
`custom_domain`	string	Não	Host de domínio customizado para direcionar (ex: `meuapp.exemplo.com`).

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 token de acesso OAuth

BUBBLE_O_AUTH_ACCESS_TOKEN

Troca um authorization code ou refresh token por um access token OAuth2. Use depois de obter um authorization code ou ao renovar um token expirado.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`code`	string	Não	Authorization code retornado por `/oauth/authorize`; obrigatório para a troca inicial.
`client_id`	string	Sim	Identificador do cliente OAuth.
`subdomain`	string	Não	Subdomínio do app Bubble (ex: `meu-app`).
`grant_type`	string	Não	Deve ser `refresh_code` ao trocar um refresh token por um novo access token. Observação: o Bubble usa `refresh_code` em vez do valor padrão OAuth 2.0 `refresh_token`.
`redirect_uri`	string	Sim	URI de redirecionamento usada na requisição de autorização.
`client_secret`	string	Sim	Segredo do cliente OAuth.
`custom_domain`	string	Não	Host de domínio customizado (ex: `meuapp.exemplo.com`).
`refresh_token`	string	Não	Refresh token emitido anteriormente; obrigatório quando `grant_type=refresh_code`.
`use_version_test`	boolean	Não	Se deve direcionar o ambiente `/version-test` ao construir a URL.
`token_url_override`	string	Não	URL completa do endpoint de token. Se fornecida, tem precedência sobre URL derivada de domínio/subdomínio/metadata.
`additional_body_fields`	object	Não	Campos adicionais a incluir no corpo JSON do POST.

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.

Autorização OAuth

BUBBLE_OAUTH_AUTHORIZE

Inicia o fluxo de autorização OAuth2 para o Bubble. Use ao configurar uma integração de login de terceiros. Retorna a URL para redirecionamento do user-agent para obtenção do authorization code.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`scope`	string	Não	Lista separada por espaços dos escopos solicitados.
`state`	string	Não	Valor opaco para manter estado entre requisição e callback (token CSRF, etc).
`client_id`	string	Sim	Identificador do cliente OAuth emitido pelo Bubble ao registrar sua aplicação.
`subdomain`	string	Não	Subdomínio do app Bubble (ex: `meu-app`) para direcionar `*.bubbleapps.io`.
`extra_params`	object	Não	Parâmetros de query adicionais a incluir na requisição de autorização.
`redirect_uri`	string	Sim	URL de callback para onde o Bubble enviará o authorization code.
`custom_domain`	string	Não	Host de domínio customizado para direcionar (ex: `meuapp.exemplo.com`).
`response_type`	string	Não	Tipo de resposta OAuth. Para o fluxo authorization code deve ser `code`.
`use_version_test`	boolean	Não	Se `true`, usa `/version-test` no caminho raiz para apps Bubble.
`authorize_url_override`	string	Não	URL completa do endpoint de autorização. Se fornecida, tem precedência sobre URL derivada de subdomínio/custom_domain/metadata.

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.

Registrar app OAuth no Bubble

BUBBLE_O_AUTH_REGISTER_APP

Valida e inicializa as credenciais de uma aplicação OAuth no Bubble. Faz uma chamada real ao endpoint /oauth/authorize do Bubble (ou a um override fornecido) usando client_id e redirect_uri para confirmar conectividade e retornar as credenciais informadas.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`client_id`	string	Sim	Identificador do cliente OAuth conforme configurado no editor Bubble.
`subdomain`	string	Não	Subdomínio do app Bubble (ex: `meu-app`).
`extra_params`	object	Não	Parâmetros de query adicionais a acrescentar na requisição de autorização.
`redirect_uri`	string	Sim	URI de redirecionamento configurada no app OAuth do Bubble.
`client_secret`	string	Não	Segredo do cliente OAuth conforme configurado no editor Bubble.
`custom_domain`	string	Não	Host de domínio customizado (ex: `meuapp.exemplo.com`).
`use_version_test`	boolean	Não	Se deve direcionar o ambiente `/version-test`.
`authorize_url_override`	string	Não	URL completa para chamar ao invés de construir a partir de domínio/subdomínio. Útil para testes.

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.

Disparar workflow do Bubble via GET

BUBBLE_WORKFLOW_TRIGGER_GET

Dispara um workflow de API do Bubble via requisição HTTP GET. Workflows de API são workflows server-side do Bubble que podem ser acionados externamente. Use GET para workflows simples que não exigem corpo de requisição (parâmetros passados como query string). Para workflows que exigem dados complexos ou upload de arquivos, use a versão POST. Pré-requisitos: o workflow deve estar criado no editor de workflows do Bubble e marcado como Expose as a public API workflow. O app Bubble precisa ter acesso à API habilitado na assinatura.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`branch`	string	Não	Branch de deploy do Bubble a direcionar. Use `live` para workflows em produção ou `version-test` para workflows de desenvolvimento/teste.
`parameters`	object	Não	Parâmetros de query string a passar ao workflow, correspondendo aos inputs definidos no workflow. Cada chave deve bater com um nome de parâmetro configurado no seu workflow Bubble.
`workflow_name`	string	Sim	Nome do workflow de API a disparar (conforme definido no editor de workflows do Bubble). É o nome exato dado ao workflow, que compõe parte da URL do endpoint.

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.

Disparar workflow do Bubble via POST

BUBBLE_WORKFLOW_TRIGGER_POST

Dispara um workflow de API do Bubble pelo nome via requisição POST. Use essa ação para executar workflows de backend no seu aplicativo Bubble. O workflow deve estar configurado na seção API Workflows do app com Expose as public API workflow habilitado. Passe os parâmetros necessários como objeto JSON no campo parameters.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`branch`	string	Não	Branch de deploy a direcionar. Use `live` para ambiente de produção ou `version-test` para desenvolvimento/teste.
`parameters`	object	Não	Parâmetros em corpo JSON a passar ao workflow, correspondendo aos parâmetros de entrada configurados no workflow. Use formato ISO 8601 para datas (ex: `2024-01-15T10:30:00Z`) e IDs únicos (strings) para referências a Data Types do Bubble.
`workflow_name`	string	Sim	Nome amigável de URL do workflow de API do Bubble a disparar. É o nome que você configurou na seção API Workflows, convertido para minúsculas com hífens no lugar de espaços (ex: `send-email`, `process-payment`).

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.