PlugSend API - Guia de Integração com Bubble

📱 + 🫧

PlugSend API + Bubble

Guia completo para enviar mensagens WhatsApp pelo Bubble usando o API Connector

Passo a Passo para Iniciantes

📑 Índice do Guia

Navegação Rápida

01 Resumo da API (o que você precisa saber) 02 Instalar o plugin API Connector ⚡ ATALHO: Importar via cURL (pula o passo 3) 03 Configurar a chamada de API (manual) 04 Testar direto no editor (Initialize) 05 Criar o Workflow para enviar 06 Montar a tela com formulário 07 Usar dados dinâmicos do banco 08 Erros comuns e soluções

Fundamentos

📡 1. Resumo da API PlugSend

Antes de configurar qualquer coisa no Bubble, entenda o que a API precisa receber:

POST https://plugsend.uazapi.com/send/text

Headers (Cabeçalhos)

Header	Valor
Content-Type	application/json
token	Seu token da API PlugSend

Body (Corpo da Requisição)

Campo	Descrição	Status
number	Número no formato internacional, apenas números (ex: 5511999999999)	Obrigatório
text	Mensagem que será enviada ao contato	Obrigatório
linkPreview	Mostrar pré-visualização de links (true/false)	Opcional

⚠️ Regra de Ouro do Número:
• Use apenas números — sem espaços, traços, parênteses ou +
• Formato correto: 5511999999999
• Formato errado: +55 (11) 99999-9999
• No Bubble, use o operador :find & replace para limpar (ensinamos abaixo)

Passo a Passo

🔌 2. Instalar o Plugin API Connector

O API Connector é o plugin oficial do Bubble para conectar APIs externas. Ele já vem gratuito.

1 Abra seu app no Bubble Editor

Acesse bubble.io e abra o projeto onde quer enviar mensagens.

2 Vá em Plugins

No menu lateral esquerdo, clique em Plugins (ícone de quebra-cabeça 🧩).

3 Clique em "+ Add plugins"

Botão azul no canto superior direito da tela de plugins.

4 Pesquise "API Connector"

Digite API Connector na busca. É o primeiro resultado — do próprio Bubble. Clique em "Install".

💡 Já tem instalado? Se você já vê "API Connector" na sua lista de plugins, pule direto para o passo 3.

⚡ Atalho Rápido

🚀 Importar via cURL — Configuração em 30 segundos

O Bubble tem uma função escondida que importa um cURL pronto e preenche tudo automaticamente — URL, headers, body, método. Você pula toda a configuração manual da seção 3.

Como usar:

1 Abra o API Connector

Vá em Plugins → API Connector e clique em "Add another API".

2 Clique em "Import from cURL"

Dentro da API que você criou, clique em "expand" na chamada e procure o link azul "import from cURL" (fica ao lado do nome da chamada, no canto direito). Vai abrir uma caixa de texto.

3 Copie e cole o cURL abaixo

Copie o comando inteiro e cole na caixa que apareceu. Clique em "Import".

cURL — Enviar Mensagem de Texto

curl -X POST https://plugsend.uazapi.com/send/text \
  -H "Content-Type: application/json" \
  -H "token: SEU_TOKEN_AQUI" \
  -d '{
    "number": "5511999999999",
    "text": "Teste PlugSend via Bubble!",
    "linkPreview": true
  }'

4 Após importar — ajustes obrigatórios

O Bubble vai preencher tudo automaticamente, mas você precisa ajustar 4 coisas:

① Troque o token: No header token, substitua SEU_TOKEN_AQUI pelo seu token real da PlugSend. Dica: mova o header token para "Shared headers" para não precisar repetir em outras chamadas.
② Mude "Use as" para Action: O Bubble importa como "Data" por padrão. Mude para "Action" para poder usar em Workflows.
③ Torne os parâmetros dinâmicos: No body, troque os valores fixos por parâmetros dinâmicos do Bubble:

Antes (fixo) "number": "5511999999999"

Depois (dinâmico) "number": "<number>"

Antes (fixo) "text": "Teste PlugSend via Bubble!"

Depois (dinâmico) "text": "<text>"
④ Desmarque "Private": Nos parâmetros number e text que vão aparecer, desmarque a checkbox "Private" para poder preenchê-los no Workflow.

5 Initialize e Salve

Preencha valores de teste nos parâmetros (um número real e uma mensagem) → Clique em "Initialize call" → Se tudo der certo, clique em "SAVE". Pronto! Pule para a seção 5 (Workflow).

💡 Body JSON final (após os ajustes do passo 4):

{"number": "<number>", "text": "<text>", "linkPreview": true}

Se após importar o body vier como form-data, mude o "Body type" para JSON e cole o JSON acima manualmente.

OU CONFIGURE MANUALMENTE ↓

Parte Principal

