> ## Documentation Index > Fetch the complete documentation index at: https://docs.messagefy.io/llms.txt > Use this file to discover all available pages before exploring further. # Usando o WhatsApp Oficial > Guia completo para criar e operar canais do WhatsApp Oficial (WABA/Meta) na MessageFy # 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](/autenticacao)). O fluxo assume que você já tem uma **Account** criada ([Contas](/contas/introducao)) — 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](/whatsapp-oficial/financial-managers) 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`). ```json theme={null} 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 ```json theme={null} 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}`: ```json theme={null} { "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`): ```json theme={null} { "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: ```json theme={null} { "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`: ```json theme={null} { "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`](/comandos/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](/whatsapp-oficial/carteiras) 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`](/whatsapp-oficial/templates); envie mensagens a partir de um template aprovado com o tipo [`TEMPLATE`](/mensagens/template): ```json theme={null} 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](/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`): ```json theme={null} { "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](/whatsapp-oficial/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`