WhatsApp: conexão e configuração

Como o número de WhatsApp da loja é conectado e configurado pela API de administração.

O WhatsApp Confluence é o canal de WhatsApp da plataforma: o número de WhatsApp Business da loja passa a ter uma caixa de entrada compartilhada (inbox), um assistente automático que vende e atende, campanhas, catálogo e uma mini-loja que abre pelo link enviado na conversa. Esta seção cobre a base: conectar o número, ligar ou desligar recursos e configurar as mensagens fixas (boas-vindas e consentimento) e a aparência da mini-loja. As outras áreas estão em seções vizinhas: caixa de entrada, assistente de IA, catálogo e campanhas, e análises e ligações.

Pontos principais

Todas as rotas ficam em /api/v1/admin/whatsapp-confluence/... e exigem um token de administrador (Authorization: Bearer). A loja é identificada pelo domínio da requisição ($BASE_URL).
Um número = uma conta (wacoex_accounts no banco, account na API). A loja pode ter várias contas; todas as rotas de configuração valem para a loja inteira.
O cadastro usa o fluxo Embedded Signup da Meta: o navegador do administrador abre a janela da Meta e devolve um code, que a API troca por credenciais.
Mudar configurações grava na hora; recursos essenciais (caixa de entrada, assistente, atendimento humano) não podem ser desligados.
O mesmo conjunto de rotas também existe sob /api/v1/vendor/... para o painel do seller, com recorte próprio; esta documentação trata só da superfície de administração.

Como funciona

A conexão tem quatro passos. Os dois primeiros são obrigatórios; os dois últimos são opcionais e têm prazo.

Ler a configuração do cadastro
GET /onboarding/es-config devolve o meta_app_id e o embedded_signup_config_id que o navegador usa para abrir a janela do Embedded Signup.
Trocar o código
Quando a janela fecha, a Meta entrega um code. POST /onboarding/exchange-code troca esse código por um token, descobre a conta WhatsApp Business (WABA) e cria uma conta para cada número dessa WABA.
Assinar o webhook
POST /onboarding/subscribe-webhook faz a Meta passar a enviar mensagens e status deste número para a plataforma. Uma rotina em segundo plano também tenta assinar sozinha se você esquecer.
Importar histórico e contatos (opcional)
Dentro das 24 horas seguintes ao cadastro, POST /onboarding/sync-history e POST /onboarding/sync-contacts pedem à Meta a importação das conversas antigas e da agenda do aplicativo. Cada uma só pode ser pedida uma vez.

Q fila→X código trocado→S webhook assinado→H importação pedida→C completo

`onboarding_state`	`step`	Significado
`Q`	`queued`	Linha criada, nada trocado ainda.
`X`	`connected`	Código trocado e WABA descoberta.
`S`	`subscribed`	Webhook assinado.
`H`	`sync_requested`	Importação de histórico ou contatos pedida.
`C`	`complete`	Cadastro completo e número saudável.
`E`	`error`	Falhou (por exemplo, o número não é compatível).

`status`	Significado
`P`	Pendente: cadastro iniciado, ainda não ativo.
`A`	Ativa: número conectado e saudável.
`E`	Com erro.
`D`	Desconectada (removida pela API).

Conceitos importantes

Conta, WABA e número

A WABA é a conta WhatsApp Business na Meta; ela pode ter vários números. Cada número vira uma conta na plataforma, identificada por um UUID próprio (id) e pelo phone_number_id da Meta. Não confunda os dois: as rotas desta seção recebem o id da plataforma.

Recursos ligáveis

GET /settings devolve um mapa de interruptores (enable_inbox, enable_campaigns, enable_web_preview e dezenas de outros) mais ajustes de uso. Os interruptores essenciais ficam sempre ligados e a API ignora tentativas de desligá-los. Veja Configurações do canal.

Segmento comercial

O segmento (alimentos, moda, autopeças, farmácia...) troca o vocabulário e as regras do assistente e da mini-loja. Veja Segmento e textos.

Privilégios

