Mensagens de serviço WhatsApp

Uma mensagem de serviço é qualquer coisa que você envia e que não seja um template pré-aprovado: o conteúdo livre que uma empresa envia dentro de uma conversa aberta. POST /v1/whatsapp/messages carrega exatamente um dos nove tipos de conteúdo de mensagem de serviço, ou um template. Esta página cobre o que os nove tipos têm em comum; a página de cada tipo cobre seu formato no fio e seus próprios limites.

Uma solicitação carrega exatamente um entre template ou um desses nove campos. Uma solicitação que não carrega nenhum deles, ou que carrega mais de um, é recusada com um 422.

Uma mensagem de serviço, ou seja, qualquer um dos nove tipos acima, é entregue apenas dentro de uma janela de atendimento ao cliente de 24 horas aberta. O contato abre essa janela ao enviar uma mensagem ou ligar para o número da sua empresa, e cada nova mensagem dele reinicia o prazo para 24 horas.

Uma mensagem de serviço enviada para uma janela fechada é recusada na hora: a solicitação retorna um 422 E15044 WhatsAppServiceWindowClosed, e nada é criado ou cobrado. Envie um template aprovado em vez disso; ele alcança o contato independentemente da janela, e a resposta do contato a reabre. Uma janela que fecha no instante entre a aceitação e o despacho ainda falha, mas de forma assíncrona: a mensagem chega a failed com service_window_expired em last_error.

A verificação no momento da aceitação é feita com melhor esforço, não é uma garantia: a porta falha aberta, então uma falha de leitura ou de cache deixa o envio passar em vez de bloqueá-lo. Um 202 portanto não é prova de que a janela estava aberta quando o envio saiu; o sinal definitivo é o status da própria mensagem, não a resposta de aceitação.

Toda mensagem de serviço também exige from, um número que o seu espaço de trabalho possui. Os números gerenciados de Bird não suportam isso, então uma mensagem de serviço precisa de um número próprio conectado primeiro; veja Configuração de número de telefone.

Veja a janela de atendimento ao cliente para o ciclo de vida completo: como a janela abre, o que a reinicia e como ela é rastreada.

image, video, audio, sticker e document usam uma url apontando para um arquivo que WhatsApp busca no momento do envio, em vez de um arquivo que você envia para Bird. Bird verifica o formato da URL na aceitação, antes de qualquer enfileiramento:

Uma URL http é rejeitada com um 422 na aceitação, embora WhatsApp a buscasse sem problemas. Isso é política de Bird, não um limite que WhatsApp impõe.

Bird não verifica o tamanho do arquivo, seu tipo MIME nem se a URL está acessível. WhatsApp busca a URL quando despacha a mensagem, então uma URL assinada precisa continuar válida após esse momento, não apenas no momento em que você envia a solicitação; uma URL privada ou expirada falha quando WhatsApp tenta buscá-la. WhatsApp também armazena em cache uma URL buscada por aproximadamente 10 minutos, então reenviar a mesma URL dentro dessa janela serve o resultado da primeira busca em vez de buscar novamente.

Um envio de mídia segue o mesmo caminho assíncrono de qualquer mensagem WhatsApp: Bird retorna 202 e aceita a mensagem, depois WhatsApp busca a URL quando a despacha. Se essa busca falhar, a mensagem chega a failed com media_rejected em last_error, que é o 131053 da Meta por baixo.

media_rejected é um código genérico que cobre um arquivo grande demais, um 404, uma falha de DNS e um tipo MIME errado igualmente; Bird não o divide além disso, então não espere um código distinto por causa.

Um envio de mídia que falha de forma assíncrona ainda é cobrado. A cobrança acontece quando Bird processa o envio aceito, antes de WhatsApp buscar a URL, e não há caminho de reembolso depois que essa cobrança é registrada. Planeje de acordo: uma mensagem que falha depois em media_rejected já custou o mesmo que uma que foi entregue.

Uma mensagem de entrada carrega um dos mesmos nove tipos, então o campo que você lê corresponde ao tipo que o contato usou. Cartões de contato são lidos no mesmo campo contact_cards tanto quando o contato compartilhou um quanto quando você enviou um. Recebendo mensagens WhatsApp cobre a leitura de mensagens de entrada pela API, a busca da mídia que um contato enviou e o webhook whatsapp.received.