# Responder a uma conversa do Apple Messages

Envie uma resposta de texto a um cliente que iniciou uma conversa no Apple Messages for Business e inspecione o resultado da mensagem.

## Pré-requisitos

Seu espaço de trabalho precisa de um negócio Apple aprovado e de uma conversa aberta iniciada pelo cliente. Os pacotes CLI e SDK com suporte a AMB aguardam publicação. Esses comandos exigem um build que inclua `bird amb`; verifique `bird amb --help` antes de continuar. Até que um pacote com esses comandos seja publicado, use a [referência do API](/docs/api/reference/create-amb-message) ou o painel do Apple Messages. Autentique-se na região que hospeda seu espaço de trabalho.

Use Bash com `jq` e `uuidgen` instalados. Autentique o CLI nesse espaço de trabalho. Sua credencial precisa de `amb:read` para inspecionar conversas e mensagens, `amb:write` para enviar e `amb_management:read` para inspecionar negócios. Use uma conversa de teste existente com permissão para contatar o destinatário.

## 1. Selecione o negócio e a conversa

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

Nos prompts, cole os IDs de registro que você selecionou nessas listas:

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

Verifique se o negócio está aprovado, a conversa está aberta e o negócio dela corresponde ao registro selecionado. Extraia os identificadores Apple que a solicitação de envio usa:

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

Um número de telefone não pode substituir o identificador opaco do cliente em uma resposta comum.

## 2. Visualize a resposta

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

O comando imprime a solicitação sem enviá-la. Verifique o negócio, o destinatário e o texto da mensagem. Para inspecionar o formato completo da solicitação, execute `bird amb send --example`. Um arquivo JSON passado por `--body-file` pode incluir campos opcionais como categoria, tags ou localidade.

## 3. Enviar a mensagem revisada

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

O comando gera um identificador de solicitação e salva o ID da resposta em `MESSAGE_ID`. O envio enfileira uma mensagem faturável para processamento assíncrono. Se você tentar novamente, reutilize `REQUEST_ID`; não execute `uuidgen` outra vez para essa solicitação.

## 4. Inspecionar o resultado

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

`sent` registra a aceitação pelo gateway da Apple. Isso não confirma a entrega no dispositivo nem que o cliente leu a mensagem. Um envio com falha ou incerto precisa de investigação antes de outra mensagem ser enviada. Sua reserva, pedido ou outra ação de negócio deve aguardar seu próprio resultado confirmado.

Para atualizações assíncronas, inscreva-se por meio de [webhooks](/docs/guides/webhooks) em `amb.accepted`, `amb.sent`, `amb.send_failed`, `amb.rejected`, `amb.received` ou nos eventos de ciclo de vida da conversa. Verifique assinaturas e elimine entregas duplicadas pelo ID do webhook. Os eventos podem chegar fora de ordem.

## Use MCP para a mesma troca

MCP expõe as ferramentas correspondentes: `amb_businesses_list`, `amb_businesses_get`, `amb_conversations_list`, `amb_conversations_get`, `amb_send`, `amb_get` e `amb_list_events`. Forneça a `amb_send` o mesmo `from`, `to` e objeto `content`, além de `idempotency_key` ao tentar novamente uma solicitação. Revise o destinatário exato e o conteúdo antes de autorizar a chamada da ferramenta.

Se uma ferramenta estiver ausente, verifique a versão do servidor e os escopos concedidos à sua conexão.

## Limites de solicitação

O Apple Messages tem como padrão 10 solicitações por minuto por organização. Respostas, indicadores de digitação e preparação de anexos compartilham essa cota entre seus espaços de trabalho e credenciais em uma região. Seu plano ou um limite de cliente aprovado pode aumentá-la; entre em contato com o suporte para um aumento. Pergunte ao administrador da sua organização ou ao suporte para confirmar seu limite efetivo. Quando uma solicitação retornar `429`, aguarde o intervalo de `Retry-After` antes de tentar novamente.

## Solução de problemas

Se o canal retornar uma resposta de não encontrado, verifique se o recurso pertence ao espaço de trabalho autenticado. Para uma recusa de permissão, verifique o escopo de canal da credencial. O negócio precisa estar aprovado e a conversa aberta para receber uma resposta; supressões também podem bloquear o envio.

Se o processamento rejeitar uma solicitação já aceita, inspecione os eventos e a configuração de cobrança. O resultado do gateway de envio e o resultado comercial do cliente são independentes. Não presuma entrega a partir de uma resposta bem-sucedida de API.

## Próximos passos

Leia o [guia de integração do Apple Messages](/docs/guides/apple-messages/api) para trocas nativas e resultados comerciais assíncronos, ou as [orientações de registro](/docs/guides/apple-messages/registration) para preparar outro negócio.

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