Usando o WhatsApp Oficial

O Canal WhatsApp Oficial conecta sua aplicação à WhatsApp Business Platform da Meta. Ele difere do canal não oficial (whatsapp-web) por usar a infraestrutura oficial com WABA (WhatsApp Business Account), templates aprovados pela Meta, cobrança por conversa e as garantias oficiais da plataforma. Diferente do canal não oficial, o canal oficial não é um container: é um registro lógico dentro da MessageFy que aponta para um número de telefone registrado em uma WABA na Meta. A relação continua sendo um canal = um número — múltiplos números exigem múltiplos canais.

Arquitetura provisionada automaticamente

Componente	Descrição	Quem cria
Canal Oficial (`whatsapp-api`)	Representa 1 número de WhatsApp	Você, via API
Router	Administra a conta Meta, credenciais, carteira e templates; roteia os webhooks	Automático (1 por Account)
`http-receiver`	Endpoint público que recebe os webhooks da Meta	Automático
`http-sender`	Entrega tudo que chega/acontece na URL configurada	Você, via API

O Router e o http-receiver são criados uma única vez por Account e reaproveitados para os demais números que você conectar.

Pré-requisitos

Todas as chamadas usam o header X-API-KEY (veja Autenticação). O fluxo assume que você já tem uma Account criada (Contas) — o accountId é usado em praticamente todos os passos.

Passo 1 — Criar o Responsável Financeiro

O canal oficial é pré-pago e exige um Responsável Financeiro com isDefault: true na Account antes da criação do canal. Sem ele, a criação falha com METAGURU_FINANCIAL_MANAGER_REQUIRED.

O Responsável Financeiro é usado para as cobranças da MessageFy (não da Meta): é contra ele que as faturas de crédito da carteira são emitidas.

Passo 2 — Criar o canal de Webhook (http-sender)

É nesse canal que a MessageFy entrega tudo: mensagens recebidas, eventos de status, respostas de comandos e notificações de template. Ele precisa existir antes do canal oficial (será o feedbackChannelId).

POST /api/v1/Admin/Channel
{
  "name": "Sender",
  "description": "Sender Channel",
  "channelType": "http-sender",
  "accountId": "uuid-da-account",
  "parameters": {
    "url": "https://suaempresa.com.br/api/messagefy/receive"
  }
}

Guarde o channelId retornado.

Passo 3 — Criar o canal oficial

POST /api/v1/Admin/Channel
{
  "name": "Atendimento Oficial",
  "description": "Número oficial",
  "channelType": "whatsapp-api",
  "accountId": "uuid-da-account",
  "feedbackChannelId": "uuid-do-canal-http-sender"
}

Erros comuns nesta etapa:

Erro (`errorCode`)	Significado
`FEEDBACK_CHANNEL_REQUIRED`	Falta o `feedbackChannelId`
`METAGURU_INVALID_FEEDBACK_CHANNEL_TYPE`	O feedback channel não é `http-sender`
`METAGURU_FINANCIAL_MANAGER_REQUIRED`	Account sem responsável financeiro `isDefault`
`METAGURU_PHONE_PROVISIONING_IN_PROGRESS`	Outro canal oficial da Account ainda está sendo provisionado (só é permitido um por vez)

Nos bastidores: a MessageFy valida o responsável financeiro, cria o Router e o http-receiver da Account (se ainda não existirem), registra o business na Meta e guarda as credenciais. Quando o Router fica pronto, o canal muda de Created para Running. Acompanhe pelo GET /api/v1/Admin/Channel/{channelId}:

{
  "channelId": "9d2f4c18-7a35-4b6e-9c02-4e8b1f5d3a67",
  "status": { "channelStatusId": 4, "key": "running", "name": "Running" }
}

Só prossiga quando o status for Running (ou aguarde o evento INSTANCE_START no webhook).

Passo 4 — Gerar o link de conexão do número

Todos os comandos usam POST /api/v1/message/SendCommand, sempre com o envelope Package (channelId do canal oficial + content):

