Fluxo de cadastro incorporado e hospedado pelo WhatsApp para parceiros de tecnologia

O Fluxo de Cadastro Incorporado Hospedado do WhatsApp é uma interface de usuário de integração com marca branca. Ele permite que os parceiros da Vonage realizem a integração de seus clientes às contas do WhatsApp Business sem a necessidade de criar, configurar ou hospedar seu próprio Fluxo de Cadastro Incorporado.

A seguir, é apresentado um resumo dos pré-requisitos e do fluxo do processo. Para obter informações mais detalhadas, consulte o Guia de inscrição para prestadores de serviços de tecnologia.

Pré-requisitos

Para poder utilizar a solução de cadastro integrada, os parceiros da Vonage devem atender aos seguintes requisitos prévios:

  • Cadastre-se na Meta como provedor de tecnologia
  • Tenha um Meta App ativo no Painel de Aplicativos
  • Ter permissão de “Controle total” ou de administrador no Portfólio de Negócios no qual um número WABA ou do WhatsApp será cadastrado
  • Enviei uma solicitação de solução à Vonage, a solicitação foi aceita e recebi um ID de solução

Caso tenha dúvidas ou precise de suporte em relação a qualquer um dos pré-requisitos listados acima, entre em contato com seu gerente de contas da Vonage.

Fluxo do processo

O fluxo do processo para o cadastro no WhatsApp Hosted Embedded é o seguinte:

  1. O Parceiro da Vonage gera uma URL de cadastro incorporada
  2. O Parceiro pode compartilhar o URL com seus clientes (por exemplo, por e-mail ou SMS, ou incorporando o URL em sua própria página da web)
  3. A URL direciona o cliente para um fluxo de cadastro incorporado com marca branca, hospedado pela Vonage, por meio do qual é possível concluir o cadastro de um Account do WhatsApp Business (WABA) ou de um número do WhatsApp
  4. O cliente conclui o processo de integração por meio do fluxo de cadastro integrado

Observação: as tentativas de cadastro ou cancelamento de cadastro para cada número do WhatsApp são limitadas (10 tentativas por número por semana).

Geração de uma URL de cadastro incorporada

É possível gerar uma URL de cadastro incorporada enviando uma solicitação POST para o Gerar o endpoint da URL do fluxo do ES hospedado do API do Channel Manager.

Observação: a API do Channel Manager está atualmente em fase beta.

A autenticação pode ser feita por meio da autenticação básica (Basic Auth) ou da autenticação por token de portador (JWT).

O corpo da solicitação deve conter um objeto JSON com, no mínimo, um solution_id propriedade cujo valor é o ID da solução fornecido pela Vonage (consulte pré-requisitos).

O corpo também pode conter um api_key propriedade para identificar a subconta da Vonage do cliente para o qual o Parceiro deseja criar a URL (caso essa propriedade seja omitida, será utilizada a chave de API principal da conta principal da Vonage).

A ttl Também é possível especificar essa propriedade para definir o prazo de validade da URL gerada (No máximo 3 dias; se omitido, é utilizado o prazo de validade padrão de 86.400 segundos, ou seja, um dia).

Exemplo de corpo da solicitação

{
  "solution_id": "123456789111213",
  "api_key": "abc123", // Optional
  "ttl": 3600 // Optional
}

Exemplo de corpo da resposta

Uma resposta bem-sucedida retornará um código de status HTTP de 200 e inclua um corpo de resposta com um objeto JSON que contenha a URL de cadastro incorporada gerada, bem como um ID de rastreamento para a solicitação.

{
  "id": "3amb0119-0196-42d1-8fb5-55a98s133546",
  "url": "https://tools.vonage.com/wa/partners/onboard?token=fhdhhdJhbGciOiJSUzI1NiJ9.eyJleHAiOjE3MjU5Njc1OTYsImp0aSI6ImQ1MmJhNmFjLWYxZjktNDdmNC05MTR_cFT1bVfkDhP-wgpKZibSbUoh9z-9KGD-wsmHxi0h7tTidpVhPNShfC5jmgiHtOQKXXv5NWb9OqoUraOMMpqCdNdXoN3ao-PeZX7axyYW_FQ6CeV9gDEPhAZ4urTi0uW4mCYGl3ULmA9Ps92r_wi2DJyRE_Kx2KahWtQd51yVpU6FfXgMb4odREEccDctT1Peo09wKgwBa1wsOkD7rrvkoQPqZ00VXcqOY1_LOO5tq4WJaKqtxX-U7VtDo9qyVUl8pdegZW6QWChQzGN4PkqXXLWcBlyrCtAYdhtWG8q6NM_6bARRjcGJlj0tQvE0PZ9AtafAQSPpOll5lcnUK8Ds"
}

