Saltar para o conteúdo
OmniMessage

API de gateway de mensagens

Uma só API para todos os canais de mensagens

Envie mensagens de WhatsApp Business, SMS, Telegram, Messenger, Instagram e TikTok através de um único endpoint REST. Pré-pago, com cobrança por mensagem de saída, webhooks de entrega e modo de teste.

Obter uma chave de APILer a documentação
Desde
0,0003 $
por mensagem de saída
Ao registar-se
100
mensagens gratuitas
Compromisso
Nenhum
pré-pago, sem contrato
curl https://api.omnimessage.co/v1/messages \
  -H "Authorization: Bearer om_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{
    "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
    "to": "+971501234567",
    "type": "text",
    "text": { "body": "Your order #1042 has shipped." },
    "reference": "order-1042"
  }'
202 Accepted
{
  "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ",
  "object": "message",
  "mode": "live",
  "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "channel_type": "whatsapp",
  "direction": "outbound",
  "to": "+971501234567",
  "from": "+971800123456",
  "type": "text",
  "content": {
    "text": { "body": "Your order #1042 has shipped." }
  },
  "status": "queued",
  "error": null,
  "reference": "order-1042",
  "metadata": {},
  "billing": {
    "source": "wallet",
    "amount_micros": 1000,
    "package_grant_id": null,
    "refunded": false
  },
  "created_at": "2026-10-05T09:30:00.000Z",
  "sent_at": null,
  "delivered_at": null,
  "read_at": null,
  "failed_at": null
}
  • Tipos de canal7 atrás de um só endpoint
  • Tipos de mensagem9, do texto às listas interativas
  • Preço desde0,0003 $ por mensagem de saída
  • Limite de pedidos100 pedidos por segundo por chave
  • Tamanho do loteAté 100 mensagens por pedido
  • Novas tentativas de webhook8, com backoff de 30 segundos a 24 horas
  • Janela de idempotência24 horas
  • Modo de testeGratuito, sem necessidade de canal
  • Mensagens falhadasReembolsadas automaticamente
  • Mensagens de entradaGratuitas

Canais

Sete tipos de canal, um só formato de pedido

Ligue os remetentes que já são seus. Cada um passa a ser um ID de canal que envia para o mesmo endpoint, e todos devolvem os mesmos estados.

Comparar canais

Como funciona

Do registo a uma mensagem entregue em quatro passos

Não há chamadas comerciais nem compromisso mínimo. Pode fazer a sua primeira chamada à API em modo de teste um minuto depois de criar a conta.

  1. Passo 01

    Crie uma conta

    Registe-se, verifique o seu e-mail e crie uma chave de API na consola. As chaves de teste funcionam de imediato, antes de qualquer canal estar ligado.

  2. Passo 02

    Ligue um canal

    Inicie sessão com o Facebook ou o TikTok na consola para ligar um número de WhatsApp, uma Página ou uma conta empresarial. Adicione um bot de Telegram ou um número da Twilio com as respetivas credenciais, na consola ou com POST /v1/channels.

  3. Passo 03

    Envie através de um só endpoint

    POST /v1/messages recebe um ID de canal, um destinatário e um objeto de conteúdo tipado. O formato do pedido é o mesmo em todos os canais.

  4. Passo 04

    Acompanhe cada entrega

    Os webhooks assinados comunicam os estados enviada, entregue, lida e falhada. O mesmo histórico está na consola e em GET /v1/messages.

Tipos de mensagem

O que envia é o que eles veem

Cada mensagem tem um tipo e um objeto de conteúdo sob a chave desse tipo. Escolha um para ver o corpo do pedido ao lado da mensagem que ele produz.

Todos os tipos de mensagem
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "text",
  "text": {
    "body": "A sua encomenda n.º 1042 foi expedida. Acompanhe-a em https://example.com/t/1042",
    "preview_url": true
  },
  "reference": "order-1042"
}

Texto simples, aceite por todos os tipos de canal. Defina preview_url para permitir que o canal apresente uma pré-visualização da ligação.

