Conectar pela API Oficial
Passo a passo da API Oficial do WhatsApp: o que criar na Meta, o assistente de 5 passos do ggCheckout, o webhook e o primeiro template aprovado.
A API Oficial conecta ao ggCheckout um número registrado na plataforma do WhatsApp Business, da Meta, pela WhatsApp Cloud API. A conexão usa as credenciais de um app seu no Meta for Developers: o token de um usuário do sistema, o App Secret do app e os IDs da conta e do número. As mensagens desse número saem só por templates aprovados pela Meta. Esta página vai da conta na Meta até o número conectado no ggCheckout e o primeiro template aprovado.
Antes de começar, na Meta
A conexão depende de itens que existem só na Meta. Alguns podem ser criados durante o próprio passo a passo.
| Item | Para que serve |
|---|---|
| Conta do Facebook | Dá acesso ao Meta for Developers e às configurações do negócio. A Meta também aceita uma conta gerenciada da Meta. |
| Cadastro de desenvolvedor | Permite criar apps no Meta for Developers. |
| Portfólio empresarial | Antigo Gerenciador de Negócios (Business Manager). É o dono do app, da conta do WhatsApp Business e do usuário do sistema. Pode ser criado durante a criação do app. |
| Conta do WhatsApp Business (WABA) | Guarda o número, os templates e a cobrança da Meta. A documentação atual da Meta também a chama de conta de mensagens. Pode ser criada na tela Configuração da API do app. |
| Número de telefone | Precisa ser seu, ter código do país e DDD e receber SMS ou ligação, por onde chega o código de verificação. Códigos curtos não são aceitos. |
| Nome de exibição | É o nome que aparece no perfil do WhatsApp do número e segue as diretrizes de nome de exibição da Meta. A Meta revisa o nome quando o número alcança um limite de envio maior. |
| Forma de pagamento na Meta | A Meta cobra por mensagem entregue pela API, e a cobrança é feita pelo Meta Business Suite, onde fica a forma de pagamento da conta. |
Verificação da empresa
A verificação da empresa é o processo em que a Meta confirma os dados do negócio dono do portfólio empresarial. O assistente do ggCheckout pede, no passo 1, o portfólio "que estiver com a verificação concluída", e o aviso de aprovação dos templates informa que contas novas ou não verificadas podem ficar em análise. Pela documentação da Meta, a verificação também muda o que o portfólio pode fazer:
- é um dos caminhos para o limite de envio passar de 250 para 2.000 destinatários em 24 horas, aumento que a Meta aprova ou nega depois de analisar a qualidade das mensagens;
- o número de telefones registrados no portfólio passa de 2 para 20.
O pedido é feito nas configurações do negócio, conforme a página Como verificar sua empresa, da Meta.
Número que já está no WhatsApp
Pela documentação da Meta, um número em uso no aplicativo WhatsApp ou WhatsApp Business só pode ser registrado na API depois que a conta do aplicativo é excluída, em Configurações > Conta > Excluir minha conta. O número fica disponível em até 3 minutos. O histórico de conversas do aplicativo se perde, por isso a Meta orienta fazer o backup antes. Depois do registro, o número não funciona mais no aplicativo enquanto estiver na API.
A Meta também prevê o uso do mesmo número no aplicativo WhatsApp Business e na API ao mesmo tempo, chamado de coexistência. Esse caminho existe só no cadastro incorporado feito por um parceiro da Meta. A conexão do ggCheckout usa as credenciais do seu próprio app e não abre o cadastro incorporado. Os detalhes estão na página Migrar um número do WhatsApp existente, da Meta.
No ggCheckout: conectar o número
O assistente Conectar API Oficial (Meta) tem 5 passos. Os passos 1 a 3 mostram o que fazer na Meta, e os passos 4 e 5 recebem as credenciais. Continuar avança e Voltar retorna ao passo anterior.
-
Abra o assistente. Em Ferramentas > WhatsApp, parte Chips, clique em Cadastrar chip e escolha API Oficial (Meta).
-
Passo 1 de 5, Criar app. O link Abrir Meta for Developers abre o painel de apps da Meta.
Na Meta, conforme a introdução à API de Nuvem do WhatsApp:
- No Painel de Apps, clique em Criar app.
- Informe o nome do app e o seu e-mail.
- Selecione o caso de uso Conectar-se com clientes pelo WhatsApp e clique em Avançar.
- Selecione o portfólio empresarial ou crie um novo.
- Na lista de requisitos de publicação, clique em Avançar.
- Confira os dados e clique em Criar app.
- Na página Início rápido, clique em Começar a usar a API.
- Na Configuração da API, selecione a conta do WhatsApp Business ou clique em Criar uma conta do WhatsApp Business.
- Na mesma tela, adicione o número de telefone e confirme o código recebido por SMS ou ligação.
-
Passo 2 de 5, App Secret. No app, abra Configurações e depois Básico no menu da esquerda e copie o App Secret. A página Configurações básicas, da Meta, descreve essa tela.
-
Passo 3 de 5, System User. O usuário do sistema é criado nas configurações do negócio (business.facebook.com), e não no Meta for Developers. O link Abrir Usuários do sistema leva direto à tela.
Na Meta, conforme a etapa 5 da introdução à API de Nuvem do WhatsApp:
- Em Configurações do negócio, clique em Usuários do sistema.
- Clique em Adicionar+, dê um nome ao usuário e escolha a função Admin, como indica o assistente.
- Selecione o usuário e clique em Atribuir ativos. Selecione o app e ative Gerenciar app em Controle total.
- Selecione a conta do WhatsApp e ative Gerenciar contas do WhatsApp Business em Controle total. Clique em Atribuir ativos.
- Clique em Gerar token, escolha o app e a expiração Nunca.
- Marque as permissões
whatsapp_business_managementewhatsapp_business_messaging. A Meta também listabusiness_management, que o ggCheckout pede quando não encontra a conta do WhatsApp. - Copie o token. Ele aparece uma única vez.
-
Passo 4 de 5, Credenciais. Cole o token em System User Token e o App Secret em App Secret. O token precisa ser permanente, com expiração Nunca. Continuar é liberado com os dois campos preenchidos.
-
Passo 5 de 5, Número. Os dois IDs ficam no app, em WhatsApp > Configuração da API, cada um com um botão de copiar. Preencha WhatsApp Business Account ID (WABA ID), Phone Number ID e Nome do chip, e clique em Conectar. O ggCheckout valida as credenciais com a Meta. Os erros possíveis estão em Problemas comuns.
-
Configure o webhook na Meta. Com a conexão aceita, a tela Número conectado! mostra a Callback URL e o Verify Token. A tela avisa que o Verify Token não é exibido de novo depois de fechar. No app da Meta, abra Casos de uso, clique em Personalizar no WhatsApp, abra Configuração no menu da esquerda, cole a URL de callback e o Verify Token, ligue o campo
messagese clique em Verificar e salvar. Pelo webhook, a Meta avisa o ggCheckout sobre a entrega das mensagens, como descreve a página Webhooks do WhatsApp, da Meta. -
Coloque o chip em uma sessão. O número aparece na lista de chips com o tipo Oficial. Ele só envia mensagens depois de entrar em uma sessão, como descrito em Sessões.
O primeiro template aprovado
Pela API Oficial, toda mensagem automática do ggCheckout é um template, e a Meta precisa aprovar cada um antes do envio. Os templates desses chips ficam na aba API Oficial da parte Templates.
- Escolha o evento. A lista agrupa os eventos em Fluxo de pagamentos, Recuperação, Upsell e Downsell.
- Revise a mensagem. A mensagem não pode começar nem terminar com uma variável. Templates nessa situação aparecem em Precisam de ajuste, com o botão Corrigir.
- Publique na Meta. No bloco Publicar na Meta, escolha o Idioma do template e clique em Publicar na Meta. Com mais de uma conta conectada, o painel pede Escolha a conta (WABA). Publicar N na Meta, abaixo da lista, publica de uma vez todos os templates prontos.
- Acompanhe a análise. O selo do template mostra Em análise até a resposta da Meta e depois Aprovado, Rejeitado, Pausado ou Desativado. O aviso do painel diz: "Você publica e a Meta revisa cada template antes de liberar o envio. Não é automático nem instantâneo (de minutos a algumas horas). Você não aprova; a Meta aprova." Pela análise de modelos da Meta, a decisão leva até 24 horas.
Um template editado depois de publicado precisa ser publicado de novo com Republicar. Até lá, a Meta continua enviando a versão aprovada, e a nova versão passa por outra aprovação.
Importar consulta a Meta e atualiza o status dos templates que o ggCheckout publicou. Ele também liga templates já aprovados em outra conta, sem publicar de novo. Templates criados direto no Gerenciador do WhatsApp, com outro nome, não são importados.
Depois de conectar: regras da Meta
Estas regras são da Meta e valem para qualquer número na API Oficial.
- Janela de 24 horas. Quando o comprador manda uma mensagem ao número, abre uma janela de atendimento de 24 horas, renovada a cada nova mensagem dele. Dentro da janela, a empresa pode enviar mensagens livres. Fora dela, só templates aprovados. A Meta também exige que o destinatário tenha aceitado receber mensagens da empresa.
- Limite de envio. O limite é o número de destinatários diferentes que o portfólio empresarial alcança fora da janela de atendimento em 24 horas, somando todos os números do portfólio. Portfólios novos começam com 250. O limite pode subir para 2.000 depois da verificação da empresa ou de 2.000 mensagens entregues em 30 dias por templates de alta qualidade, e a Meta aprova ou nega o aumento depois de analisar a qualidade. A partir daí, a Meta sobe o limite sozinha para 10.000, 100.000 e ilimitado, quando a qualidade está alta e o portfólio usou ao menos metade do limite nos últimos 7 dias. A página Limites de mensagens traz as regras completas.
- Qualidade. A Meta avalia como os destinatários receberam as mensagens nos últimos 7 dias, por sinais como bloqueios, denúncias e conversas silenciadas ou arquivadas. Cada template também tem uma classificação de qualidade, e um template com retorno negativo pode ser pausado ou desativado. O status, a qualidade e o limite do número ficam no Gerenciador do WhatsApp, em Ferramentas da conta > Números de telefone.
Cobrança
A tela Minhas faturas informa que os disparos de WhatsApp pela API Oficial entram na mesma fatura da taxa sobre as vendas, que fecha a cada 7 dias. A Meta tem preços próprios por mensagem entregue, que variam com a categoria do template (marketing, utilidade ou autenticação) e com o país do destinatário, publicados na página Preços na plataforma do WhatsApp Business.
No painel
Ferramentas > WhatsApp, parte Chips, botão Cadastrar chip e opção API Oficial (Meta). Os templates ficam na parte Templates, aba API Oficial.
Páginas relacionadas
- Templates: os eventos, as variáveis e as opções de envio de cada template.
- Problemas comuns: os erros do assistente e da publicação de templates.
- Modalidade Billing: a fatura semanal do ggCheckout.