Início rápido

Crie uma conta e gere uma chave em Chaves de API.
Crie uma instância e escaneie o QR code com o número que vai enviar.
Aponte sua integração para https://api.omensageiro.online com o header apikey.

curl -X POST https://api.omensageiro.online/message/sendText/minha-instancia \  -H "apikey: om_SUA_CHAVE" \  -H "content-type: application/json" \  -d '{"number":"5511999999999","text":"Olá!"}'

Você pode testar sem escrever código na área Testar envio do painel.

Autenticação

Toda chamada leva o header apikey com uma chave om_…. A chave identifica a sua conta; instâncias de outras contas não são visíveis nem acessíveis. Chaves podem ser revogadas a qualquer momento no painel e ficam guardadas cifradas: só o dono da conta pode revê-las no painel.

Instâncias e QR code

O nome que você dá à instância vira o identificador usado na API, e ele pertence à sua conta. Nomes comuns comovendas ou suporte podem existir em várias contas ao mesmo tempo sem nenhum conflito: a chave de API diz de quem é a chamada, e /message/sendText/vendas só alcança a instância da conta dona da chave. Dentro da sua conta, porém, o nome é único.

Rota	O que faz
`POST /instance/create`	cria a instância (`instanceName` vira um slug); aceita `webhook.url` e `webhook.events`; devolve o QR em base64 e o `webhook.secret`
`GET /instance/connect/:nome`	novo QR code (expira em ~40 s; chame de novo se precisar)
`GET /instance/connectionState/:nome`	`open` conectada · `connecting` · `close`
`GET /instance/fetchInstances`	lista as suas instâncias com status e número
`DELETE /instance/logout/:nome`	desconecta o número (mantém a instância)
`DELETE /instance/delete/:nome`	remove a instância
`GET /instance/webhook/:nome`	URL e eventos do webhook da instância
`POST /instance/webhook/:nome`	troca a URL e os eventos; envie `{"url": null}` para desligar

Enviar mensagens

Mesmas rotas da Evolution: /message/sendText, sendMedia, sendWhatsAppAudio, sendLocation, sendContact, sendList, sendButtons, sempre seguidas de /:nome-da-instancia. O número vai só com dígitos, com DDI: 5511999999999.

# imagem por URLPOST /message/sendMedia/minha-instancia{ "number": "5511999999999", "mediatype": "image", "media": "https://exemplo.com/foto.jpg", "caption": "Chegou!" } # áudio como se fosse gravado na hora (arquivo .ogg/opus)POST /message/sendWhatsAppAudio/minha-instancia{ "number": "5511999999999", "audio": "https://exemplo.com/audio.ogg" }

Se o motor estiver em manutenção, a resposta é 202 com {"queued":true,"queueId":"…"}: a mensagem foi aceita e sai automaticamente quando o motor voltar. Você recebe send.message no webhook quando isso acontecer.

Webhooks assinados

Cada evento é um POST JSON na URL da instância com estes headers:

x-omensageiro-event — messages.upsert, messages.update, send.message, connection.update, qrcode.updated, call
x-omensageiro-delivery — id único da entrega (use para idempotência)
x-omensageiro-timestamp — unix time
x-omensageiro-signature — sha256=HMAC_SHA256(secret, timestamp + "." + body)

// Node.js — validar a assinaturaimport { createHmac, timingSafeEqual } from 'node:crypto';const expected = 'sha256=' + createHmac('sha256', SECRET).update(ts + '.' + rawBody).digest('hex');const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-omensageiro-signature']));

Responda 2xx em até 10 segundos. Entregas com falha são reenviadas com backoff exponencial até o limite do seu plano. No painel, em Testar webhook, você dispara um evento de teste e vê a resposta do seu endpoint.

A URL precisa ser pública: destinos internos (localhost, faixas privadas, endereços de metadados da nuvem) são recusados na hora do cadastro e revalidados a cada entrega. Redirecionamentos não são seguidos; informe a URL final.

# trocar a URL do webhook de uma instânciacurl -X POST https://api.omensageiro.online/instance/webhook/vendas \  -H "apikey: $OM_API_KEY" \  -H "content-type: application/json" \  -d '{"url":"https://app.seudominio.com.br/webhooks/whatsapp","events":["messages.upsert","send.message"]}'

Códigos de resposta

Código	Significado
`201`	mensagem aceita pelo motor (campo `key.id`)
`202`	enfileirada: motor em manutenção, sai depois
`401`	chave ausente ou inválida
`402`	limite do plano ou da conta (instâncias ou mensagens/dia)
`403`	conta suspensa
`404`	instância não encontrada nesta conta
`409`	instância sem número conectado (`instance_not_connected`): escaneie o QR code antes de enviar
`423`	envio pausado pelo administrador
`429`	requisições por minuto excedidas (veja `x-ratelimit-*`)
`503`	motor em manutenção (rotas de instância)

Compatibilidade com Evolution API

Rotas, payloads e eventos seguem a documentação oficial da Evolution API v2. Diferenças: o nome da instância é o slug do painel; /proxy/* e /webhook/* são bloqueadas (proxy e webhook do motor são geridos pela plataforma; use /instance/webhook/:nome); /instance/create aplica a quota do plano e configura proxy e webhook automaticamente.

n8n, Typebot e Chatwoot

Use o nó ou integração "Evolution API" apontando para https://api.omensageiro.online com a sua chave om_…. O nome da instância é o slug que aparece no painel. Nada mais muda.

Limites e planos

Cada plano define instâncias, mensagens por dia e requisições por minuto. Os headers x-ratelimit-limit e x-ratelimit-remaining acompanham toda resposta. Veja os valores em Planos e o consumo do dia em Painel.

Boas práticas para não ser banido

Aqueça números novos: poucas conversas por dia na primeira semana, aumentando aos poucos.
Personalize mensagens e responda quem escreve; taxa alta de bloqueio derruba o número.
Ofereça saída ("responda SAIR") e respeite-a.
Prefira responder conversas abertas a iniciar contato frio.

Detalhes na política de uso aceitável.

Sobre o motor

Este serviço utiliza a Evolution API (Apache 2.0) como motor de conexão ao WhatsApp, por protocolo não oficial. O estado do motor é público na página de status.

API do OMensageiro