{
  "channelId": "uuid-do-canal-oficial",
  "content": {
    "type": "SESSION_START_LINK",
    "commandType": "SESSION_START_LINK"
  }
}

A resposta síncrona é só o enfileiramento ({ "packageId": "..." }); o link chega no webhook:

{
  "packageId": "01a01b1b-ba62-732a-8260-5c38ee201a31",
  "originPackageId": "66cdfd4e-a1a7-4ca6-9931-8ca0f6c443a0",
  "channelId": "uuid-do-canal-oficial",
  "content": {
    "type": "SESSION_START_LINK_GENERATED_RESPONSE",
    "connectionLink": "https://metaguru.../connect?state=eyJid...",
    "success": true,
    "commandType": "SESSION_START_LINK_GENERATED_RESPONSE"
  }
}

Entregue o connectionLink ao dono do número. Ele abre o fluxo de Embedded Signup da Meta: (1) login com a conta Facebook/Meta Business; (2) seleção ou criação da WABA; (3) informação e verificação do número; (4) aceite das permissões.

O link expira em 60 minutos. Se expirar, envie o comando novamente para gerar outro.

Quando o onboarding termina, o webhook recebe o CONNECTED:

{
  "channelId": "uuid-do-canal-oficial",
  "content": {
    "type": "CONNECTED",
    "jid": "5511936236876@s.whatsapp.net",
    "phoneNumber": "5511936236876",
    "timestamp": "2026-08-19T17:47:54+00:00"
  }
}

A partir daí o canal já recebe mensagens. O comando STATUS funciona como no canal não oficial.

Passo 5 — Créditos (Carteira)

O envio é pré-pago: a MessageFy cobra por conversa e o consumo sai da carteira da conta. Sem saldo, os envios falham. Uma carteira é criada automaticamente para cada conta — liste-a com WALLET/LIST, consulte saldo com BALANCE, e gere o link de pagamento com ADD_FUND.

Passo 6 — Templates

No canal oficial, conversas só podem ser iniciadas com um template aprovado pela Meta. Fora da janela de 24 horas (contada da última mensagem do cliente), mensagens livres são recusadas. Crie e liste templates pelos comandos TEMPLATES; envie mensagens a partir de um template aprovado com o tipo TEMPLATE:

POST /api/v1/message/SendMessage
{
  "channelId": "uuid-do-canal-oficial",
  "correlationId": "pedido-10245-confirmacao",
  "content": {
    "type": "TEMPLATE",
    "to": { "type": "WHATSAPP", "number": "5511977776666" },
    "templateId": "7b3f9c21-4d18-4a6e-90f2-1c5e8a7b4d03",
    "components": ["João", "10245", "3"]
  }
}

Dentro da janela de 24h, texto livre e mídia funcionam normalmente (TEXT, IMAGE, etc.).

No canal oficial o to aceita number (só dígitos, com DDI) ou jid — diferente do canal whatsapp-web, que usa exclusivamente jid.

Passo 7 — Receber mensagens e acompanhar envios

Tudo chega na URL do http-sender, no envelope Package padrão (veja Recebendo Eventos). Eventos de status do envio:

Evento (`content.type`)	Quando ocorre
`MESSAGE_SENT`	A Meta aceitou o envio
`MESSAGE_DELIVERED`	Entregue no aparelho do destinatário
`MESSAGE_READ`	Lida pelo destinatário
`SEND_MESSAGE_RESPONSE` com `success: false`	Falha no envio

Exemplo de falha (o detalhe do erro vem em providerMetadata):

{
  "originPackageId": "018f3b40-2c17-7d84-9b31-6a0f5e2c7d19",
  "correlationId": "pedido-10245-confirmacao",
  "content": {
    "type": "SEND_MESSAGE_RESPONSE",
    "commandType": "SEND_MESSAGE_RESPONSE",
    "success": false,
    "error": "Template not approved for this WABA"
  },
  "providerMetadata": {
    "category": "error",
    "error_code": "TEMPLATE_NOT_APPROVED",
    "error_meta_code": "132000",
    "error_http_status": "400",
    "error_title": "Template not approved",
    "error_message": "Template not approved for this WABA",
    "error_request_id": "req_1a2b3c4d"
  }
}