⚙️ 3. Configurar a Chamada de API

Aqui é onde a mágica acontece. Vamos preencher campo por campo.

1 Abra o API Connector

Em Plugins → API Connector, clique em "Add another API" (botão azul).

2 Dê um nome para a API

No campo "API Name", digite:
PlugSend - WhatsApp

Esse nome é apenas para você se organizar. Pode ser qualquer nome.

3 Configurar Autenticação (Shared Headers)

Logo abaixo do nome da API, você verá a seção "Shared headers". Aqui configuramos o token que será enviado em TODAS as chamadas dessa API.

Clique em "Add shared header" e preencha:

Key token

Value SEU_TOKEN_PLUGSEND_AQUI

⚠️ Onde pego meu token?
O token é fornecido pela PlugSend quando você cria sua instância. Se ainda não tem, entre em contato com o suporte da PlugSend para obter o seu.

4 Expandir/Criar a Chamada (API Call)

Clique em "Add another API call" ou no botão "expand" da chamada que já apareceu automaticamente. Agora vamos preencher os campos da chamada:

5 Preencher os campos da chamada

Preencha EXATAMENTE assim:

Name Enviar Texto

Use as Action

Method POST

URL https://plugsend.uazapi.com/send/text

🚨 IMPORTANTÍSSIMO — "Use as"
Selecione "Action" no dropdown "Use as". Se você deixar como "Data" (que é o padrão), não vai conseguir usar essa chamada nos Workflows. Action = pode usar em Workflows. Data = só para buscar dados.

6 Headers da chamada

Na seção "Headers" da chamada, adicione:

Key Content-Type

Value application/json

💡 Nota: O header token já está nos "Shared headers" (passo 3). Não precisa repetir aqui. Ele será enviado automaticamente em todas as chamadas.

7 Configurar o Body (Corpo)

Este é o passo mais importante! Marque a opção "Body type" como "JSON".

No campo do body, cole exatamente este JSON:

{
  "number": "<number>",
  "text": "<text>",
  "linkPreview": true
}

⚠️ Os sinais < > são parâmetros dinâmicos!

No Bubble, quando você escreve <number> dentro do body JSON, o Bubble entende que isso é um parâmetro dinâmico — ou seja, um valor que você vai preencher depois no Workflow.

Ao colar o JSON acima, o Bubble vai automaticamente criar dois campos de parâmetro abaixo: number e text. Eles aparecerão como inputs que você pode preencher.

8 Configurar os Parâmetros

Após colar o body, os parâmetros vão aparecer abaixo. Configure-os assim:

number Desmarque "Private" ✅

(valor de teste) 5511999999999

text Desmarque "Private" ✅

(valor de teste) Teste PlugSend via Bubble

🚨 Desmarcar "Private" — POR QUÊ?
Se o parâmetro ficar marcado como Private, o valor fica fixo e você NÃO consegue alterá-lo no Workflow. Desmarque para que esses valores sejam dinâmicos (preenchidos em cada envio).

👁️ Visão Geral — Como fica no editor:

API Connector — PlugSend - WhatsApp → Enviar Texto

API Name PlugSend - WhatsApp

Name Enviar Texto

Use as Action

Method POST

URL https://plugsend.uazapi.com/send/text

Header: token (shared) ••••••••••

Header Content-Type: application/json

Body type JSON

Body {"number":"<number>","text":"<text>","linkPreview":true}

Param: number 5511999999999 (unchecked Private)

Param: text Teste PlugSend via Bubble (unchecked Private)

Validação

🧪 4. Testar a Chamada (Initialize Call)

Antes de usar em produção, teste direto no editor do Bubble.

1 Preencha os valores de teste

Nos campos de parâmetro:
• number: coloque um número real de teste (ex: 5511999999999)
• text: coloque uma mensagem de teste (ex: Teste via Bubble!)

2 Clique em "Initialize call"

É o botão azul no final da configuração da chamada. O Bubble vai fazer a requisição real para a API.

3 Verifique o resultado

Se deu certo: Vai aparecer o retorno da API com status de sucesso e o número de teste vai receber a mensagem no WhatsApp!

Se deu erro: Veja a seção de Erros Comuns no final deste guia.

💡 O Initialize é obrigatório!
O Bubble precisa "conhecer" a estrutura de resposta da API para funcionar. Se você pular o Initialize, a chamada não vai funcionar nos Workflows. Sempre inicialize antes de usar.

4 Clique em "SAVE"

Após o Initialize funcionar, clique em SAVE para salvar toda a configuração. Pronto, a parte do plugin está feita!

Usar no App

⚡ 5. Criar o Workflow para Enviar Mensagem

Agora vamos conectar a API a um botão no seu app. É aqui que o usuário clica e a mensagem é enviada.

1 Crie um botão na sua página

Na aba Design, arraste um Button para a página e nomeie como Botão Enviar WhatsApp.

