Rispondere a una conversazione Apple Messages

Invia una risposta testuale a un cliente che ha avviato una conversazione Apple Messages for Business, quindi verifica l'esito del messaggio.

Prerequisiti

Il tuo spazio di lavoro necessita di un business Apple approvato e di una conversazione aperta avviata dal relativo cliente. I pacchetti CLI e SDK con supporto AMB sono in attesa di pubblicazione. Questi comandi richiedono una build che include bird amb; controlla bird amb --help prima di procedere. Fino alla pubblicazione di un pacchetto con questi comandi, usa il riferimento API o la dashboard Apple Messages. Autenticati per la regione che ospita il tuo spazio di lavoro.

Usa Bash con jq e uuidgen installati. Autentica la CLI per quello spazio di lavoro. Le tue credenziali richiedono amb:read per ispezionare conversazioni e messaggi, amb:write per inviare e amb_management:read per ispezionare i business. Usa una conversazione di test esistente con il permesso di contattare il destinatario.

1. Seleziona il business e la conversazione

Esempio di codice

bird amb businesses list
bird amb conversations list

Ai prompt, incolla gli ID dei record selezionati da quegli elenchi:

Esempio di codice

read -r -p "Business record ID: " BUSINESS_ID
read -r -p "Conversation record ID: " CONVERSATION_ID
bird amb businesses get "$BUSINESS_ID"
bird amb conversations get "$CONVERSATION_ID"

Verifica che il business sia approvato, la conversazione sia aperta e che il business corrisponda al record selezionato. Estrai gli identificatori Apple utilizzati dalla richiesta di invio:

Esempio di codice

APPLE_BUSINESS_ID=$(bird amb businesses get "$BUSINESS_ID" --format json | jq -er '.apple_business_id')
OPAQUE_USER_ID=$(bird amb conversations get "$CONVERSATION_ID" --format json | jq -er '.opaque_user_id')

Un numero di telefono non può sostituire l'identificatore opaco del cliente per una risposta ordinaria.

2. Anteprima della risposta

Esempio di codice

bird amb send --from "$APPLE_BUSINESS_ID" --to "$OPAQUE_USER_ID" \
  --content '{"type":"text","body":"Your order is ready."}' --dry-run

Il comando stampa la richiesta senza inviarla. Verifica l'azienda, il destinatario e il testo del messaggio. Per esaminare la struttura completa della richiesta, esegui bird amb send --example. Un file JSON passato attraverso --body-file può includere campi opzionali come categoria, tag o lingua.

3. Invia il messaggio verificato

Esempio di codice

REQUEST_ID=$(uuidgen)
MESSAGE_ID=$(bird amb send --from "$APPLE_BUSINESS_ID" --to "$OPAQUE_USER_ID" \
  --content '{"type":"text","body":"Your order is ready."}' \
  --idempotency-key "$REQUEST_ID" --format json | jq -er '.id')
printf '%s\n' "$MESSAGE_ID"

Il comando genera un identificativo di richiesta e salva l'ID di risposta in MESSAGE_ID. L'invio mette in coda un messaggio fatturabile per l'elaborazione asincrona. Se riprovi, riutilizza REQUEST_ID; non eseguire di nuovo uuidgen per quella richiesta.

4. Esamina l'esito

Esempio di codice

bird amb get "$MESSAGE_ID"
bird amb list-events "$MESSAGE_ID"

sent registra l'accettazione da parte del gateway di Apple. Non stabilisce la consegna al dispositivo né che il cliente abbia letto il messaggio. Un invio fallito o incerto richiede un'indagine prima di inviare un altro messaggio. La prenotazione, l'ordine o altra azione commerciale deve attendere il proprio esito confermato.

Per aggiornamenti asincroni, iscriviti tramite webhook a amb.accepted, amb.sent, amb.send_failed, amb.rejected, amb.received o agli eventi del ciclo di vita della conversazione. Verifica le firme e deduplica le consegne tramite l'ID del webhook. Gli eventi possono arrivare in ordine diverso.

Usa MCP per lo stesso scambio

MCP espone gli strumenti corrispondenti: amb_businesses_list, amb_businesses_get, amb_conversations_list, amb_conversations_get, amb_send, amb_get e amb_list_events. Passa a amb_send gli stessi from, to e l'oggetto content, più idempotency_key quando riprovi una richiesta. Verifica il destinatario esatto e il contenuto prima di autorizzare la chiamata allo strumento.

Se uno strumento non è presente, controlla la versione del server e gli ambiti concessi alla tua connessione.

Limiti delle richieste

Apple Messages prevede per impostazione predefinita 10 richieste al minuto per organizzazione. Risposte, indicatori di digitazione e preparazione degli allegati condividono questa quota tra i tuoi spazi di lavoro e le credenziali in una regione. Il tuo piano o un limite cliente approvato possono aumentarla; contatta il supporto per un incremento. Chiedi all'amministratore della tua organizzazione o al supporto di confermare il tuo limite effettivo. Quando una richiesta restituisce 429, attendi l'intervallo Retry-After prima di riprovare.

Risoluzione dei problemi

Se il canale restituisce una risposta di risorsa non trovata, verifica che la risorsa appartenga allo spazio di lavoro autenticato. In caso di rifiuto per permessi insufficienti, controlla l'ambito del canale nelle credenziali. L'azienda deve essere approvata e la conversazione aperta perché possa ricevere una risposta; anche le soppressioni possono bloccare l'invio.

Se l'elaborazione rifiuta una richiesta accettata, esamina i relativi eventi e la configurazione di fatturazione. L'esito del gateway di un invio e l'esito commerciale del cliente sono separati. Non dedurre la consegna da una risposta API riuscita.

Passaggi successivi

Leggi la guida all'integrazione di Apple Messages per gli scambi nativi e gli esiti commerciali asincroni, oppure le indicazioni per la registrazione per preparare un'altra azienda.

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Guarda la guidaWebhooks done right: reliable delivery events Comprendi il concettoHow do I verify a webhook signature?Esplora la funzionalitàApple Messages for Business Segui il percorso di apprendimentoOperate messaging reliably

Prova l'esercitazione e ottieni un brief di implementazione