Odpowiedź przez Apple Messages API

Wyślij odpowiedź tekstową do istniejącej konwersacji Apple Messages przez publiczne Bird API, a następnie sprawdź stan przetwarzania i odbieraj odpowiedzi klientów.

Przygotuj obszar roboczy i poświadczenie

Przejdź szybki start pierwszej konwersacji w panelu, aby połączyć firmę i otworzyć konwersację testową. Firma ze statusem Draft może wysyłać wiadomości testowe przed zatwierdzeniem. Zwykłe odpowiedzi używają nieprzezroczystego identyfikatora Apple klienta; numer telefonu nie może go zastąpić.

Utwórz klucz API obszaru roboczego z amb:read, amb:write i amb_management:read. Użyj Bash z curl, jq i uuidgen. Uruchom poniższe bloki w jednym skrypcie Bash lub powłoce. Ustawienia obsługi błędów zatrzymają przewodnik, jeśli żądanie lub walidacja się nie powiedzie. Przechowuj poświadczenia w zmiennych środowiskowych, a nie w plikach źródłowych:

Przykład kodu

set -euo pipefail
read -r -s -p "Bird API key: " BIRD_API_KEY
printf '\n'
export BIRD_API_KEY
case "$BIRD_API_KEY" in
  bk_eu1_*) BIRD_API_URL=https://eu1.platform.bird.com ;;
  bk_us1_*) BIRD_API_URL=https://us1.platform.bird.com ;;
  *) printf 'Use a workspace key for a supported region.\n' >&2; exit 1 ;;
esac

Klucz dostarcza kontekst obszaru roboczego. Zobacz regiony, jeśli otrzymujesz błąd niezgodności regionu.

Wybierz firmę i konwersację

Wyświetl listę firm i konwersacji:

Przykład kodu

curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/business-accounts" \
  -H "Authorization: Bearer $BIRD_API_KEY" | jq .
curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/conversations" \
  -H "Authorization: Bearer $BIRD_API_KEY" | jq .
read -r -p "Bird business record ID: " BUSINESS_ID
read -r -p "Bird conversation record ID: " CONVERSATION_ID
BUSINESS=$(curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/business-accounts/$BUSINESS_ID" \
  -H "Authorization: Bearer $BIRD_API_KEY")
CONVERSATION=$(curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/conversations/$CONVERSATION_ID" \
  -H "Authorization: Bearer $BIRD_API_KEY")
printf '%s' "$BUSINESS" | jq -e '.status == "pending" or .status == "active"'
printf '%s' "$CONVERSATION" | jq -e --arg business "$BUSINESS_ID" \
  '.status == "open" and .business_account_id == $business'

Ten przykład dotyczy autoryzowanej konwersacji testowej; status Draft nie uprawnia do publicznego uruchomienia. Zatrzymaj się, jeśli którakolwiek kontrola zwróci false lub żądanie się nie powiedzie. Wybieraj rekordy tej samej firmy. Aby uzyskać więcej wyników, użyj paginacji kursorowej; pierwsza strona nie stanowi pełnego wykazu.

Sprawdź i wyślij odpowiedź

Zbuduj żądanie, używając apple_business_id jako from i opaque_user_id jako to:

Przykład kodu

APPLE_BUSINESS_ID=$(printf '%s' "$BUSINESS" | jq -er '.apple_business_id')
OPAQUE_USER_ID=$(printf '%s' "$CONVERSATION" | jq -er '.opaque_user_id')
REQUEST=$(jq -n --arg from "$APPLE_BUSINESS_ID" --arg to "$OPAQUE_USER_ID" \
  '{from:$from,to:$to,content:{type:"text",body:"We can help arrange your visit. Which day works for you?"}}')
printf '%s\n' "$REQUEST" | jq .

Sprawdź firmę, odbiorcę i treść. Następne żądanie kolejkuje prawdziwą, potencjalnie płatną wiadomość:

Przykład kodu

REQUEST_ID=$(uuidgen)
RESPONSE=$(curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $REQUEST_ID" \
  --data "$REQUEST")
printf '%s\n' "$RESPONSE" | jq .
MESSAGE_ID=$(printf '%s' "$RESPONSE" | jq -er '.id')

Odpowiedź 202 potwierdza przyjęcie do przetwarzania asynchronicznego. Przy ponawianiu tego samego żądania logicznego zachowaj REQUEST_ID i niezmienioną treść; wygenerowanie nowego klucza może utworzyć kolejną wiadomość. Zobacz idempotentność.

Sprawdź przetwarzanie i odbierz odpowiedzi

Użyj Get message i List message events:

Przykład kodu

curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $BIRD_API_KEY" | jq .
curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/messages/$MESSAGE_ID/events" \
  -H "Authorization: Bearer $BIRD_API_KEY" | jq .

Aby otrzymywać aktualizacje asynchroniczne, skonfiguruj webhooki dla amb.accepted, amb.sent, amb.send_failed, amb.rejected, amb.received oraz wymaganych zdarzeń cyklu życia konwersacji. Weryfikuj sygnatury, deduplikuj dostarczenia webhooków i toleruj zdarzenia przychodzące w zmienionej kolejności. Pobierz wiadomość, gdy uzgadniasz niepewny stan.

Dla amb.received sprawdź treść przychodzącą i dopasuj konwersację do oczekującego zadania klienta. Przetwarzaj natywne odpowiedzi, korzystając z wysłanych identyfikatorów, gdy są dostępne; odpowiedź z selektora czasu może zawierać wybraną etykietę. Sprawdź system rezerwacji, zamówień lub zgłoszeń przed podjęciem nieodwracalnej akcji lub potwierdzeniem jej wyniku.

Rozszerz treść wiadomości

Dokumentacja Send message definiuje treść text, rich_link i interactive. Wiadomości interaktywne obejmują szybkie odpowiedzi, listy, selektory czasu, formularze i niestandardowe aplikacje iMessage. Skorzystaj z wytycznych projektowania natywnych wiadomości dla doświadczenia klienta.

W przypadku podglądów generowanych przez Apple użyj obsługiwanego procesu tworzenia linków w panelu. Źródłowe adresy URL multimediów są pobierane podczas przetwarzania i mogą zawieść po przyjęciu wiadomości; przestrzegaj wymagań dotyczących multimediów.

Instalacje CLI lub MCP, które udostępniają bird amb lub odpowiadające im narzędzia amb_*, używają tej samej semantyki adresowania i statusów. Sprawdź schemat zainstalowanej komendy lub narzędzia przed użyciem; ten przewodnik zależy bezpośrednio od publicznego kontraktu HTTP.

Rozwiąż błędy

404 może wskazywać nieznaną konwersację lub niewłaściwy obszar roboczy. 403 wymaga zakresu uprawnień operacji. Zamknięta konwersacja lub nieobsługiwana natywna interakcja może zwrócić 422; klient musi ponownie otworzyć zamkniętą konwersację. W przypadku 429 postępuj zgodnie z Retry-After i wspólnymi wytycznymi dotyczącymi limitów liczby żądań.

Po zaakceptowaniu sprawdź zdarzenia i statusy wiadomości pod kątem błędów przetwarzania lub rozliczeń. Sent oznacza przyjęcie przez bramkę Apple; nie jest to potwierdzenie dostarczenia na urządzenie ani potwierdzenie odczytu. Mierz wyniki biznesowe osobno.