CanaisWhatsApp Business, SMS, SMS OTP, Telegram, Messenger, Instagram e TikTok

Consola

Uma consola para as partes que não são código

Crie chaves, ligue canais, pesquise o registo de mensagens, repita entregas de webhooks e faça a gestão da faturação. Tudo o que a consola mostra está também disponível através da API.

Visão geral. Saldo da carteira, créditos de pacotes restantes e volume de saída dos últimos 30 dias, por conta e por modo. Os ecrãs desta página são apresentados com dados de exemplo.
Registo de mensagens. Filtre por canal, estado, destinatário ou pela sua própria referência, e abra qualquer mensagem para ver o histórico de estados e o que foi cobrado por ela.
Faturação. Carregue a carteira, compre pacotes, defina o carregamento automático e descarregue recibos. Os créditos de pacotes mostram o que resta e quando expira.

Preços

Pague por mensagem ou compre mensagens em volume

Carregue uma carteira pré-paga a partir de 10 $ e pague o preço por mensagem de cada canal, ou compre um pacote de créditos de mensagens para ter volume nos seus canais mais caros.

Todos os preços

10 mil mensagens

8 $

0,0008 $ por mensagem

  • 10 000 mensagens de saída
  • Válido durante 3 meses a contar da compra
  • Válido em todos os tipos de canal
Começar com 10 mil

100 mil mensagens

Em destaque

60 $

0,0006 $ por mensagem

  • 100 000 mensagens de saída
  • Válido durante 6 meses a contar da compra
  • Válido em todos os tipos de canal
Começar com 100 mil

1 M mensagens

400 $

0,0004 $ por mensagem

  • 1 000 000 mensagens de saída
  • Válido durante 12 meses a contar da compra
  • Válido em todos os tipos de canal
Começar com 1 M

Pagamento por utilização

Preço por utilização, por mensagem de saída e por tipo de canal, em dólares dos EUA
CanalPor mensagem
WhatsApp Business0,001 $
Telegram0,0003 $
SMS0,0005 $
SMS OTP0,0005 $
Messenger0,0005 $
Instagram0,0005 $
TikTok0,0005 $

O que o preço inclui

  • CobradoMensagens de saída aceites pela API, no momento em que são aceites.
  • GratuitoMensagens de entrada, mensagens em modo de teste, webhooks e a consola.
  • ReembolsadoQualquer mensagem que termine como falhada, devolvida ao pacote ou à carteira de onde saiu.
  • À parteTaxas que a Meta, os operadores ou outros fornecedores cobram pelo próprio canal.

Experiência de programação

Feito para integrar uma vez e não voltar a mexer

Webhooks assinados, novas tentativas seguras, uma sandbox que se comporta como a produção e erros que o seu código consegue distinguir.

Referência da API

Webhooks que pode verificar

Cada entrega é assinada com HMAC-SHA256 sobre o carimbo de data/hora e o corpo em bruto, no cabeçalho OmniMessage-Signature. Responda com qualquer 2xx em 10 segundos. As entregas falhadas são repetidas oito vezes com backoff, de 30 segundos até 24 horas.

verify-signature.js
import { createHmac, timingSafeEqual } from 'node:crypto';

// header is "t=<unix seconds>,v1=<hex hmac-sha256>"
export function verifySignature(rawBody, header, secret) {
  const parts = header.split(',').map((part) => part.split('='));
  const { t, v1 = '' } = Object.fromEntries(parts);

  const expected = createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  const matches =
    v1.length === expected.length &&
    timingSafeEqual(Buffer.from(v1), Buffer.from(expected));

  return fresh && matches;
}
Evento message.delivered
{
  "id": "evt_8Kd2pQ7wN4xB1zR6mT3c",
  "object": "event",
  "type": "message.delivered",
  "mode": "live",
  "created_at": "2026-10-05T09:30:02.900Z",
  "data": {
    "object": {
      "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ",
      "object": "message",
      "status": "delivered",
      "reference": "order-1042",
      "delivered_at": "2026-10-05T09:30:02.871Z"
    }
  }
}

Um modo de teste que não custa nada

