Guia de migração do WhatsApp da versão 0.1 para a versão 1

Atualmente, existem duas versões da Messages API: v0.1 e v1. Embora a v1 seja compatível com todos os recursos da v0.1, há algumas diferenças significativas entre as duas versões que devem ser levadas em consideração caso você já esteja usando a v0.1 da API e pretenda migrar para a v1.

Estrutura JSON

Uma das diferenças mais importantes entre as duas versões é a estrutura utilizada para os dados JSON nas solicitações à API e para os dados recebidos por webhook; a v1 oferece uma estrutura simplificada e mais plana. Para que seu aplicativo funcione com a v1, será necessário alterar qualquer código que gere ou faça referência aos dados JSON.

Algumas das diferenças entre as duas estruturas incluem:

• to e from são nós de valor único, em vez de um objeto
• A mensagem channel só precisa ser especificado uma vez, em vez de ser especificado como um type em to e from
• O message O objeto foi substituído por um message_type, e um nó de valor único com o tipo de conteúdo implícito no rótulo, por exemplo: "text": "this is a text"

Exemplos

Mensagem enviada pelo WhatsApp V0.1

{
  "to": {
    "type": "whatsapp",
    "number": "447700900000"
  },
  "from": {
    "type": "whatsapp",
    "number": "447700900001"
  },
  "message": {
    "content": {
      "type": "text",
      "text": "Hello From Vonage!"
    }
  }
}

Mensagem enviada pelo WhatsApp V1

{
  "message_type": "text",
  "text": "Hello From Vonage!",
  "to": "447700900000",
  "from": "447700900001",
  "channel": "whatsapp"
}

Webhook para mensagens recebidas no WhatsApp v0.1

{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "timestamp": "2020-01-01T14:00:00.000Z",
  "to": {
    "type": "whatsapp",
    "number": "447700900000"
  },
  "from": {
    "type": "whatsapp",
    "number": "447700900001"
  },
  "message": {
    "content": {
      "type": "text",
      "text": "Hello From Vonage!"
    }
  }
}

Webhook de mensagens recebidas no WhatsApp v1

{
  "channel": "whatsapp",
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2020-01-01 14:00:00 UTC",
  "message_type": "text",
  "text": "Nexmo Verification code: 12345. Valid for 10 minutes.",
  "profile": {
    "name": "Jane Smith"
  },
  "context": {
    "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
    "message_from": "447700900000"
  }
}

Os exemplos acima são apenas alguns. Confira o especificação para obter um conjunto completo de campos para os diversos tipos de mensagens e webhooks.

Uso das Applications da Vonage para webhooks

Se você usar webhooks, para a v1, esses itens devem ser configurados dentro de um Aplicativo Vonage. Além disso, as Applications devem estar configuradas para usar a v1 como versão.

Um fluxo de trabalho básico para configurar isso por meio do Painel de controle seria o seguinte:

1. Crie um novo aplicativo na seção “Seus aplicativos” (atribuindo-lhe um nome adequado, etc.)
2. Na seção “Recursos”, ative a opção “Mensagens”
3. Ao ativar as mensagens, devem ser exibidos campos para webhooks de entrada e de status. Defina o webhook de entrada com a URL na qual você deseja receber os callbacks das Mensagens Interativas do WhatsApp.
4. Defina a versão da Messages API como v1 usando o menu suspenso
5. Clique em “Gerar novo pedido”

Uso de JWTs para autenticação ao utilizar um aplicativo da Vonage

Se você estiver configurando uma aplicação da Vonage, é importante saber que as aplicações da Vonage exigem o uso de JWT (JSON Web Tokens) para autenticar as solicitações à API. Em outras palavras, a autenticação HTTP Basic não é uma opção nesse caso. Saiba mais sobre os JWTs.

Vinculando números e canais sociais a uma Application da Vonage

Se você quiser disponibilizar determinados números e canais sociais em um aplicativo da Vonage, é preciso vincular esses números e canais sociais ao aplicativo. Isso pode ser feito por meio do Painel de controle. A partir do Página de Applications, selecione o aplicativo que você deseja vincular; você pode vincular números ao aplicativo na aba “Vincular números” e vincular canais sociais na aba “Vincular canais sociais”.

Recursos adicionais

Um dos motivos pelos quais você pode querer migrar para a v1, caso já esteja usando a v1, é aproveitar algumas das recursos adicionais que a v1 oferece, por exemplo Mensagens interativas do WhatsApp.