Como verificar o status do número de verificação do WhatsApp

Como parte do processo de registro do número no WhatsApp, uma senha de uso único (OTP) será enviada ao número que está sendo registrado, a fim de verificá-lo. A verificação deve ser concluída com sucesso antes que o número possa ser utilizado.

É possível verificar o status da verificação do número das seguintes maneiras:

Observação: os administradores do cliente também receberão uma notificação por e-mail e uma notificação do Meta Business Suite sobre o status da integração.

Verificar manualmente o status de um número

Para verificar manualmente o status de um número, você pode acessar a interface do WhatsApp Manager do seu WABA. Um número ativo exibirá o status de Conectado.

Screenshot of WhatsApp Manager showing number status

Inscrever-se para receber atualizações sobre um número

Você pode se inscrever para receber atualizações sobre a mudança no status de verificação de um número usando Assinaturas de notificações do WhatsApp.

É possível criar assinaturas para diversos tipos de eventos; você pode ler mais sobre isso no Guia sobre assinaturas de notificações do WhatsApp. Para receber atualizações sobre o status dos números, é necessário criar uma assinatura com o account_update tipo de assinatura no whatsapp_subscribe_types, e também o vonage_number_onboarded tipo de assinatura no vonage_subscribe_types.

A notificação é acionada por um PARTNER_ADDED evento e é enviada para o webhook ou hook do Slack que você especificou ao criar a assinatura. A carga útil da notificação incluirá o waba_id, solution_id, e owner_business_id detalhes.

A carga útil de um POST solicitação à https://api.nexmo.com/v2/whatsapp-manager/subscriptions O endpoint teria uma aparência mais ou menos assim:

{
  "type": "webhook",
  "label": "#dk-test",
  "whatsapp_subscribe_types": "account_update", // or can be left blank ""
  "vonage_subscribe_types": "vonage_number_onboarded",
  "webhook": {
      "url" : "https://eo34s4y0tl.m.pipedream.net"
  }
}

Observação: o valor do id retornado na resposta quando Geração de uma URL de cadastro incorporada está relacionado ao valor do onboarding_id propriedade na notification_value objeto dentro do whatsapp objeto na carga útil da notificação.

Como vincular um número do WhatsApp a uma aplicação da Vonage

Para que o número do WhatsApp possa ser usado para enviar mensagens por meio da Messages API do Vonage, ele precisa estar vinculado a um aplicativo da Vonage.

Isso pode ser feito por meio do Painel do Vonage ou pelo Vincular o aplicativo a um endpoint de Account do API de Contas Externas.

Notas para os parceiros

  • Não é necessária nenhuma ativação específica para que um Parceiro ou Provedor de Tecnologia da Vonage utilize o Fluxo de Cadastro Incorporado Hospedado. O acesso pode ser feito por meio da página principal api-key e as credenciais associadas.
  • Apenas os Accounts do WhatsApp Business (WABAs) “Compartilhados” dos clientes podem realizar a integração de novos números do WhatsApp por meio do fluxo de cadastro incorporado hospedado ou de qualquer fluxo de cadastro incorporado. Para WABAs OBO, é necessário utilizar a integração manual. Consulte o Documentação do Meta para obter mais detalhes sobre OBO e WABAs compartilhadas.
  • Os parceiros e provedores de tecnologia da Vonage devem garantir que seus clientes que utilizam o Hosted Embedded Flow tenham preenchido e completado os detalhes comerciais na seção “Informações do portfólio comercial”. Se algum dado obrigatório, como o e-mail comercial do usuário, estiver inválido, é provável que o processo de integração falhe.
  • Durante o cadastro do número no WhatsApp, o tempo de resposta esperado da API da Meta pode chegar a 120s.
  • As tentativas de cadastro ou cancelamento de cadastro para cada número do WhatsApp são limitadas pela Meta (10 tentativas por número por semana). Após atingir esse limite, o número será bloqueado para cadastro.