API Externa Omniflow

A API externa permite integrar o Omniflow com automações, sistemas externos e scripts.

Como criar o access_token

Acesse a plataforma Omniflow e faça login.
Vá em Configurações (menu lateral) → API.
Clique em Criar API Key.
Selecione o canal (WhatsApp ou Instagram) ao qual a chave será vinculada.
Opcionalmente, informe um nome (ex.: Integração ERP).
Clique em Criar.
O access_token será exibido apenas uma vez. Copie e guarde em local seguro — não é possível recuperá-lo depois.

O token dá acesso apenas aos recursos do canal escolhido (contatos, conversas e envio de mensagens desse canal).

Escopo (regra imutável)

O access_token nunca deve acessar recursos fora da API externa.

Autenticação

Todas as requisições exigem o header:

Authorization: Bearer <seu_access_token>

O access_token é gerado ao criar uma API Key e só é exibido uma vez. Guarde-o em local seguro. O token não expira por tempo; só fica inválido se você revogar a API Key em Configurações.

Base URL: https://api.omniflow.chat (ou http://localhost:3001 em desenvolvimento)

Whitelabel

A API e sua base URL respeitam toda a lógica de Whitelabel. Em instalações com domínio customizado (ex.: api.seudominio.com), use a URL pública configurada para o seu tenant. A autenticação continua sendo Authorization: Bearer <access_token> independente do host.

Swagger

Use o Swagger abaixo para testar as rotas diretamente no navegador. Informe seu access_token em Authorize e escolha a rota desejada. Acesse o Swagger aqui.

Referência das rotas

Rotas GET (plataforma)

Listar contatos

GET /api/v1/contacts

Lista os contatos do tenant associados ao canal da sua API Key.

Query params:

Parâmetro	Tipo	Default	Descrição
page	integer	1	Página da listagem
limit	integer	50	Itens por página (máx. 100)

Exemplo (cURL):

bash

curl -X GET "https://api.omniflow.chat/api/v1/contacts?page=1&limit=20" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

Resposta (200):

json

{
  "data": {
    "data": [
      {
        "id": "uuid",
        "name": "João Silva",
        "phone": "5511999999999",
        "externalId": null,
        "email": "joao@email.com"
      }
    ],
    "total": 150,
    "page": 1,
    "limit": 20
  }
}

Listar conversas

GET /api/v1/conversations

Lista as conversas (sessões) do canal.

Query params:

Parâmetro	Tipo	Default	Descrição
page	integer	1	Página
limit	integer	50	Itens por página

Exemplo (cURL):

bash

curl -X GET "https://api.omniflow.chat/api/v1/conversations?page=1&limit=50" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

Listar mensagens de uma conversa

GET /api/v1/conversations/:id/messages

Lista as mensagens de uma conversa específica.

Path params:

Parâmetro	Tipo	Descrição
id	string	ID da conversa (UUID)

Exemplo (cURL):

bash

curl -X GET "https://api.omniflow.chat/api/v1/conversations/abc-123-uuid/messages" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

Listar grupos (WhatsApp)

GET /api/v1/groups

Lista os grupos do WhatsApp. Disponível apenas para canais WhatsApp conectados via Evolution API (QR Code). Funcional com Evolution: utiliza fetchAllGroups e retorna id (JID para envio), subject, size e owner.

Exemplo (cURL):

bash

curl -X GET "https://api.omniflow.chat/api/v1/groups" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

Resposta (200): array com id, subject, size, owner de cada grupo.

Rotas POST (envio 1:1)

O parâmetro to indica o destinatário: número de telefone (WhatsApp, ex: 5511999999999) ou IGSID (Instagram, ID do usuário).

Enviar texto

POST /api/v1/send/text

Body (JSON):

Campo	Tipo	Obrigatório	Descrição
to	string	Sim	Número (WhatsApp) ou IGSID (Instagram)
text	string	Sim	Conteúdo da mensagem

Exemplo (cURL):

bash

curl -X POST "https://api.omniflow.chat/api/v1/send/text" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": "5511999999999", "text": "Olá! Mensagem via API."}'

Enviar imagem

POST /api/v1/send/image

Body (JSON):

Campo	Tipo	Obrigatório	Descrição
to	string	Sim	Destinatário
image	string	Sim	Base64 da imagem ou URL pública (HTTPS)
caption	string	Não	Legenda da imagem

Exemplo (cURL):

bash

curl -X POST "https://api.omniflow.chat/api/v1/send/image" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "image": "https://exemplo.com/imagem.jpg",
    "caption": "Confira esta imagem!"
  }'

Enviar vídeo

POST /api/v1/send/video

Body (JSON):

Campo	Tipo	Obrigatório	Descrição
to	string	Sim	Destinatário
video	string	Sim	Base64 ou URL pública
caption	string	Não	Legenda

Exemplo (cURL):

bash

curl -X POST "https://api.omniflow.chat/api/v1/send/video" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": "5511999999999", "video": "BASE64_OU_URL", "caption": "Vídeo explicativo"}'

