Introdução à API

A API REST do Flowella permite-lhe enviar mensagens WhatsApp, gerir contactos e opt-outs, modelos de listas e de envio em massa e obter análises - de forma programática. Esta página cobre tudo o que precisa de saber antes de chamar um endpoint. A referência completa do ponto final encontra-se na barra lateral Referência API (gerada automaticamente a partir da OpenAPI spec).

URL base

https://api.flowella.io/v1

Todos os endpoints v1 vivem sob esta base canónica — por exemplo https://api.flowella.io/v1/messages.

Anteriormente a API estava no host da app em https://app.flowella.io/api/v1/.... Os pedidos a esse caminho legado são redirecionados permanentemente (308) para https://api.flowella.io/v1/..., preservando o método e o corpo — pelo que as integrações existentes continuam a funcionar. Atualize o seu URL base assim que possível para evitar o salto adicional.

Autenticação

Cada pedido necessita de uma chave API no cabeçalho Authorization:

Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx

As chaves têm um âmbito organizacional - actuam numa única organização Flowella e herdam as permissões de um Administrador nessa organização.

Trate as chaves como senhas. Nunca as submeta ao controlo da fonte, nunca as cole no chat ou em documentos partilhados, e rode-as quando os colegas de equipa deixam a organização. Veja Settings → API keys para os passos de rotação.

Criar uma chave

É necessário o papel de Proprietário ou Administrador para gerir as chaves da API.

Ir para Configurações → Chaves API na aplicação Flowella.
Clique em Criar chave e dê-lhe um nome memorável.
Copie a chave uma vez - ela é mostrada apenas no momento da criação.

Trate as chaves como palavras-passe: nunca as submeta ao controlo da fonte, nunca as cole no chat e rode-as quando os colegas de equipa deixarem a organização.

Verificando uma chave

Clique no endpoint ping para confirmar que uma chave é válida:

curl https://api.flowella.io/v1/ping \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"

await fetch("https://api.flowella.io/v1/ping", {
  headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` },
});

import os, requests

requests.get(
    "https://api.flowella.io/v1/ping",
    headers={"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}"},
)

Um 200 OK com { "ok": true, "organizationId": "…" } significa que está autenticado.

Erros

Todos os erros são devolvidos num envelope consistente:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Status HTTP	Quando você o verá
`400`	Falha na validação, corpo malformado ou rejeição Meta do upstream
`401`	Chave de API em falta ou inválida
`402`	Pagamento necessário - a sua subscrição não cobre a ação
`403`	Proibido - por exemplo, enviar para um contacto excluído, ou o Meta não está ligado
`404`	O canal ou recurso solicitado não existe
`429`	Taxa limitada - abrandar

O campo error.code é estável e seguro para ser ativado programaticamente. O error.message é legível por humanos e pode mudar.

Limites de taxa

As chaves de API têm um limite de taxa por organização. Se exceder o limite, receberá um 429 com o código RATE_LIMITED e a mensagem Too many requests. Quando presente, o cabeçalho de resposta Retry-After indica quantos segundos deve esperar. Recue e tente novamente com um atraso exponencial. Se estiver a executar grandes envios em massa, prefira POST /v1/templates/send com o parâmetro throttlePerHour - o Flowella impõe o estrangulamento do lado do servidor, pelo que não precisa de acelerar os pedidos.

Chaves de idempotência

Os envios de modelos em massa são assíncronos. O POST /v1/templates/send valida o pedido, coloca-o numa fila de forma durável e devolve imediatamente 202 Accepted:

{
  "id": "v1ts-0123456789abcdef",
  "status": "accepted"
}

O Flowella entrega o lote em segundo plano e repete automaticamente os erros temporários do WhatsApp. Os destinatários são processados individualmente, pelo que um número inválido não bloqueia o resto do lote. Acompanhe o progresso da entrega no separador Estatísticas do modelo na aplicação. Como a entrega acontece depois da resposta, as novas tentativas precisam de ser seguras. Passe um cabeçalho Idempotency-Key (até 200 caracteres) que identifique de forma única cada lote:

curl -X POST "https://api.flowella.io/v1/templates/send" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: campaign-2026-08-31-launch" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "recipients": [{ "phone": "+15551234567" }]
  }'

As repetições da mesma chave no prazo de sete dias devolvem o id da tarefa original em vez de criarem um novo envio. Pode repetir um pedido em segurança após um timeout ou erro de rede sem enviar mensagens a ninguém duas vezes. Se omitir o cabeçalho, o Flowella deriva uma chave a partir do corpo do pedido. Um lote idêntico submetido duas vezes em rápida sucessão não é, portanto, enviado em duplicado. Uma chave explícita é ainda mais segura, porque qualquer alteração ao corpo (mesmo reordenar os destinatários) produz uma nova chave derivada.

Paginação

Os endpoints de lista (/conversations, /contacts, /templates) utilizam paginação de cursor:

Passar limit (1-100, predefinição 25) e um cursor opcional.
A resposta contém items e, quando há mais resultados, um nextCursor.
Passar nextCursor de volta como o parâmetro cursor para buscar a próxima página.
Quando o nextCursor estiver ausente, o utilizador chegou ao fim.

curl "https://api.flowella.io/v1/conversations?limit=50" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"

Data e hora

Todos os carimbos de data/hora são cadeias de caracteres ISO 8601 em UTC (por exemplo, 2025-01-15T14:30:00.000Z). Nos casos em que a API aceita datas, tanto a data apenas (2025-01-15) como o ISO 8601 completo são coagidos do lado do servidor.

Números de telefone

Passe números de telefone no formato E.164 (+15551234567) sempre que possível. O Flowella normalizará as variações comuns do lado do servidor, mas o E.164 é mais seguro.

Canais

Muitos endpoints aceitam um whatsappChannelId. Se a sua organização tiver um único canal e o omitir, o Flowella utiliza o seu canal predefinido. Se tiver vários canais, passe o ID explicitamente para evitar enviar do remetente errado. Para o padrão URL completo e troca de canal, veja Multi-channel.

OpenAPI spec

A especificação legível por máquina está em:

/api-reference/openapi.json

Coloque-a no Postman, Insomnia, ou no seu gerador de código de eleição.

Construindo uma integração? Emparelhe esta página com Webhooks para reagir a eventos em vez de sondar o estado.

Primeiros passos

Registro de alterações

Essenciais

Usar a aplicação

Definições

Configuração Meta e WhatsApp

Integração HubSpot

Flows e campanhas

Conta e início de sessão

Segurança e privacidade

Referência da API

Resolução de problemas

Introdução à API

URL base

Autenticação

Criar uma chave

Verificando uma chave

Erros

Limites de taxa

Chaves de idempotência

Paginação

Data e hora

Números de telefone

Canais

OpenAPI spec

​URL base

​Autenticação

​Criar uma chave

​Verificando uma chave

​Erros

​Limites de taxa

​Chaves de idempotência

​Paginação

​Data e hora

​Números de telefone

​Canais

​OpenAPI spec

URL base

Autenticação

Criar uma chave

Verificando uma chave

Erros

Limites de taxa

Chaves de idempotência

Paginação

Data e hora

Números de telefone

Canais

OpenAPI spec