Envie imagens e arquivos no Apple Messages

Use um template de Image ou Document para enviar imagens de produtos, instruções ou um recibo em uma conversa aberta com o cliente. Bird busca o arquivo de origem e o prepara para a Apple durante o processamento da mensagem.

Prepare um arquivo acessível

Hospede o arquivo desejado em uma URL HTTPS pública que possa ser acessada sem cookies de navegador ou login. Use um arquivo específico para a finalidade que seja seguro expor nessa URL. Uma página de pré-visualização de drive privado não é uma URL direta de arquivo.

A referência de envio de mensagem define as restrições de mídia:

Mantenha a URL disponível enquanto o processamento é concluído. Uma URL assinada que expira cedo demais pode causar uma falha depois que a mensagem foi aceita. Teste a URL sem um navegador autenticado e confirme que ela retorna o arquivo real em vez de uma página HTML.

Configure o template

1. Abra Templates e escolha New template > Image ou Document.
2. Em Content, dê ao rascunho um Template name e insira uma Message útil que explique o anexo.
3. Em Apple delivery, defina Attachment URL, File name e Media type. Por exemplo, um PDF usa um nome de arquivo .pdf e application/pdf.
4. Selecione o negócio em Personalization e salve o rascunho.
5. Prepare e revise a mensagem, verificando o cliente e o arquivo reais antes de enviar.

A arte de pré-visualização incluída no pacote não é uma fonte de anexo para um envio real. Forneça a URL desejada explicitamente.

Faça o upload uma vez e reutilize com attachment_id

O fluxo de template acima envia por source_url a cada vez, então a Bird busca o arquivo novamente em cada envio. Quando você envia pela API, pode fazer o upload de um arquivo uma vez com Fazer upload de um anexo e reutilizá-lo em envios posteriores, sem buscar o arquivo de novo.

Chame POST /v1/amb/attachments com uma chave API do workspace que tenha amb:write, um cabeçalho Idempotency-Key, exigido pela solicitação, e um corpo com from (o Apple Business ID da empresa remetente) e uma parte file de até 25.000.000 bytes ou uma source_url de até 99.999.999 bytes. A resposta retorna um id começando com aat_. Cada chamada faz upload de um novo anexo, mesmo para um arquivo que você já enviou antes. Repetir com a mesma Idempotency-Key retorna o primeiro resultado sem enviar de novo, então use uma chave nova para cada arquivo que você quiser enviar. Em um envio posterior, defina content.attachments[].attachment_id com esse ID em vez de source_url. Um anexo recebido carrega o mesmo tipo de ID: leia-o em data.message.content.attachments[].attachment_id no evento de webhook amb.received e reenvie-o ao cliente sem baixar e reenviar o arquivo você mesmo.

expires_at em um anexo é a estimativa da Bird de quando a Apple deixa de manter o arquivo, não uma garantia: a Apple documenta cerca de 30 dias de disponibilidade, renovados sempre que uma mensagem posterior reutiliza a referência. Um envio com um attachment_id cujo expires_at está a menos de 24 horas de distância é recusado antes de chegar à Apple; se isso acontecer, faça o upload do arquivo novamente ou envie-o por source_url. Um template não pode armazenar attachment_id, porque um template tem vida longa e um ID de anexo não.

Verifique o resultado

Inspecione a mensagem enviada e os eventos, depois abra o anexo em um dispositivo de teste Apple autorizado. Verifique a legibilidade, o nome do arquivo e se o conteúdo faz sentido sem o site ao redor.

Se a mensagem falhar após a aceitação, inspecione o erro antes de alterar o template. Causas comuns incluem uma URL inacessível, um tipo de mídia inesperado, um arquivo acima do limite de tamanho ou dados PNG inválidos. Alterar a extensão de um arquivo não converte seu formato.

Para baixar um anexo recebido no dashboard, selecione o nome do arquivo na transcrição da conversa. Você precisa de acesso de leitura ao Apple Messages no espaço de trabalho.

Para obter um arquivo pela API, use Baixar um anexo com o attachment_id em content.attachments[] da mensagem, ou Obter um anexo de mensagem com data.message.id do evento de webhook amb.received e a posição, com base zero, do anexo no array content.attachments dessa mensagem. Em ambos os casos, autentique-se com uma chave API do workspace que tenha amb:read; a resposta contém os bytes do arquivo descriptografado. Baixe o arquivo assim que a mensagem chegar e guarde sua própria cópia, porque a disponibilidade após o período de retenção da Apple não é garantida.