Enviar áudio

POST /api/v1/send/audio

Body (JSON):

Campo	Tipo	Obrigatório	Descrição
to	string	Sim	Destinatário
audio	string	Sim	Base64 ou URL do arquivo de áudio
asVoice	boolean	Não	Se `true`, envia como mensagem de voz (WhatsApp)

Exemplo (cURL):

bash

curl -X POST "https://api.omniflow.chat/api/v1/send/audio" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": "5511999999999", "audio": "BASE64_OU_URL", "asVoice": true}'

Enviar documento

POST /api/v1/send/document

Body (JSON):

Campo	Tipo	Obrigatório	Descrição
to	string	Sim	Destinatário
document	string	Sim	Base64 ou URL do arquivo
fileName	string	Não	Nome do arquivo (ex: `contrato.pdf`)
caption	string	Não	Legenda

Exemplo (cURL):

bash

curl -X POST "https://api.omniflow.chat/api/v1/send/document" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "document": "BASE64_OU_URL",
    "fileName": "relatorio.pdf",
    "caption": "Segue o documento solicitado."
  }'

Rotas POST (grupos — apenas WhatsApp)

O groupId é o JID do grupo retornado em GET /api/v1/groups (ex: 120363123456789@g.us).

Enviar texto para grupo

POST /api/v1/groups/:groupId/send/text

Path params: groupId — JID do grupo (ex: 120363123456789@g.us)

Body (JSON):

Campo	Tipo	Obrigatório	Descrição
text	string	Sim	Conteúdo da mensagem

Exemplo (cURL):

bash

curl -X POST "https://api.omniflow.chat/api/v1/groups/120363123456789@g.us/send/text" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Olá grupo! Mensagem via API."}'

Enviar imagem para grupo

POST /api/v1/groups/:groupId/send/image

Body (JSON):

Campo	Tipo	Obrigatório	Descrição
image	string	Sim	Base64 ou URL
caption	string	Não	Legenda

Exemplo (cURL):

bash

curl -X POST "https://api.omniflow.chat/api/v1/groups/120363123456789@g.us/send/image" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"image": "BASE64_OU_URL", "caption": "Imagem para o grupo"}'

Enviar arquivo para grupo

POST /api/v1/groups/:groupId/send/file

Body (JSON):

Campo	Tipo	Obrigatório	Descrição
file	string	Sim	Base64 ou URL do arquivo
fileName	string	Não	Nome do arquivo
caption	string	Não	Legenda

Exemplo (cURL):

bash

curl -X POST "https://api.omniflow.chat/api/v1/groups/120363123456789@g.us/send/file" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file": "BASE64_OU_URL", "fileName": "planilha.xlsx", "caption": "Arquivo em anexo"}'

Exemplos em outras linguagens

JavaScript (fetch)

javascript

const response = await fetch('https://api.omniflow.chat/api/v1/send/text', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SEU_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '5511999999999',
    text: 'Olá! Mensagem via API.',
  }),
});

Python

python

import requests

response = requests.post(
    'https://api.omniflow.chat/api/v1/send/text',
    headers={'Authorization': 'Bearer SEU_ACCESS_TOKEN', 'Content-Type': 'application/json'},
    json={'to': '5511999999999', 'text': 'Olá! Mensagem via API.'}
)

Especificação OpenAPI

A especificação completa está em openapi.json.

Swagger UI no backend: A URL é {BACKEND_PUBLIC_URL}/api/v1/docs (ex.: http://localhost:3001/api/v1/docs). Configure BACKEND_PUBLIC_URL no .env do backend.

Suporte

Para dúvidas sobre a API: suporte@omniflow.chat

API Externa Omniflow ​

Como criar o access_token ​

Autenticação ​

Swagger ​

Referência das rotas ​

Rotas GET (plataforma) ​

Listar contatos ​

Listar conversas ​

Listar mensagens de uma conversa ​

Listar grupos (WhatsApp) ​

Rotas POST (envio 1:1) ​

Enviar texto ​

Enviar imagem ​

Enviar vídeo ​

Enviar áudio ​

Enviar documento ​

Rotas POST (grupos — apenas WhatsApp) ​

Enviar texto para grupo ​

Enviar imagem para grupo ​

Enviar arquivo para grupo ​

Exemplos em outras linguagens ​

JavaScript (fetch) ​

Python ​

Especificação OpenAPI ​

Suporte ​

API Externa Omniflow

Como criar o access_token

Autenticação

Swagger

Referência das rotas

Rotas GET (plataforma)

Listar contatos

Listar conversas

Listar mensagens de uma conversa

Listar grupos (WhatsApp)

Rotas POST (envio 1:1)

Enviar texto

Enviar imagem

Enviar vídeo

Enviar áudio

Enviar documento

Rotas POST (grupos — apenas WhatsApp)

Enviar texto para grupo

Enviar imagem para grupo

Enviar arquivo para grupo

Exemplos em outras linguagens

JavaScript (fetch)

Python

Especificação OpenAPI

Suporte