Skip to main content
O Partner Direct Link (TP Lite) é uma opção de integração para YCloud Tech Partners. Você precisa que a YCloud habilite o recurso para a sua conta, mas não precisa se tornar um parceiro da Meta. Crie um link de onboarding de curta duração no seu servidor. Seu cliente pode abri-lo diretamente ou por meio de um botão no seu site. Comece com o Direct Link para testar sua integração e depois use o botão do SDK se quiser que os clientes concluam o cadastro em um pop-up.

Visão geral da integração

  1. Prepare sua conta. Solicite à YCloud a habilitação do Partner Direct Link, crie uma chave de API e configure seu receptor de webhook.
  2. Configure seu ponto de entrada. Abra o Partner Direct Link no painel e defina sua identidade visual, URL de redirecionamento ou origens do SDK.
  3. Crie um link. Seu servidor solicita um link de onboarding para um cliente em seu sistema.
  4. Deixe o cliente se conectar. Eles abrem a página hospedada ou o pop-up do SDK e concluem a autorização da Meta.
  5. Confirme o resultado. Seu backend recebe o webhook e associa a WABA ao cliente.

Antes de começar

  1. Peça à YCloud para habilitar o Partner Direct Link para a sua conta. Se você ainda não for um Tech Partner, candidate-se para se tornar um.
  2. Crie uma chave de API em Desenvolvedores > Chave de API.
  3. Configure seu receptor em Desenvolvedores > Webhooks e assine whatsapp.business_account.updated.
Chame a API de criação de link a partir do seu servidor. Nunca insira sua chave de API no código do navegador ou de aplicativos móveis. Trate cada URL de onboarding como uma credencial temporária: mantenha-a fora de páginas públicas, ferramentas de analytics e logs públicos.
  1. Abra o painel da YCloud para a conta em que o Partner Direct Link está habilitado.
  2. Expanda Desenvolvedores na barra lateral esquerda.
  3. Clique em Partner Direct Link para abrir a página de configuração.
Página do Partner Direct Link com as Configurações básicas e a pré-visualização do cadastro hospedado

Open Developers > Partner Direct Link to configure your branding and entry point. This example shows the settings before configuration.

A página contém Configurações básicas para sua identidade visual e Integração para criar um link, integrar o ponto de entrada e assinar webhooks. Use a Pré-visualização da página hospedada para ver a página voltada ao cliente.

Configure sua identidade visual e ponto de entrada

Abra Desenvolvedores > Partner Direct Link no painel da YCloud. Preencha as Configurações básicas: Para origens do SDK, insira o esquema exato, o domínio e a porta opcional, sem um caminho. Adicione cada subdomínio ou porta separadamente; caracteres curinga não são suportados. Use HTTPS em produção. HTTP é permitido apenas para o desenvolvimento com localhost. O Direct Link funciona sem uma origem permitida do SDK; o botão do SDK não.
  • WhatsApp Business Platform (WHATSAPP_BUSINESS_PLATFORM): Escolha este modo para conectar um número para troca de mensagens por meio de APIs e do seu software.
  • Coexistência com o WhatsApp Business App (WHATSAPP_BUSINESS_APP): Escolha este modo para um número qualificado do Business App existente quando o cliente desejar continuar usando o aplicativo e adicionar o envio de mensagens via API no mesmo número.
Os idiomas suportados são en_US (inglês), zh_CN (chinês simplificado), es_ES (espanhol), pt_BR (português do Brasil), id_ID (indonésio) e ru_RU (russo). Os valores diferenciam maiúsculas de minúsculas. Outros valores retornam HTTP 400. Exemplo de resposta:
expiresAt é o horário de expiração como um timestamp Unix em milissegundos. O tempo de vida padrão do link é de duas horas. Cada link conecta um cliente a uma WABA. Antes de concluir o cadastro, o cliente pode atualizar, tentar novamente ou abrir o link em outro navegador enquanto ele permanecer válido. Após a vinculação bem-sucedida, o link não pode vincular outra WABA. Crie um novo link quando o cliente precisar alterar ou adicionar uma WABA. Adicione um botão de conexão ao seu aplicativo de cliente. Quando o cliente clicar nele, solicite um link de integração ao seu servidor e navegue até onboardingUrl ou abra-o em uma nova janela. Você também pode enviá-lo de forma privada ao cliente pretendido por meio de um canal individual seguro. O cliente abre a página hospedada e clica em Continue with Meta. Ele usa uma conta do Facebook com permissão para gerenciar a empresa e seleciona ou cria a empresa, a WABA e o número de telefone na Meta. A YCloud conclui a vinculação e exibe o resultado.
Integração do Direct Link com um espaço reservado para URL de integração e uma prévia da página de cadastro do cliente

Direct Link integration and the hosted page preview. This example has no generated onboarding link.

Se você configurou uma URL de redirecionamento, o cadastro bem-sucedido redirecionará para lá com status=connected anexado como um parâmetro de consulta. Use isso para atualizar a página voltada ao cliente; use o webhook abaixo para confirmar a vinculação no seu back-end.

Opção 2: Botão SDK

Adicione a origem da sua página a Allowed SDK origins e, em seguida, carregue o SDK. O código do seu navegador chama seu próprio back-end para obter o link. A rota /api/ycloud/onboarding-link abaixo é um exemplo de rota que você implementa no seu servidor.
onStatus(result) relata o estado do cadastro: onError(error) significa que o SDK não conseguiu abrir o cadastro. Seu code pode ser POPUP_BLOCKED ou INVALID_ONBOARDING_URL. onClose(event) é disparado somente quando o cliente fecha a janela antes de um resultado final, com reason: "USER_CLOSED". Esses retornos de chamada atualizam seu front-end. Use o webhook do lado do servidor como o resultado final da vinculação.

Confirmar a vinculação com um webhook

Etapa de integração do Partner Direct Link mostrando o evento de webhook whatsapp.business_account.updated

Subscribe to whatsapp.business_account.updated in Developers > Webhooks to receive the binding result.

A YCloud envia whatsapp.business_account.updated para o seu receptor de webhook configurado após a vinculação ser bem-sucedida. O trecho a seguir mostra os campos que sua integração utiliza:
Quando updateEvent for PARTNER_ADDED, processe a WABA como recém-adicionada. Corresponda partnerCustomerId ao seu cliente e salve o id da WABA. Um valor paymentMethodAttached de true significa que a vinculação de crédito foi bem-sucedida; false significa que ela não foi concluída. Elimine entregas duplicadas usando o evento id e retorne HTTP 2xx após o recebimento bem-sucedido. Consulte Webhooks para a configuração do receptor.