Rispondere tramite API di Apple Messages

Invia una risposta di testo a una conversazione Apple Messages esistente tramite l’API pubblica di Bird, poi controlla lo stato di elaborazione e ricevi le risposte dei clienti.

Prepara lo spazio di lavoro e le credenziali

Completa la guida rapida alla prima conversazione nella dashboard per collegare un'azienda e aprire una conversazione di prova. Prima dell'approvazione, un'azienda in stato Testing può inviare messaggi di prova ai tuoi utenti di test. Le risposte ordinarie usano l'identificatore opaco Apple del cliente; un numero di telefono non può sostituirlo.

Crea una chiave API dello spazio di lavoro con amb:read, amb:write e amb_management:read. Usa Bash con curl, jq e uuidgen. Esegui i blocchi seguenti in un unico script Bash o shell. Le impostazioni di errore arrestano la procedura se una richiesta o una validazione fallisce. Conserva le credenziali nell'ambiente anziché nei file sorgente:

Esempio di codice

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 chiave fornisce il contesto dello spazio di lavoro. Consulta regioni se ricevi un errore di mismatch della regione.

Seleziona l'azienda e la conversazione

Elenca aziende e conversazioni:

Esempio di codice

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'

Questo esempio riguarda una conversazione di prova autorizzata; lo stato Testing non autorizza il lancio pubblico. Fermati se uno dei controlli restituisce false o se una richiesta non riesce. Seleziona i record della stessa azienda. Per altri risultati, usa la paginazione tramite cursore; la prima pagina non contiene l'inventario completo.

Rivedi e invia la risposta

Costruisci la richiesta usando apple_business_id come from e opaque_user_id come to:

Esempio di codice

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,text:{body:"We can help arrange your visit. Which day works for you?"}}')
printf '%s\n' "$REQUEST" | jq .

Verifica l'azienda, il destinatario e il testo. La prossima richiesta accoda un messaggio reale, potenzialmente fatturabile:

Esempio di codice

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

Una risposta 202 conferma l'accettazione per l'elaborazione asincrona. Quando riprovi quella richiesta logica, mantieni REQUEST_ID e il body invariato; generare un'altra chiave può creare un altro messaggio. Vedi idempotenza.

Ispeziona l'elaborazione e ricevi le risposte

Usa Get message e List message events:

Esempio di codice

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 .

Per gli aggiornamenti asincroni, configura i webhook per amb.accepted, amb.sent, amb.send_failed, amb.rejected, amb.received e per gli eventi richiesti del ciclo di vita della conversazione: amb.conversation_started, amb.conversation_closed e amb.conversation_reopened. Verifica le firme, deduplica le consegne dei webhook e gestisci gli eventi che arrivano fuori ordine. Recupera il messaggio quando devi riconciliare uno stato incerto.

Per amb.received, ispeziona il contenuto in arrivo e associa la conversazione al task del cliente in sospeso. Elabora le risposte native usando gli identificativi inviati, quando disponibili; la risposta di un time picker può contenere un'etichetta selezionata. Controlla il sistema di prenotazione, ordine o caso prima di eseguire un'azione irreversibile o confermarne il risultato.

Estendi il contenuto del messaggio

Il riferimento Send message definisce i contenuti text, rich_link e interactive. I messaggi interattivi includono risposte rapide, liste, time picker, moduli e app iMessage personalizzate. Usa la guida al design dei messaggi nativi per l'esperienza del cliente.

Per le anteprime generate da Apple, usa il flusso dei link supportato nella dashboard. Gli URL di origine dei contenuti multimediali vengono recuperati durante l’elaborazione e possono causare errori dopo l’accettazione; segui i requisiti multimediali.

Le installazioni CLI o MCP che espongono bird amb o i tool amb_* corrispondenti usano la stessa semantica di indirizzamento e stato. Controlla lo schema del comando o del tool installato prima di usarlo; questo walkthrough dipende direttamente dalle specifiche pubbliche HTTP.

Risolvi gli errori

Un 404 può indicare una conversazione sconosciuta o lo spazio di lavoro errato. Un 403 indica che serve l'ambito dell'operazione. Una conversazione chiusa o un'interazione nativa non supportata possono restituire 422; il cliente deve riaprire una conversazione chiusa.

Gli indicatori di digitazione usano la policy di limitazione delle richieste amb_typing; gli invii di messaggi usano amb_send. Le due capacità sono separate, quindi un indicatore di digitazione non consuma la capacità di invio dei messaggi. Regola il ritmo delle richieste in base agli header di risposta RateLimit-Policy e RateLimit. Per 429, segui Retry-After e le indicazioni condivise sulla limitazione delle richieste.

Dopo l'accettazione, ispeziona eventi e stati dei messaggi per individuare un errore di elaborazione o fatturazione. Sent indica l'accettazione da parte del gateway Apple; non fornisce una conferma di consegna al dispositivo né una conferma di lettura. Misura i risultati di business separatamente.