Provisionamento e envio de adesivos do WhatsApp com as APIs da Vonage

Os adesivos são um recurso muito popular nas conversas do WhatsApp há anos. Nesta postagem, vamos explicar o que são e como usá-los em suas comunicações pelo WhatsApp, por meio das Messages API do Vonage.

Os adesivos são elementos visuais que podem ser usados em um chat do WhatsApp, semelhantes aos emojis, mas com imagens maiores. Este artigo, do portal oficial de documentação do WhatsApp, explica como os usuários do WhatsApp podem baixar e usar adesivos.

Cute WhatsApp dragon sticker

Já existem inúmeros pacotes de adesivos disponibilizados pelo WhatsApp e por desenvolvedores independentes. Uma das grandes vantagens dos adesivos é que qualquer pessoa pode criar e publicar pacotes personalizados de terceiros. Adesivos personalizados criados com base na sua marca podem ser uma maneira inovadora e divertida de aumentar o reconhecimento da marca e o engajamento dos clientes!

Como criar um pacote de adesivos

Para publicar um pacote de adesivos personalizado, você precisará criar um aplicativo de adesivos e, em seguida, lançá-lo na Google Play Store e/ou na Apple App Store. Não entraremos em detalhes sobre como criar um aplicativo de adesivos nesta postagem, mas um ótimo ponto de partida é este guia do usuário na documentação do WhatsApp. A equipe do WhatsApp também disponibilizou um aplicativo de exemplo que você pode adaptar para seu próprio uso.

Existem certos requisitos para os adesivos, em termos de tamanho, formato e assim por diante, que estão listados no Android para o repositório e iOS README no repositório do aplicativo de exemplo.

Preparação de adesivos do WhatsApp para uso

Depois que o aplicativo de adesivos for criado e lançado, seus clientes poderão instalá-lo e baixar seu pacote de adesivos para usar em seus chats do WhatsApp. No entanto, se você quiser usar os adesivos (por exemplo, em mensagens do WhatsApp enviadas aos clientes por meio da Messages API), primeiro precisará habilitar o pacote de adesivos para uso pela sua conta do WhatsApp Business.

O provisionamento é realizado por meio da API de provisionamento do WhatsApp da Vonage.

Caso ainda não tenha feito isso, o primeiro passo é provisionar uma implantação do WhatsApp. Isso pode ser feito enviando uma solicitação POST para o seguinte endpoint /whatsapp-manager/deployments, conforme detalhado na especificação da API:

https://api.nexmo.com/v0.1/whatsapp-manager/deployments

Mais informações sobre o provisionamento de implantações do WhatsApp estão disponíveis neste este documento.

Ao provisionar uma implantação do WhatsApp, você receberá um ID de implantação, que poderá ser usado em diversos aspectos do gerenciamento dessa implantação, incluindo o provisionamento de pacotes de adesivos personalizados para uso pela sua conta do WhatsApp Business. O provisionamento do pacote de adesivos requer uma solicitação POST para o seguinte endpoint da API:

https://api.nexmo.com/v0.1/whatsapp-manager/deployments/:deployment_id/stickerpacks

Observação: o `:deployment_id` no caminho é substituído pelo ID de implantação da sua implantação do WhatsApp.

O corpo da solicitação ficaria mais ou menos assim:

{
  "publisher": "your-publisher-name",
  "name": "your-sticker-pack-name",
  "ios_app_store_link": "https://itunes.apple.com/app/id3133333",
  "android_app_store_link": "https://play.google.com/store/apps/details?id=com.example"
}

Uma resposta bem-sucedida incluiria o ID do pacote de adesivos implantado.

{
  "stickerpacks": [
    {
      "id": "sticker-pack-id1"
    }
  ]
}

Mais detalhes sobre como enviar solicitações a este endpoint estão disponíveis na especificação da API.

Enviando um adesivo (usando a Messages API)

Depois que seu pacote de adesivos estiver disponível, você poderá usar os adesivos em um chat do WhatsApp. Para isso, você precisará do ID do adesivo específico que deseja enviar. São necessárias algumas etapas para obtê-lo:

1. Acesse o índice de adesivos. Isso é feito por meio de uma GET solicitação a um endpoint que contém o deployment_id e o stickerpack_id, e está detalhado em esta especificação da API. A resposta retorna um objeto com uma index propriedade, cujo valor é o índice do adesivo necessário para a próxima etapa.

2. Obter o ID de um adesivo. Isso requer outra GET solicitação para um endpoint diferente, desta vez contendo o deployment_id e stickerpack_id , além do sticker_index obtido na etapa anterior. Essa solicitação retornará uma matriz de objetos de adesivo, cada um com uma id propriedade. Esse endpoint está detalhado na esta especificação da API.

Assim que tiver a id do adesivo, você pode enviá-lo em uma mensagem do WhatsApp, usando a Messages API da Vonage.

O envio de um adesivo envolve uma solicitação POST para o seguinte endpoint: https://api.nexmo.com/v1/messages.

A carga JSON do corpo da solicitação pode ter uma aparência semelhante a esta:

{
   "from":"447700900000",
   "to":"447700900001",
   "channel":"whatsapp",
   "message_type":"custom",
   "custom":{
      "type":"sticker",
      "sticker":{
         "id":"13aaecab-2485-4255-a0a7-97a2be6906b9"
      }
   }
}

Observe que channel valor definido como whatsapp e o message_type de custom, bem como o fato de o objeto custom ter um type de sticker, e um objeto de adesivo que contém o ID do adesivo obtido anteriormente.

Para obter mais informações sobre como usar a Messages API e sobre como enviar mensagens pelo WhatsApp, consulte os seguintes recursos:

• Especificação da Messages API

• Entendendo as mensagens do WhatsApp

• Objetos personalizados