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’attività e aprire una conversazione di prova. Un’attività in stato Draft può inviare messaggi di prova prima dell’approvazione. 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 Draft non autorizza il lancio pubblico. Fermati se uno dei controlli restituisce false o se una richiesta non riesce. Seleziona i record della stessa attività. 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,content:{type:"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 idempotency.

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 gli eventi del ciclo di vita della conversazione richiesti. Verifica le firme, deduplica le consegne dei webhook e tollera eventi fuori ordine. Recupera il messaggio quando riconcili 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 richiede l'ambito dell'operazione. Una conversazione chiusa o un'interazione nativa non supportata possono restituire 422; il cliente deve riaprire una conversazione chiusa. 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.