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

Exemplo de código

bird amb businesses list
bird amb conversations list

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

Exemplo de código

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:

Exemplo de código

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

Exemplo de código

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

Exemplo de código

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

Exemplo de código

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 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 para trocas nativas e resultados comerciais assíncronos, ou as orientações de registro para preparar outro negócio.

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Assista ao guiaWebhooks done right: reliable delivery events Entenda o conceitoHow do I verify a webhook signature?Explore a funcionalidadeApple Messages for Business Siga o percurso de aprendizagemOperate messaging reliably

Experimente na prática e obtenha um resumo de implementação