A API de histórico de mensagens está em beta. Na página Números, um
proprietário ou administrador da equipe seleciona Participar na linha do
beta de histórico de mensagens, revisa os termos e seleciona Aceitar e
participar. Até a equipe participar e o beta ser oferecido a ela, toda
solicitação de histórico retorna
403 permission_denied.Antes de começar
- O armazenamento hospedado de mensagens está ativado para o número. O
histórico contém apenas mensagens recebidas ou enviadas depois que o
armazenamento foi ativado. Para qualquer outro número, as solicitações de
histórico retornam
404 hms_not_enabled. Números de teste nunca têm histórico armazenado. - Sua equipe participa do beta. Participe pela linha do beta na página Números do Console. Sair do beta bloqueia novas leituras do histórico e não exclui as mensagens armazenadas.
- Você faz as chamadas do seu servidor com uma chave de organização ou um
token de projeto. Tokens de cliente são rejeitados com
403 permission_denied.
messages:read é um escopo novo. As credenciais criadas antes de ele existir,
incluindo as credenciais com acesso total, não o incluem. Crie uma credencial
que liste messages:read explicitamente.
Listar conversas
As conversas são ordenadas pela atividade mais recente, da mais nova para a mais antiga. Cada item traz a identidade da conversa, o tipo dela e um resumo da última mensagem armazenada. O resumo não tem o corpo da mensagem; leia as mensagens para obter o conteúdo.
Uma conversa só aparece enquanto pelo menos uma das mensagens dela estiver
retida. Uma conversa que recebe uma mensagem nova enquanto você percorre as
páginas vai para o topo da lista; ela não se repete nas páginas seguintes.
Listar as mensagens de uma conversa
Selecione a conversa peloid ou por um número de telefone E.164 (codifique o
+ na URL como %2B). Por padrão, as mensagens vêm da mais nova para a mais
antiga.
O objeto
whatsapp_ids guarda as referências do provedor que a Polymorfa
observou para a mensagem. Ele contém linked_devices, official_api ou os
dois. Use o id da Polymorfa para buscar uma mensagem ou enviar uma resposta.
O campo antigo whatsapp_id continua disponível temporariamente para as
integrações que ainda leem uma única referência.
Em um grupo, uma mensagem recebida inclui conversation.sender, o autor. Os
campos da mensagem são os mesmos de message.received: text, caption,
mimeType, filename, ptt, latitude, longitude, displayName,
title, reaction, reactionTo, edited, unavailable,
unavailableReason e pollOptions aparecem quando a mensagem armazenada os
tem. As mensagens enviadas pela API são armazenadas com o tipo e os
identificadores; o corpo delas não faz parte do registro armazenado.
Paginação
Os cursores são opacos. Devolva-os sem alterações, com o mesmo caminho e os mesmos filtros. Um cursor usado com outros filtros ou em outra conversa retorna400 invalid_parameter com param: "cursor"; comece de novo sem
cursor.
nextCursorcontinua naorderatual. Ele énullna última página, ehasMoreéfalse.previousCursorretorna a página anterior à atual. Ele énullna primeira página. Listas de conversas não têm cursor anterior.
Mídia
O histórico nunca retorna chaves de mídia do WhatsApp, caminhos de download ou URLs de armazenamento. Uma mensagem de imagem, vídeo, áudio, documento ou figurinha tem um arraymedia. Baixe os itens de mídia de Dispositivos
vinculados com Download linked media
usando uma credencial com media:read. Baixe a mídia armazenada de uma
mensagem da API oficial com Download stored message media
usando messages:read e media:read. Um ID de mídia armazenada não é um ID
de mídia vinculada. O array fica vazio quando a Polymorfa não tem uma cópia
desse arquivo que possa ser baixada.
Mídia da API oficial
O WhatsApp mantém a mídia de uma mensagem da API oficial por tempo limitado. Quando o armazenamento hospedado de mensagens retém uma mensagem desse tipo, a Polymorfa copia a mídia dela para a região de dados do número. A mensagem passa a ter um objetomediaRetrieval. Isso vale apenas para números conectados pela
API oficial; em um número que usa o Hybrid Link, a mídia da API oficial não é
copiada.
Todos os estados, exceto
pending, são finais. Um estado final diferente de
stored tem um reason, por exemplo provider_media_not_found ou
media_too_large; nesse caso, media fica vazio.
A Polymorfa armazena arquivos de até 32 MiB, e nunca acima do limite do próprio
WhatsApp para o tipo de mídia: 5 MB para imagens, 500 KB para figurinhas e
16 MB para áudio e vídeo. O WhatsApp disponibiliza um arquivo por 7 dias depois
de entregar a mensagem, então uma cópia que não for armazenada nesse prazo
termina como expired.
Baixe a cópia com Download stored message media
usando uma credencial com messages:read e media:read. O corpo da resposta é
o próprio arquivo, servido como anexo com o tipo de conteúdo armazenado. A
cópia é excluída junto com a mensagem quando o período de retenção dela
termina.
Retenção e região de dados
O histórico retorna apenas mensagens dentro do período de retenção do armazenamento hospedado do número, ou sob preservação legal (legal hold). Mensagens expiradas não são retornadas, e uma mensagem pode sumir entre duas páginas quando o período de retenção dela termina. Toda resposta bem-sucedida tem um cabeçalhoPolymorfa-Data-Region com o nome
da região que armazenou e serviu o histórico. O histórico é lido apenas na
região do número.
Erros
Consulte Erros para ver o formato completo dos erros.