Odpowiedz na konwersację Apple Messages

Wyślij odpowiedź tekstową do klienta, który rozpoczął konwersację Apple Messages for Business, a następnie sprawdź wynik wiadomości.

Wymagania wstępne

Twój obszar roboczy potrzebuje aktywnego konta biznesowego Apple i otwartej konwersacji rozpoczętej przez klienta. Pakiety CLI i SDK z obsługą AMB oczekują na publikację. Te polecenia wymagają kompilacji zawierającej bird amb; przed kontynuowaniem sprawdź bird amb --help. Dopóki pakiet z tymi poleceniami nie zostanie opublikowany, użyj dokumentacji API lub panelu Apple Messages. Uwierzytelnij się w regionie, w którym znajduje się Twój obszar roboczy.

Użyj Bash z zainstalowanymi jq i uuidgen. Uwierzytelnij CLI dla tego obszaru roboczego. Twoje poświadczenie wymaga amb:read do przeglądania konwersacji i wiadomości, amb:write do wysyłania oraz amb_management:read do przeglądania kont biznesowych. Użyj istniejącej konwersacji testowej z uprawnieniem do kontaktu z jej odbiorcą.

1. Wybierz firmę i konwersację

Przykład kodu

bird amb business-accounts list
bird amb conversations list

W odpowiedzi na monity wklej identyfikatory rekordów wybrane z tych list:

Przykład kodu

read -r -p "Business record ID: " BUSINESS_ID
read -r -p "Conversation record ID: " CONVERSATION_ID
bird amb business-accounts get "$BUSINESS_ID"
bird amb conversations get "$CONVERSATION_ID"

Sprawdź, czy konto jest aktywne, konwersacja otwarta, a jej business_account_id odpowiada wybranemu rekordowi. Wyodrębnij identyfikatory Apple używane w żądaniu wysyłki:

Przykład kodu

APPLE_BUSINESS_ID=$(bird amb business-accounts get "$BUSINESS_ID" --format json | jq -er '.apple_business_id')
OPAQUE_USER_ID=$(bird amb conversations get "$CONVERSATION_ID" --format json | jq -er '.opaque_user_id')

Numer telefonu nie może zastąpić nieprzejrzystego identyfikatora klienta w zwykłej odpowiedzi.

2. Wyświetl podgląd odpowiedzi

Przykład kodu

bird amb send --from "$APPLE_BUSINESS_ID" --to "$OPAQUE_USER_ID" \
  --content '{"type":"text","body":"Your order is ready."}' --dry-run

Polecenie wyświetla żądanie bez jego wysyłania. Sprawdź firmę, odbiorcę i treść wiadomości. Aby zobaczyć pełną strukturę żądania, uruchom bird amb send --example. Plik JSON przekazany przez --body-file może zawierać opcjonalne pola, takie jak kategoria, tagi lub język.

3. Wyślij sprawdzoną wiadomość

Przykład kodu

REQUEST_ID=$(uuidgen)
MESSAGE_ID=$(bird amb send --from "$APPLE_BUSINESS_ID" --to "$OPAQUE_USER_ID" \
  --content '{"type":"text","body":"Your order is ready."}' \
  --idempotency-key "$REQUEST_ID" --format json | jq -er '.id')
printf '%s\n' "$MESSAGE_ID"

Polecenie generuje identyfikator żądania i zapisuje identyfikator odpowiedzi w MESSAGE_ID. Wysyłanie kolejkuje płatną wiadomość do przetwarzania asynchronicznego. Jeśli ponawiasz próbę, użyj ponownie REQUEST_ID; nie uruchamiaj uuidgen ponownie dla tego żądania.

4. Sprawdź wynik

Przykład kodu

bird amb get "$MESSAGE_ID"
bird amb list-events "$MESSAGE_ID"

sent rejestruje przyjęcie przez bramkę Apple. Nie potwierdza dostarczenia na urządzenie ani tego, że klient przeczytał wiadomość. Nieudane lub niepewne wysłanie wymaga zbadania przed przesłaniem kolejnej wiadomości. Twoja rezerwacja, zamówienie lub inna akcja biznesowa musi poczekać na własne potwierdzone zakończenie.

Aby otrzymywać aktualizacje asynchroniczne, zasubskrybuj przez webhooki zdarzenia amb.accepted, amb.sent, amb.send_failed, amb.rejected, amb.received lub zdarzenia cyklu życia konwersacji. Weryfikuj podpisy i deduplikuj dostarczenia po identyfikatorze webhooka. Zdarzenia mogą przychodzić w dowolnej kolejności.

Użyj MCP do tej samej wymiany

MCP udostępnia odpowiednie narzędzia: amb_business_accounts_list, amb_business_accounts_get, amb_conversations_list, amb_conversations_get, amb_send, amb_get i amb_list_events. Przekaż do amb_send te same from, to i obiekt content, a przy ponawianiu żądania także idempotency_key. Przed autoryzacją wywołania narzędzia zweryfikuj dokładnego odbiorcę i treść.

Jeśli narzędzie jest niedostępne, sprawdź wersję serwera i zakresy uprawnień przyznane Twojemu połączeniu.

Limity żądań

Apple Messages domyślnie pozwala na 10 żądań na minutę na organizację. Odpowiedzi, wskaźniki pisania i przygotowywanie załączników dzielą ten limit między Twoje obszary robocze i poświadczenia w danym regionie. Twój plan lub zatwierdzony limit klienta mogą go podnieść; skontaktuj się ze wsparciem, aby uzyskać zwiększenie. Poproś administratora organizacji lub wsparcie o potwierdzenie obowiązującego limitu. Gdy żądanie zwróci 429, poczekaj przez interwał Retry-After przed ponowieniem próby.

Rozwiązywanie problemów

Jeśli kanał zwraca odpowiedź „nie znaleziono

Jeśli przetwarzanie odrzuci zaakceptowane żądanie, sprawdź jego zdarzenia i konfigurację rozliczeń. Wynik bramki wysyłki i wynik biznesowy klienta to osobne rzeczy. Nie wnioskuj o dostarczeniu na podstawie pomyślnej odpowiedzi API.

Następne kroki

Przeczytaj przewodnik integracji Apple Messages, aby poznać natywną wymianę wiadomości i asynchroniczne wyniki biznesowe, lub wskazówki dotyczące rejestracji, aby przygotować kolejną firmę.

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Obejrzyj przewodnikWebhooks done right: reliable delivery events Zrozum koncepcjęHow do I verify a webhook signature?Poznaj możliwościApple Messages for Business Podążaj ścieżką naukiOperate messaging reliably

Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy