Saltar para o conteúdo principal
Os aplicativos personalizados permitem conceder a uma integração acesso a números de telefone selecionados do WhatsApp Business e APIs da YCloud. Cada aplicativo tem sua própria chave de API, permissões de API e configuração de webhook. Use um aplicativo personalizado quando quiser limitar uma integração apenas aos recursos e funcionalidades de que ela precisa.

Antes de começar

Certifique-se de que:
  • Sua conta usa um plano pago da YCloud. Os aplicativos personalizados não estão disponíveis no plano Free.
  • Sua função pode acessar Developers > Custom apps no painel da YCloud.
  • Os números de telefone do WhatsApp Business de que o aplicativo precisa já estão disponíveis em sua conta da YCloud.
  • Você sabe de quais permissões de API a integração precisa.
  • Você possui um endpoint HTTPS publicamente acessível caso o aplicativo precise de eventos de webhook.
Mantenha a chave de API do aplicativo e o segredo de assinatura do webhook em um gerenciador de segredos. Nunca os exponha em código do lado do cliente, logs, capturas de tela ou controle de versão.

Criar um aplicativo

  1. Faça login no painel da YCloud.
  2. Acesse Developers > Custom apps.
  3. Clique em Create app.
Página de aplicativos personalizados no painel da YCloud com o botão Create app.
  1. Insira um App name. O nome pode conter até 64 caracteres.
  2. Opcional: insira uma Description de até 512 caracteres para que sua equipe saiba para que o aplicativo é usado.
  3. Clique em Create.
Caixa de diálogo Create app com os campos App name e Description.

Enter an app name and, optionally, a description before selecting Create.

A YCloud atribui ao aplicativo um ID de aplicativo somente leitura. Um novo aplicativo fica desativado até que você o ative explicitamente. Configure seus recursos, acesso à API e eventos de webhook antes de ativá-lo.

Atribuir números de telefone do WhatsApp

Atribua apenas os números de telefone aos quais a integração precisa ter acesso.
  1. Abra o aplicativo e selecione Assets.
  2. Clique em Add phone numbers.
Seção Assets de um aplicativo personalizado com o botão Add phone numbers.
  1. Localize um número pelo nome do Gerenciador de Negócios, ID da WABA, nome da WABA ou número de telefone.
  2. Selecione um ou mais números de telefone do WhatsApp Business.
  3. Clique em Confirm.
A janela de seleção também mostra o status de vinculação e a classificação de qualidade de cada número quando essas informações estão disponíveis.
Caixa de diálogo Add phone numbers exibindo os números de telefone do WhatsApp Business disponíveis, status de vinculação e classificação de qualidade.
Os números selecionados agora aparecem na lista de recursos do aplicativo.

Configurar a chave de API e as permissões

A YCloud exibe a chave de API do aplicativo em API key & permissions. As chaves de aplicativos personalizados começam com yc_ak_. Use a ação de cópia para armazenar a chave com segurança e, em seguida, adicione apenas as permissões de que a integração precisa.
Seção API key and permissions de um aplicativo personalizado.
  1. Selecione API key & permissions.
  2. Em API permissions, clique em Add permissions.
  3. Filtre por categoria ou pesquise pelo nome da permissão ou escopo.
  4. Selecione cada permissão necessária. Por exemplo, as permissões de contatos são divididas nos escopos de leitura, criação ou atualização e exclusão.
  5. Clique em Confirm.
Caixa de diálogo Edit permissions exibindo os escopos de permissão de contatos.
Envie a chave gerada no cabeçalho X-API-Key e utilize-a apenas a partir de código confiável do lado do servidor. A YCloud verifica se o aplicativo está ativo e se a requisição corresponde a uma de suas permissões de API selecionadas. Quando uma API opera em um recurso do WhatsApp, a YCloud também verifica se o aplicativo pode acessar o número de telefone ou a WABA em questão. Nem toda API da YCloud está disponível para aplicativos personalizados. Uma API que não aparece no seletor de permissões é negada para uma chave de aplicativo personalizado. As chaves de aplicativos personalizados também não podem ser combinadas com o cabeçalho X-Managed-Account-ID. Consulte Authentication para obter orientações sobre o cabeçalho da requisição e o tratamento de credenciais.
A seção de chave de API inclui uma ação para gerar uma chave de substituição. Dependendo da opção escolhida durante a regeneração, a chave anterior é revogada imediatamente ou permanece disponível por um período de transição de uma hora. Atualize todos os serviços que usam a chave antes do término do período de transição.

Configurar webhooks

Configure um destino dedicado para os eventos de que este aplicativo precisa. Os webhooks do aplicativo são separados dos endpoints de webhook configurados em Developers > Webhooks.
  1. Selecione Webhook.
  2. Insira seu endpoint HTTPS público em Endpoint URL e salve-o.
  3. Armazene o Signing secret gerado em segurança.
  4. Em Added events, clique em Add events.
Seção Webhook com as configurações Endpoint URL, Signing secret e Added events.
  1. Filtre por categoria ou pesquise por nome de evento ou tipo de evento.
  2. Selecione os eventos que seu endpoint precisa receber.
  3. Se um evento oferecer opções de escopo de dados, escolha o escopo compatível com sua integração.
  4. Clique em Confirm.
Caixa de diálogo Add webhook events exibindo os eventos de contato disponíveis.
A YCloud entrega apenas eventos selecionados para o endpoint de um aplicativo ativo. Os eventos do WhatsApp são filtrados de acordo com os números de telefone atribuídos ao aplicativo ou suas WABAs mãe. As configurações de escopo de dados específicas de eventos podem limitar ainda mais a entrega aos dados atribuídos ao aplicativo. Eventos de contato e cancelamento de inscrição ocorrem no nível do tenant porque não estão associados a um ativo do WhatsApp. Seu endpoint deve validar a assinatura da YCloud antes de processar uma solicitação e retornar uma resposta 2xx de sucesso prontamente. Consulte Configurar webhooks para validação de assinatura, tratamento de entrega e orientações de segurança. Consulte Payloads de eventos de Webhook para ver os esquemas de eventos.

Ativar e verificar o aplicativo

Antes de usar o aplicativo em produção:
  1. Confirme se o aplicativo contém os números de telefone do WhatsApp Business esperados.
  2. Revise todas as permissões de API e remova o acesso que a integração não precisa.
  3. Retorne a Desenvolvedores > Aplicativos personalizados e ative o aplicativo a partir do seu menu de ações.
Lista de aplicativos personalizados com a ação Ativar para um aplicativo inativo.
  1. Confirme se o status do aplicativo está como Ativo.
  2. Envie uma solicitação de teste com a chave de API do aplicativo a partir de um ambiente seguro no servidor.
  3. Dispare um evento selecionado e confirme se o seu endpoint o valida e processa.
Apenas aplicativos ativos podem autenticar solicitações de API ou receber eventos de webhook. Você pode encontrar um aplicativo existente pelo seu nome ou ID do aplicativo. Abra Editar para revisar ou atualizar sua configuração.