Wysyłanie obrazów i plików w Apple Messages

Użyj szablonu Image lub Document, aby wysłać zdjęcia produktów, instrukcje lub paragon w otwartej rozmowie z klientem. Bird pobiera plik źródłowy i przygotowuje go dla Apple podczas przetwarzania wiadomości.

Przygotuj dostępny plik

Umieść docelowy plik pod publicznym adresem URL HTTPS, który można pobrać bez plików cookie przeglądarki i bez logowania. Użyj pliku przeznaczonego do tego celu, który można bezpiecznie udostępnić pod tym adresem URL. Strona podglądu dysku prywatnego nie jest bezpośrednim adresem URL pliku.

Dokumentacja send-message definiuje ograniczenia multimediów:

Utrzymuj URL dostępny do zakończenia przetwarzania. Podpisany URL, który wygasa zbyt szybko, może spowodować błąd po zaakceptowaniu wiadomości. Przetestuj URL bez zalogowanej przeglądarki i potwierdź, że zwraca właściwy plik, a nie stronę HTML.

Skonfiguruj szablon

1. Otwórz Szablony i wybierz Nowy szablon > Obraz lub Dokument.
2. W sekcji Treść nadaj wersji roboczej Nazwę szablonu i wpisz przydatną Wiadomość opisującą załącznik.
3. W sekcji Apple delivery ustaw Attachment URL, File name i Media type. Na przykład plik PDF używa nazwy pliku .pdf i application/pdf.
4. Wybierz firmę w sekcji Personalizacja, a następnie zapisz wersję roboczą.
5. Przygotuj i sprawdź wiadomość, weryfikując właściwego klienta i plik przed wysłaniem.

Dołączona grafika podglądu nie jest źródłem załącznika do rzeczywistej wysyłki. Podaj zamierzony URL jawnie.

Prześlij raz i używaj ponownie z attachment_id

Opisany wyżej przepływ szablonu za każdym razem wysyła przez source_url, więc Bird pobiera plik ponownie przy każdym wysłaniu. Gdy zamiast tego wysyłasz przez API, możesz przesłać plik raz za pomocą Prześlij załącznik i używać go ponownie w kolejnych wysyłkach, co eliminuje ponowne pobieranie.

Wywołaj POST /v1/amb/attachments z kluczem API obszaru roboczego, który ma uprawnienie amb:write, z wymaganym nagłówkiem Idempotency-Key oraz treścią zawierającą from (Apple Business ID firmy wysyłającej) i albo część file o rozmiarze do 25 000 000 bajtów, albo source_url o rozmiarze do 99 999 999 bajtów. Odpowiedź zwraca id zaczynające się od aat_. Każde wywołanie przesyła nowy załącznik, nawet dla pliku przesłanego wcześniej. Ponowienie z tym samym Idempotency-Key zwraca pierwszy wynik bez ponownego przesyłania, dlatego użyj nowego klucza dla każdego pliku, który chcesz przesłać. Przy kolejnej wysyłce ustaw content.attachments[].attachment_id na ten identyfikator zamiast source_url. Otrzymany załącznik ma identyfikator tego samego rodzaju: odczytaj go z data.message.content.attachments[].attachment_id w zdarzeniu webhook amb.received i odeślij go klientowi bez samodzielnego pobierania i ponownego przesyłania pliku.

expires_at w załączniku to szacunek Bird dotyczący tego, kiedy Apple przestanie przechowywać plik, a nie gwarancja: Apple dokumentuje dostępność przez około 30 dni, odnawianą za każdym razem, gdy kolejna wiadomość ponownie używa odwołania. Wysyłka z attachment_id, którego expires_at nastąpi za mniej niż 24 godziny, jest odrzucana, zanim dotrze do Apple; jeśli tak się stanie, prześlij plik ponownie lub wyślij go przez source_url. Szablon nie może przechowywać attachment_id, ponieważ szablon jest długotrwały, a identyfikator załącznika nie.

Sprawdź wynik

Sprawdź wysłaną wiadomość i zdarzenia, a następnie otwórz załącznik na autoryzowanym urządzeniu testowym Apple. Sprawdź czytelność, nazwę pliku oraz czy treść ma sens bez otaczającej strony internetowej.

Jeśli wiadomość zakończy się błędem po zaakceptowaniu, sprawdź jej błąd przed zmianą szablonu. Typowe przyczyny to niedostępny URL, nieoczekiwany typ mediów, plik przekraczający limit rozmiaru lub nieprawidłowe dane PNG. Zmiana rozszerzenia pliku nie konwertuje jego formatu.

Aby pobrać przychodzący załącznik w panelu, wybierz jego nazwę pliku w transkrypcji rozmowy. Potrzebujesz dostępu do odczytu Apple Messages w obszarze roboczym.

Aby pobrać plik przez API, użyj Pobierz załącznik z attachment_id z content.attachments[] wiadomości, albo Pobierz załącznik wiadomości z data.message.id ze zdarzenia webhook amb.received oraz liczoną od zera pozycją załącznika w tablicy content.attachments tej wiadomości. W obu przypadkach uwierzytelnij się kluczem API obszaru roboczego, który ma uprawnienie amb:read; odpowiedź zawiera odszyfrowane bajty pliku. Pobierz plik, gdy tylko wiadomość dotrze, i zachowaj własną kopię, ponieważ dostępność po okresie przechowywania Apple nie jest gwarantowana.