2 Abra o Workflow do botão

Clique no botão → aba Workflow → ou clique com botão direito → "Start/Edit workflow".

3 Adicione a Action da API

No Workflow, clique em "Click here to add an action" → Procure por:

Plugins → PlugSend - WhatsApp - Enviar Texto

(O nome vai variar conforme o que você digitou no passo 3.2 e 3.5)

4 Preencha os parâmetros dinâmicos

Ao selecionar a action, dois campos aparecem:

(body) number Input Numero's value

(body) text Input Mensagem's value

Ou seja: você conecta os campos do formulário diretamente aos parâmetros da API.

💡 Dica Pro — Limpar o número no Workflow:
Para remover caracteres especiais do número, use o operador :find & replace do Bubble no campo number:

Input Numero's value :find & replace
→ Find: [^0-9]
→ Replace by: (vazio)
→ Marque "This is a regex pattern" ✅

Isso remove tudo que não for número, igual ao replace(/\D/g, "") do JavaScript.

Interface

🖼️ 6. Montar a Tela com Formulário

Monte uma tela simples para testar ou usar em produção:

Elementos necessários:

Input A Número do WhatsApp Placeholder: 5511999999999

Input B Mensagem Tipo: Multiline Input

Botão Enviar WhatsApp

💡 Feedback visual:
Adicione um Alert ou Text que mostre "Mensagem enviada!" após o envio. No Workflow, após a action da API, adicione "Show an alert" com a mensagem de sucesso.

Avançado

🔄 7. Usar Dados Dinâmicos do Banco

No mundo real, você não vai digitar o número manualmente — vai puxar do banco de dados do Bubble.

Exemplo: Enviar mensagem para um cliente salvo no banco

1 Suponha que você tem uma tabela "Clientes"

Com os campos: nome, telefone, email

2 No Workflow, preencha assim:

(body) number Current cell's Cliente's telefone :find & replace ([^0-9] → vazio, regex)

(body) text Olá Current cell's Cliente's nome! Sua consulta foi confirmada.

3 Mensagem dinâmica com variáveis

No campo text, misture texto fixo com dados dinâmicos:

Olá [insert dynamic: Cliente's nome]! Seu pedido #[insert dynamic: Pedido's numero] foi confirmado. Valor: R$ [insert dynamic: Pedido's valor]

⚠️ Lembre-se do :find & replace no número!
Mesmo puxando do banco de dados, sempre aplique a limpeza regex no campo do telefone para garantir que apenas números sejam enviados à API.

Troubleshooting

🔧 8. Erros Comuns e Soluções

! Erro 401 — Token inválido

Causa: O token não foi enviado ou está incorreto.
Solução: Verifique se o header token está nos Shared Headers e se o valor está correto (copie e cole diretamente, sem espaços extras).

! Erro 400 — Número inválido

Causa: O número contém caracteres não numéricos (+, espaços, parênteses).
Solução: Aplique o :find & replace com regex [^0-9] antes de enviar. Verifique que o número tem o formato 5511999999999.

! A chamada não aparece no Workflow

Causa: O campo "Use as" está como "Data" em vez de "Action".
Solução: Volte em Plugins → API Connector, mude "Use as" para "Action", clique em Initialize call novamente e salve.

! Os parâmetros não são dinâmicos no Workflow

Causa: Os parâmetros estão marcados como "Private".
Solução: Desmarque a checkbox "Private" nos parâmetros number e text.

! Erro "Plugin Action Error" ou "Invalid JSON"

Causa: O body JSON tem formato incorreto.
Solução: Verifique que:
• O body type está como JSON (não form-data ou raw)
• Não há vírgulas extras ou aspas faltando
• Os parâmetros estão entre < > corretamente

? Mensagem enviada mas não chegou

Possíveis causas:
• O número não tem WhatsApp ativo
• Sua instância PlugSend desconectou — verifique o status no painel
• O número está bloqueado ou com privacidade restrita

📋 Resumo Rápido — Checklist Final

✅ Plugin API Connector instalado

✅ API Name PlugSend - WhatsApp

✅ Shared Header token → seu_token_aqui

✅ Call Name Enviar Texto

✅ Use as Action (NÃO Data)

✅ Method POST

✅ URL https://plugsend.uazapi.com/send/text

✅ Header Content-Type: application/json

✅ Body JSON com <number> e <text>

✅ Private Desmarcado nos dois parâmetros

✅ Initialize Executado com sucesso

✅ Regex :find & replace [^0-9] no número

📦 Body JSON para Copiar e Colar

Copie este JSON e cole no campo "Body" do API Connector:

{
  "number": "<number>",
  "text": "<text>",
  "linkPreview": true
}

💡 Versão texto limpo para colar:
{"number": "<number>", "text": "<text>", "linkPreview": true}