Correlacione pelo correlationId (definido por você) ou pelo originPackageId (o packageId retornado no 200 OK do envio).

Recursos não suportados no canal oficial

Enviar estes comandos retorna success: false com mensagem explicativa (ou é ignorado):

Comando	Situação
`GROUPS` / `GROUP_INFO`	Não suportado pela API da Meta
`MARK_READ`	Não suportado
`START_TYPING` / `STOP_TYPING`	Ignorado
`SESSION_START_QR_CODE` / `SESSION_START_PAIR_CODE`	Não se aplica — a conexão é pelo link de onboarding

Erros comuns

Situação	Causa provável	Resolução
`METAGURU_FINANCIAL_MANAGER_REQUIRED`	Sem responsável financeiro padrão	Crie um com `isDefault: true` (passo 1)
`METAGURU_INVALID_FEEDBACK_CHANNEL_TYPE`	`feedbackChannelId` não aponta para `http-sender`	Crie o canal de webhook (passo 2) e use o id dele
`METAGURU_PHONE_PROVISIONING_IN_PROGRESS`	Outro canal oficial em provisionamento	Aguarde o anterior ficar `Running`
`'waba_phone_number_id' not resolved from routing table`	Número ainda não conectado	Gere o link (passo 4) e conclua o onboarding
Canal parado em `Created`	Router inicializando	Aguarde e consulte o status do canal
Envio falha por saldo	Carteira sem crédito	Adicione fundos (Carteiras)
Envio de texto recusado	Fora da janela de 24h	Inicie a conversa com um template aprovado

Checklist de implantação

Account criada e API Key gerada
Responsável financeiro criado com isDefault: true
Canal http-sender apontando para sua URL e respondendo 2xx
Canal whatsapp-api criado e com status Running
Link de conexão gerado e número conectado (CONNECTED recebido)
Carteira com saldo
Ao menos um template com status APPROVED
Webhook tratando TEXT, MESSAGE_SENT, MESSAGE_DELIVERED, MESSAGE_READ, SEND_MESSAGE_RESPONSE e TEMPLATE_STATUS

Início

Contas

API Keys

Canais

WhatsApp Oficial

Tipos de Mensagem

Operações de Mensagem

Sessão e Conexão

Consultas

Interação

Usando o WhatsApp Oficial

Usando o WhatsApp Oficial

Arquitetura provisionada automaticamente

Pré-requisitos

Passo 1 — Criar o Responsável Financeiro

Passo 2 — Criar o canal de Webhook (http-sender)

Passo 3 — Criar o canal oficial

Passo 4 — Gerar o link de conexão do número

Passo 5 — Créditos (Carteira)

Passo 6 — Templates

Passo 7 — Receber mensagens e acompanhar envios

Recursos não suportados no canal oficial

Erros comuns

Checklist de implantação

​Usando o WhatsApp Oficial

​Arquitetura provisionada automaticamente

​Pré-requisitos

​Passo 1 — Criar o Responsável Financeiro

​Passo 2 — Criar o canal de Webhook (http-sender)

​Passo 3 — Criar o canal oficial

​Passo 4 — Gerar o link de conexão do número

​Passo 5 — Créditos (Carteira)

​Passo 6 — Templates

​Passo 7 — Receber mensagens e acompanhar envios

​Recursos não suportados no canal oficial

​Erros comuns

​Checklist de implantação

Usando o WhatsApp Oficial

Arquitetura provisionada automaticamente

Pré-requisitos

Passo 1 — Criar o Responsável Financeiro

Passo 2 — Criar o canal de Webhook (http-sender)

Passo 3 — Criar o canal oficial

Passo 4 — Gerar o link de conexão do número

Passo 5 — Créditos (Carteira)

Passo 6 — Templates

Passo 7 — Receber mensagens e acompanhar envios

Recursos não suportados no canal oficial

Erros comuns

Checklist de implantação