Répondre via le API Apple Messages

Envoyez une réponse textuelle dans une conversation Apple Messages existante via l’API publique de Bird, puis inspectez son état de traitement et recevez les réponses des clients.

Préparer l'espace de travail et les identifiants

Suivez le guide de démarrage rapide pour la première conversation dans le tableau de bord pour connecter une entreprise et ouvrir une conversation de test. Une entreprise au statut Draft peut envoyer des messages de test avant son approbation. Les réponses ordinaires utilisent l’identifiant opaque Apple du client ; un numéro de téléphone ne peut pas le remplacer.

Créez une clé API d'espace de travail avec amb:read, amb:write et amb_management:read. Utilisez Bash avec curl, jq et uuidgen. Exécutez les blocs suivants dans un seul script Bash ou shell. Les paramètres d'erreur arrêtent la procédure si une requête ou une validation échoue. Conservez les identifiants dans votre environnement plutôt que dans des fichiers source :

Exemple de code

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

La clé fournit le contexte de l'espace de travail. Consultez régions si vous recevez une erreur de non-correspondance de région.

Sélectionner l'entreprise et la conversation

Listez les entreprises et les conversations :

Exemple de code

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'

Cet exemple concerne une conversation de test autorisée ; le statut Draft n’autorise pas le lancement public. Arrêtez-vous si l’une des vérifications renvoie false ou si une requête échoue. Sélectionnez les enregistrements de la même entreprise. Pour obtenir d’autres résultats, utilisez la pagination par curseur ; la première page ne contient pas l’inventaire complet.

Vérifier et envoyer la réponse

Construisez la requête en utilisant apple_business_id comme from et opaque_user_id comme to :

Exemple de code

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 .

Vérifiez l'entreprise, le destinataire et le texte. La requête suivante met en file d'attente un message réel, potentiellement facturable :

Exemple de code

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

Une réponse 202 confirme l'acceptation pour traitement asynchrone. Conservez REQUEST_ID et le corps inchangé lorsque vous réessayez cette requête logique ; générer une autre clé peut créer un autre message. Voir idempotence.

Inspecter le traitement et recevoir les réponses

Utilisez Get message et List message events :

Exemple de code

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 .

Pour les mises à jour asynchrones, configurez des webhooks pour amb.accepted, amb.sent, amb.send_failed, amb.rejected, amb.received et les événements de cycle de vie de conversation requis. Vérifiez les signatures, dédupliquez les livraisons de webhooks et tolérez les événements reçus dans le désordre. Récupérez le message pour réconcilier un état incertain.

Pour amb.received, inspectez le contenu entrant et associez la conversation à votre tâche client en attente. Traitez les réponses natives à l'aide des identifiants envoyés lorsqu'ils sont disponibles ; une réponse de sélection d'horaire peut contenir un libellé sélectionné. Vérifiez le système de réservation, de commande ou de dossier avant d'effectuer une action irréversible ou d'en confirmer le résultat.

Enrichir le contenu du message

La référence Send message définit le contenu text, rich_link et interactive. Les messages interactifs comprennent les réponses rapides, les listes, les sélecteurs d'horaire, les formulaires et les applications iMessage personnalisées. Utilisez les recommandations de conception des messages natifs pour l'expérience client.

Pour les aperçus générés par Apple, utilisez le parcours de liens pris en charge dans le tableau de bord. Les URL sources des médias sont récupérées lors du traitement et peuvent échouer après l’acceptation ; suivez les exigences relatives aux médias.

Les installations CLI ou MCP qui exposent bird amb ou les outils amb_* correspondants utilisent la même sémantique d'adressage et de statut. Vérifiez le schéma de la commande ou de l'outil installé avant de l'utiliser ; ce guide dépend directement du contrat HTTP public.

Résoudre les erreurs

Une réponse 404 peut indiquer une conversation inconnue ou un espace de travail incorrect. Une réponse 403 exige la portée de l'opération. Une conversation fermée ou une interaction native non prise en charge peut renvoyer 422 ; le client doit rouvrir une conversation fermée. Pour 429, suivez Retry-After et les conseils partagés sur la limitation du débit.

Après l'acceptation, inspectez les événements et statuts de message pour détecter un échec de traitement ou de facturation. Sent correspond à l'acceptation par la passerelle Apple ; il ne fournit ni accusé de réception sur l'appareil ni confirmation de lecture. Mesurez les résultats métier séparément.