# 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](/docs/api/reference/create-amb-message) 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

```sh
bird amb businesses list
bird amb conversations list
```

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

```sh
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:

```sh
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

```sh
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

```sh
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

```sh
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](/docs/guides/webhooks) 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](/docs/guides/apple-messages/api) per gli scambi nativi e gli esiti commerciali asincroni, oppure le [indicazioni per la registrazione](/docs/guides/apple-messages/registration) per preparare un'altra azienda.

## Related resources

- [Webhooks done right: reliable delivery events](/learn/basics/webhooks-done-right-reliable-delivery-events) (video)
- [How do I verify a webhook signature?](/explained/platform/how-do-i-verify-a-webhook-signature) (answer)
- [Apple Messages for Business](/apple-messages-api) (product)
- [Operate messaging reliably](/learn/paths/reliability) (course)

[Get an implementation brief](/learn/workspace?topic=webhooks)