As rotas de leitura exigem apenas o papel de administrador. As gravações de commerce-profile, welcome e consent-term exigem também o privilégio manage_settings.

Endpoints

Método	Caminho	Para que serve	Autenticação
GET	`/onboarding/status`	Situação da conexão e recursos ligados	admin
GET	`/accounts`	Lista as contas (números)	admin
DELETE	`/accounts/{id}`	Desconecta uma conta	admin
GET	`/onboarding/es-config`	Dados para abrir o Embedded Signup	admin
GET	`/diagnostico`	Verifica se a loja consegue atender ligações	admin
POST	`/onboarding/exchange-code`	Troca o código do Embedded Signup	admin
POST	`/onboarding/subscribe-webhook`	Assina os eventos do número	admin
POST	`/onboarding/sync-history`	Pede a importação do histórico	admin
POST	`/onboarding/sync-contacts`	Pede a importação dos contatos	admin
GET	`/settings`	Lê interruptores e ajustes	admin
PUT	`/settings`	Altera interruptores e ajustes	admin
GET	`/segments`	Catálogo de segmentos comerciais	admin
GET	`/commerce-profile`	Lê o segmento e os textos da loja	admin
PUT	`/commerce-profile`	Grava o segmento e os textos	admin + `manage_settings`
GET	`/welcome`	Lê a mensagem de boas-vindas	admin
PUT	`/welcome`	Grava a mensagem de boas-vindas	admin + `manage_settings`
GET	`/consent-term`	Lê o termo de consentimento	admin
PUT	`/consent-term`	Grava o termo de consentimento	admin + `manage_settings`
GET	`/preview-settings`	Lê a aparência da mini-loja	admin
PUT	`/preview-settings`	Grava a aparência da mini-loja	admin
GET	`/preview-link`	Link público da mini-loja	admin

Todos os caminhos acima começam com /api/v1/admin/whatsapp-confluence.

Erros comuns

Chamar exchange-code com um token de seller: só administrador cadastra o número da loja (403 acesso negado).
Achar que exchange-code com resposta 200 significa número pronto: um número que não é compatível volta com status E e step error. Confira o campo.
Tentar importar histórico ou contatos depois de 24 horas, ou pela segunda vez: 409. A tentativa que falha na Meta também consome o direito.
Mandar em PUT /settings só os campos que quer mudar e esperar que o resto seja zerado: as chaves enviadas são mescladas às existentes.
Usar o phone_number_id da Meta onde a API espera o id da conta.
Ligar enable_meta_flows e enable_web_preview juntos: os dois são excludentes, e a plataforma deixa só o primeiro ligado.

Próximos passos

Conexão e contas

Status, contas e diagnóstico.

Cadastro do número

Embedded Signup passo a passo.

Caixa de entrada

Conversas, respostas e atendimento humano.

API atual/Referência completa

WhatsApp: conexão e configuração

Como o número de WhatsApp da loja é conectado e configurado pela API de administração.

Pontos principais

Todas as rotas ficam em /api/v1/admin/whatsapp-confluence/... e exigem um token de administrador (Authorization: Bearer). A loja é identificada pelo domínio da requisição ($BASE_URL).
Um número = uma conta (wacoex_accounts no banco, account na API). A loja pode ter várias contas; todas as rotas de configuração valem para a loja inteira.
O cadastro usa o fluxo Embedded Signup da Meta: o navegador do administrador abre a janela da Meta e devolve um code, que a API troca por credenciais.
Mudar configurações grava na hora; recursos essenciais (caixa de entrada, assistente, atendimento humano) não podem ser desligados.
O mesmo conjunto de rotas também existe sob /api/v1/vendor/... para o painel do seller, com recorte próprio; esta documentação trata só da superfície de administração.

Como funciona

A conexão tem quatro passos. Os dois primeiros são obrigatórios; os dois últimos são opcionais e têm prazo.

