Skip to main content
Os apps personalizados permitem conceder a uma integração acesso a números de telefone selecionados do WhatsApp Business e APIs da YCloud. Cada app tem sua própria chave de API, permissões de API e configuração de webhook. Use um app personalizado quando quiser limitar uma integração aos ativos e recursos de que ela precisa.

​
Antes de começar

Certifique-se de que:
  • Sua conta usa um plano pago da YCloud. Os apps personalizados não estão disponíveis no plano Free.
  • Sua função tem acesso a Desenvolvedores > Apps personalizados no painel da YCloud.
  • Os números de telefone do WhatsApp Business necessários para o app 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 app precise de eventos de webhook.
Mantenha a chave de API do app 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 app

  1. Faça login no painel da YCloud.
  2. Acesse Desenvolvedores > Apps personalizados.
  3. Clique em Criar app.
Página de apps personalizados no painel da YCloud com o botão Criar app.
  1. Insira um Nome do app. O nome pode conter até 64 caracteres.
  2. Opcional: Insira uma Descrição de até 512 caracteres para que sua equipe saiba para que o app é usado.
  3. Clique em Criar.
Caixa de diálogo Criar app com os campos Nome do app e Descrição.

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

A YCloud atribui ao app um ID de app somente leitura. Um novo app fica desativado até que você o ative explicitamente. Configure seus ativos, 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 app e selecione Ativos.
  2. Clique em Adicionar números de telefone.
Seção de ativos de um app personalizado com o botão Adicionar números de telefone.
  1. Localize um número pelo nome do Gerenciador de Negócios, WABA ID, nome da WABA ou número de telefone.
  2. Selecione um ou mais números de telefone do WhatsApp Business.
  3. Clique em Confirmar.
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 Adicionar números de telefone exibindo os números de telefone disponíveis do WhatsApp Business, o status de vinculação e a classificação de qualidade.
Os números selecionados agora aparecem na lista de ativos do app.

​
Configurar a chave de API e as permissões

A YCloud exibe a chave de API do app em Chave de API e permissões. As chaves de apps personalizados começam com yc_ak_. Use a ação de copiar para armazenar a chave com segurança e, em seguida, adicione apenas as permissões necessárias para a integração.
Seção de chave de API e permissões para um app personalizado.
  1. Selecione Chave de API e permissões.
  2. Em Permissões de API, clique em Adicionar permissões.
  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 em escopos de leitura, criação ou atualização e exclusão.
  5. Clique em Confirmar.
Caixa de diálogo Editar permissões exibindo os escopos de permissão de contato.
Envie a chave gerada no cabeçalho X-API-Key e use-a somente a partir de código confiável do lado do servidor. A YCloud verifica se o app está ativo e se a requisição corresponde a uma de suas permissões de API selecionadas. Quando uma API opera em um ativo do WhatsApp, a YCloud também verifica se o app pode acessar o número de telefone relevante ou a WABA. Nem toda API da YCloud está disponível para apps personalizados. Uma API que não aparece no seletor de permissões é negada para a chave de um app personalizado. As chaves de apps personalizados também não podem ser combinadas com o cabeçalho X-Managed-Account-ID. Consulte Autenticação para obter orientações sobre o cabeçalho de requisição e o tratamento de credenciais.
A seção de chave de API inclui uma ação para gerar uma nova 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 que o período de transição termine.

​
Configurar webhooks

Configure um destino dedicado para os eventos de que este app precisa. Os webhooks de app são separados dos endpoints de webhook configurados em Desenvolvedores > Webhooks.
  1. Selecione Webhook.
  2. Insira seu endpoint HTTPS público em URL do endpoint e salve-o.
  3. Armazene o Segredo de assinatura gerado com segurança.
  4. Em Eventos adicionados, clique em Adicionar eventos.
Seção de Webhook com as configurações de URL do endpoint, Segredo de assinatura e Eventos adicionados.
  1. Filtre por categoria ou pesquise pelo nome do evento ou tipo de evento.
  2. Selecione os eventos que seu endpoint deve receber.
  3. Se um evento oferecer opções de escopo de dados, escolha o escopo que corresponde à sua integração.
  4. Clique em Confirmar.
Caixa de diálogo Adicionar eventos de webhook 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 com base nos números de telefone atribuídos ao aplicativo ou em suas WABAs pai. 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 locatário (tenant), pois 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 de sucesso 2xx prontamente. Consulte Configurar webhooks para orientações sobre validação de assinatura, tratamento de entregas e 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 de que a integração não precisa.
  3. Retorne a Desenvolvedores > Aplicativos personalizados e ative o aplicativo no menu de ações.
Lista de aplicativos personalizados com a ação Ativar para um aplicativo inativo.
  1. Confirme se o status do aplicativo é Ativo.
  2. Envie uma solicitação de teste com a chave de API do aplicativo a partir de um ambiente seguro no lado do 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 nome ou ID do aplicativo. Abra Editar para revisar ou atualizar a configuração dele.