API de gerenciamento de modelos do WhatsApp

A API de gerenciamento de modelos do WhatsApp permite listar os modelos existentes do WhatsApp, criar novos modelos, excluir modelos e enviar arquivos de mídia para uso nos modelos. Embora os modelos do WhatsApp possam ser gerenciados manualmente por meio do WhatsApp Business Manager UI, a API de gerenciamento de modelos do WhatsApp da Vonage agora permite que você gerencie seus modelos programaticamente por meio da API do WhatsApp Business.

Atualmente, a API de gerenciamento de modelos do WhatsApp permite que você realize as seguintes operações:

• Obter uma lista de modelos
• Criar um modelo
• Excluir um modelo
• Atualizar um modelo
• Carregar mídia

Como obter uma lista de modelos

Usando a API de gerenciamento de modelos do WhatsApp, é possível obter uma lista dos modelos pertencentes ao Account do WhatsApp Business especificado. A API oferece algumas funcionalidades de paginação e filtragem. Por exemplo, é possível filtrar as solicitações por modelo status, language, e name_or_content.

Criação de um modelo

Você pode criar modelos de vários tipos e categorias, bem como criar variações em vários idiomas de um mesmo modelo. Ao criar modelos com versões em vários idiomas, certifique-se de manter a consistência nas traduções entre as versões.

Processo de aprovação

Os modelos precisam ser aprovados pelo Meta antes de poderem ser usados em uma mensagem do WhatsApp. Quando criados, os modelos têm inicialmente um status de PENDING. Uma vez aprovados, eles terão um status de APPROVED, e então pode ser usado.

Modelos de mensagens para a mídia

Ao criar modelos de mensagens com mídia, é necessário primeiro enviar a mídia a ser utilizada para a plataforma do WhatsApp (consulte Envio de arquivos de mídia). As mídias enviadas terão um identificador exclusivo, que pode ser especificado ao criar um modelo.

Variantes linguísticas

É possível criar várias variantes de um modelo para atender a diferentes idiomas. Para isso, crie um modelo com o mesmo name e category como um modelo existente e definir language propriedade e todo o conteúdo de texto, conforme apropriado para a nova variante de idioma. Uma lista dos idiomas suportados está disponível no Documentação do WhatsApp.

Categorias de modelos

A partir de 1º de junho de 2023, o WhatsApp introduzirá novas categorias de conversas para empresas que enviam mensagens; informações sobre essas categorias e seus preços podem ser encontradas aqui. Atualmente, há três categorias de modelos compatíveis para cada um dos tipos de conversas iniciadas pela empresa:

• UTILITY: Facilitar a conclusão de uma solicitação ou transação específica e previamente acordada, ou fornecer ao cliente informações atualizadas sobre uma transação em andamento, incluindo notificações pós-compra e extratos de cobrança regulares.
• AUTHENTICATION: Permite que as empresas utilizem códigos de acesso únicos para verificar os usuários em diversas etapas do login, se necessário (por exemplo, verificação de conta, recuperação de conta, verificações de integridade).
• MARKETING: Conversas iniciadas pela empresa com o objetivo de promover um produto ou serviço aos clientes, como o envio de ofertas relevantes a clientes que tenham dado consentimento. Isso também incluiria qualquer interação relacionada à empresa que não seja uma conversa de autenticação ou de natureza utilitária.

Todos os modelos existentes em uma dessas categorias serão migrados para uma das novas categorias de modelos: TRANSACTIONAL, MARKETING, OTP, ACCOUNT_UPDATE, PAYMENT_UPDATE, PERSONAL_FINANCE_UPDATE, SHIPPING_UPDATE, RESERVATION_UPDATE, ISSUE_RESOLUTION, APPOINTMENT_UPDATE, TRANSPORTATION_UPDATE, TICKET_UPDATE, ALERT_UPDATE ou AUTO_REPLY.

Excluindo um modelo

Você pode excluir um modelo associado a um Account específico do WhatsApp Business, indicando o nome do modelo ou seu ID. Se um determinado modelo tiver várias versões em idiomas diferentes com o mesmo nome, todos As versões com esse nome de modelo serão excluídas.

Depois de excluído, o nome do modelo (aprovado) não poderá ser usado novamente por 30 dias.

Atualização de um modelo

É possível atualizar um modelo existente identificado por meio de seu ID de modelo. Há alguns pontos a serem considerados ao editar um modelo:

1. Os modelos de mensagem só podem ser editados quando se está em um Approved, Rejected, ou Paused estado.
2. Ao editar um modelo ativo, os modelos passarão a ser elegíveis para aprovação automática. Os modelos que forem aprovados nas verificações de formatação e nas verificações da Política de Negócios e Comércio voltarão a ficar ativos imediatamente, sem que seja necessária qualquer ação adicional para continuar enviando as mensagens que já utilizam esses modelos.
3. Ao editar um Paused modelo; os modelos estarão aptos para aprovação automática. Os modelos que passarem nas verificações de formatação e nas verificações da Política de Negócios e Comércio poderão voltar a ser publicados. Para começar a enviar mensagens usando esses modelos, as empresas terão que fazer uma chamada à Messages API.
4. O endpoint “Update” permite alterar a categoria do modelo. Assim que a solicitação for enviada com sucesso, você poderá visualizar tanto a “previous_category” quanto a “category” atualizada ao utilizar o endpoint “List Templates”.
5. Os modelos de mensagem no estado “Aprovado” podem ser editados até 10 vezes em um período de 30 dias, ou 1 vez em um período de 24 horas. As mensagens nos estados “Rejeitado” ou “Pausado” podem ser editadas um número ilimitado de vezes.

Envio de arquivos de mídia

Você pode enviar arquivos de mídia, como imagens, vídeos e arquivos PDF, para a plataforma do WhatsApp para uso em modelos de mensagem com mídia. Os arquivos de mídia precisam ser enviados antes de poderem ser usados em um modelo de mensagem com mídia. Após o envio, os arquivos de mídia ficam disponíveis para uso por 30 dias por meio do identificador de envio de mídia retornado na resposta. Consulte o Documentação do Meta para mais informações.

Exemplo de solicitação cURL

curl --location 'https://api.nexmo.com/v2/whatsapp-manager/media/uploads?file_type=image%2Fjpg' \
--header 'Authorization: Basic NTE1...g==' \
--form 'mediafile=@"Directory/WhatsApp_Image.jpeg"'