Ler a configuração do cadastro
GET /onboarding/es-config devolve o meta_app_id e o embedded_signup_config_id que o navegador usa para abrir a janela do Embedded Signup.
Trocar o código
Quando a janela fecha, a Meta entrega um code. POST /onboarding/exchange-code troca esse código por um token, descobre a conta WhatsApp Business (WABA) e cria uma conta para cada número dessa WABA.
Assinar o webhook
POST /onboarding/subscribe-webhook faz a Meta passar a enviar mensagens e status deste número para a plataforma. Uma rotina em segundo plano também tenta assinar sozinha se você esquecer.
Importar histórico e contatos (opcional)
Dentro das 24 horas seguintes ao cadastro, POST /onboarding/sync-history e POST /onboarding/sync-contacts pedem à Meta a importação das conversas antigas e da agenda do aplicativo. Cada uma só pode ser pedida uma vez.

Q fila→X código trocado→S webhook assinado→H importação pedida→C completo

`onboarding_state`	`step`	Significado
`Q`	`queued`	Linha criada, nada trocado ainda.
`X`	`connected`	Código trocado e WABA descoberta.
`S`	`subscribed`	Webhook assinado.
`H`	`sync_requested`	Importação de histórico ou contatos pedida.
`C`	`complete`	Cadastro completo e número saudável.
`E`	`error`	Falhou (por exemplo, o número não é compatível).

`status`	Significado
`P`	Pendente: cadastro iniciado, ainda não ativo.
`A`	Ativa: número conectado e saudável.
`E`	Com erro.
`D`	Desconectada (removida pela API).

Método	Caminho	Para que serve	Autenticação
GET	`/onboarding/status`	Situação da conexão e recursos ligados	admin
GET	`/accounts`	Lista as contas (números)	admin
DELETE	`/accounts/{id}`	Desconecta uma conta	admin
GET	`/onboarding/es-config`	Dados para abrir o Embedded Signup	admin
GET	`/diagnostico`	Verifica se a loja consegue atender ligações	admin
POST	`/onboarding/exchange-code`	Troca o código do Embedded Signup	admin
POST	`/onboarding/subscribe-webhook`	Assina os eventos do número	admin
POST	`/onboarding/sync-history`	Pede a importação do histórico	admin
POST	`/onboarding/sync-contacts`	Pede a importação dos contatos	admin
GET	`/settings`	Lê interruptores e ajustes	admin
PUT	`/settings`	Altera interruptores e ajustes	admin
GET	`/segments`	Catálogo de segmentos comerciais	admin
GET	`/commerce-profile`	Lê o segmento e os textos da loja	admin
PUT	`/commerce-profile`	Grava o segmento e os textos	admin + `manage_settings`
GET	`/welcome`	Lê a mensagem de boas-vindas	admin
PUT	`/welcome`	Grava a mensagem de boas-vindas	admin + `manage_settings`
GET	`/consent-term`	Lê o termo de consentimento	admin
PUT	`/consent-term`	Grava o termo de consentimento	admin + `manage_settings`
GET	`/preview-settings`	Lê a aparência da mini-loja	admin
PUT	`/preview-settings`	Grava a aparência da mini-loja	admin
GET	`/preview-link`	Link público da mini-loja	admin

Todos os caminhos acima começam com /api/v1/admin/whatsapp-confluence.

Erros comuns

Chamar exchange-code com um token de seller: só administrador cadastra o número da loja (403 acesso negado).
Achar que exchange-code com resposta 200 significa número pronto: um número que não é compatível volta com status E e step error. Confira o campo.
Tentar importar histórico ou contatos depois de 24 horas, ou pela segunda vez: 409. A tentativa que falha na Meta também consome o direito.
Mandar em PUT /settings só os campos que quer mudar e esperar que o resto seja zerado: as chaves enviadas são mescladas às existentes.
Usar o phone_number_id da Meta onde a API espera o id da conta.
Ligar enable_meta_flows e enable_web_preview juntos: os dois são excludentes, e a plataforma deixa só o primeiro ligado.

Próximos passos

Conexão e contas

Status, contas e diagnóstico.

Cadastro do número

Embedded Signup passo a passo.

Caixa de entrada

Conversas, respostas e atendimento humano.