Über die Apple Messages API antworten

Senden Sie über die öffentliche Bird API eine Textantwort in einer bestehenden Apple-Messages-Konversation. Prüfen Sie anschließend den Verarbeitungsstatus und empfangen Sie Kundenantworten.

Workspace und Anmeldedaten vorbereiten

Durchlaufen Sie den Dashboard-Schnellstart für die erste Konversation, um ein Unternehmen zu verbinden und eine Testkonversation zu öffnen. Ein Unternehmen mit dem Status Draft kann vor der Freigabe Testnachrichten senden. Normale Antworten verwenden die opake Apple-Kennung des Kunden; eine Telefonnummer kann sie nicht ersetzen.

Erstellen Sie einen Workspace-API-Schlüssel mit amb:read, amb:write und amb_management:read. Verwenden Sie Bash mit curl, jq und uuidgen. Führen Sie die folgenden Blöcke in einem Bash-Skript oder einer Shell aus. Die Fehlereinstellungen stoppen die Anleitung, wenn eine Anfrage oder Validierung fehlschlägt. Speichern Sie Anmeldedaten in Ihrer Umgebung statt in Quelldateien:

Codebeispiel

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

Der Schlüssel liefert den Workspace-Kontext. Siehe Regionen, wenn Sie eine Regionsinkompatibilität erhalten.

Geschäftskonto und Konversation auswählen

Listen Sie Geschäftskonten und Konversationen auf:

Codebeispiel

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'

Dieses Beispiel gilt für eine autorisierte Testkonversation; der Status Draft berechtigt nicht zum öffentlichen Start. Stoppen Sie, wenn eine der Prüfungen false zurückgibt oder eine Anfrage fehlschlägt. Wählen Sie Datensätze desselben Unternehmens. Nutzen Sie für weitere Ergebnisse die Cursor-Paginierung; die erste Seite ist nicht der gesamte Bestand.

Antwort prüfen und senden

Erstellen Sie die Anfrage mit apple_business_id als from und opaque_user_id als to:

Codebeispiel

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 .

Prüfen Sie Geschäftskonto, Empfänger und Text. Die nächste Anfrage reiht eine echte, potenziell kostenpflichtige Nachricht ein:

Codebeispiel

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')

Eine 202-Antwort bestätigt die Annahme zur asynchronen Verarbeitung. Behalten Sie REQUEST_ID und den unveränderten Body bei, wenn Sie dieselbe logische Anfrage erneut versuchen; ein neuer Schlüssel kann eine weitere Nachricht erzeugen. Siehe Idempotenz.

Verarbeitung prüfen und Antworten empfangen

Verwenden Sie Get message und List message events:

Codebeispiel

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 .

Konfigurieren Sie für asynchrone Aktualisierungen Webhooks für amb.accepted, amb.sent, amb.send_failed, amb.rejected, amb.received und die erforderlichen Konversations-Lifecycle-Ereignisse. Verifizieren Sie Signaturen, deduplizieren Sie Webhook-Zustellungen und tolerieren Sie Ereignisse in abweichender Reihenfolge. Rufen Sie die Nachricht ab, wenn Sie einen unklaren Zustand abgleichen.

Prüfen Sie bei amb.received den eingehenden Inhalt und ordnen Sie die Konversation Ihrer ausstehenden Kundenaufgabe zu. Verarbeiten Sie native Antworten anhand der gesendeten Bezeichner, sofern verfügbar; eine Time-Picker-Antwort kann ein ausgewähltes Label enthalten. Prüfen Sie das Buchungs-, Bestell- oder Fallsystem, bevor Sie eine irreversible Aktion ausführen oder deren Ergebnis bestätigen.

Den Nachrichteninhalt erweitern

Die Send-message-Referenz definiert text-, rich_link- und interactive-Inhalte. Interaktive Nachrichten umfassen Quick Replies, Listen, Time Picker, Formulare und benutzerdefinierte iMessage-Apps. Verwenden Sie die Designrichtlinien für native Nachrichten für das Kundenerlebnis.

Für von Apple erzeugte Vorschauen nutzen Sie den unterstützten Link-Ablauf im Dashboard. Quell-URLs für Medien werden bei der Verarbeitung abgerufen und können nach der Annahme fehlschlagen; beachten Sie die Medienanforderungen.

CLI- oder MCP-Installationen, die bird amb oder die entsprechenden amb_*-Tools bereitstellen, verwenden dieselbe Adressierungs- und Statussemantik. Prüfen Sie das installierte Befehls- oder Tool-Schema, bevor Sie es verwenden; diese Anleitung basiert direkt auf der öffentlichen HTTP-Schnittstellenbeschreibung.

Fehler beheben

Ein 404 kann auf eine unbekannte Konversation oder den falschen Workspace hinweisen. Ein 403 erfordert den Scope der Operation. Eine geschlossene Konversation oder eine nicht unterstützte native Interaktion kann 422 zurückgeben; der Kunde muss eine geschlossene Konversation erneut öffnen. Befolgen Sie bei 429 die Hinweise unter Retry-After und die gemeinsame Anleitung zu Ratenlimits.

Prüfen Sie nach der Annahme die Nachrichtenereignisse und -status auf Verarbeitungs- oder Abrechnungsfehler. Sent bedeutet Annahme durch das Apple-Gateway; es liefert keine Gerätezustellung oder Lesebestätigung. Messen Sie Geschäftsergebnisse separat.