As chaves de teste utilizam canais de sandbox incorporados, pelo que não há nada para ligar. Os últimos dígitos do destinatário determinam o resultado simulado, e os seus webhooks são disparados tal como seriam em produção.

Pedido de sandbox, termina como lida
curl https://api.omnimessage.co/v1/messages \
  -H "Authorization: Bearer om_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "ch_test_whatsapp",
    "to": "+971501230002",
    "type": "text",
    "text": { "body": "Hello from the sandbox" }
  }'

Erros com um tipo e um código

Todas as respostas que não sejam 2xx têm o mesmo corpo: um type para a classe da falha, um code estável para o seu código distinguir, o param em causa quando existe e um request_id para o suporte.

402 Payment Required
{
  "error": {
    "type": "billing_error",
    "code": "insufficient_balance",
    "message": "Not enough wallet balance or package credits.",
    "request_id": "req_5Vn1cH8jL3qW6yD9sF2k",
    "doc_url": "https://omnimessage.co/docs/errors#insufficient_balance"
  }
}

  • POST idempotentes

    Envie um cabeçalho Idempotency-Key e uma nova tentativa nas 24 horas seguintes devolve a resposta guardada com Idempotent-Replayed: true, sem enviar nem cobrar duas vezes.

  • Limites previsíveis

    100 pedidos por segundo por chave em POST /v1/messages, 20 nos restantes. Todas as respostas incluem RateLimit-Remaining, e um 429 inclui Retry-After.

  • Envio em lote

    POST /v1/messages/batch aceita até 100 mensagens. Cada item é aceite, rejeitado e cobrado individualmente, e a resposta 207 indica-os por índice.

  • Chaves com âmbitos

    Dê a cada chave apenas os âmbitos de que precisa, como messages:write ou billing:read, e restrinja-a a uma lista de endereços IP permitidos.

Perguntas

Antes de integrar

As respostas curtas. As longas estão na documentação.

Preciso de ter o meu próprio número de WhatsApp, bot ou número de SMS?

Sim. A OmniMessage é um gateway para o qual traz os seus próprios canais: liga o seu número da WhatsApp Cloud API, o seu bot de Telegram, o seu número da Twilio ou a sua conta de rede social, e continua a ser o titular. A página de canais indica o que cada tipo exige.

O que me é cobrado, exatamente?

Uma cobrança por cada mensagem de saída que a API aceita: um crédito de pacote, se tiver algum; caso contrário, o preço por mensagem do tipo de canal, debitado da carteira. As mensagens de entrada e as mensagens em modo de teste são gratuitas, e uma mensagem que termine como falhada é reembolsada automaticamente.

As taxas da Meta, dos operadores ou dos fornecedores estão incluídas?

Não. A taxa do gateway cobre a API, o acompanhamento das entregas, os webhooks e a consola. As taxas que a Meta, a Twilio ou outro fornecedor cobram pelo próprio canal ficam entre si e esse fornecedor.

Como posso testar sem enviar mensagens reais?

Utilize uma chave que comece por om_test_. Cada conta tem um canal de sandbox por tipo, como ch_test_whatsapp. Nada é entregue nem cobrado e os estados são simulados: um destinatário terminado em 0000 falha, em 0001 fica como enviada, em 0002 é também lida, e qualquer outro é entregue em cerca de dois segundos.

O que acontece quando o meu saldo acaba?

A API responde 402 insufficient_balance e nada é colocado em fila, pelo que nunca fica a dever dinheiro a posteriori. Pode subscrever o evento balance.low ou ativar o carregamento automático para carregar a carteira quando esta descer abaixo de um limiar à sua escolha.

Preciso de um SDK?

Não. A API é JSON sobre HTTPS com autenticação bearer, pelo que qualquer cliente HTTP serve. A documentação tem exemplos em cURL, Node, Python e PHP.

Envie hoje a sua primeira mensagem em modo de teste

Crie uma conta, copie uma chave de teste e chame a API antes de ligar um único canal. Cada conta nova começa com 100 mensagens gratuitas.

Obter uma chave de APILer a documentação