Responda pelo API do Apple Messages

Envie uma resposta de texto a uma conversa existente do Apple Messages usando a Bird pública API, depois inspecione o status de processamento e receba as respostas do cliente.

Prepare o espaço de trabalho e a credencial

Conclua o início rápido da primeira conversa pelo painel para conectar uma empresa e abrir uma conversa de teste. Uma empresa com status Draft pode enviar mensagens de teste antes da aprovação. Respostas comuns usam o identificador opaco Apple do cliente; um número de telefone não pode substituí-lo.

Crie uma chave API do espaço de trabalho com amb:read, amb:write e amb_management:read. Use Bash com curl, jq e uuidgen. Execute os blocos a seguir em um único script Bash ou shell. As configurações de erro interrompem o passo a passo se uma solicitação ou validação falhar. Mantenha as credenciais no seu ambiente em vez de em arquivos de código-fonte:

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

A chave fornece o contexto do espaço de trabalho. Consulte regiões se você receber um erro de incompatibilidade de região.

Selecione a empresa e a conversa

Liste empresas e conversas:

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'

Este exemplo é para uma conversa de teste autorizada; o status Draft não autoriza o lançamento público. Pare se qualquer uma das verificações retornar false ou se uma solicitação falhar. Selecione registros da mesma empresa. Para mais resultados, siga a paginação por cursor; a primeira página não é o inventário completo.

Revise e envie a resposta

Monte a solicitação usando apple_business_id como from e opaque_user_id como to:

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 .

Revise a empresa, o destinatário e o texto. A próxima solicitação enfileira uma mensagem real, potencialmente tarifável:

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

Uma resposta 202 confirma a aceitação para processamento assíncrono. Mantenha REQUEST_ID e o corpo inalterado ao tentar novamente essa solicitação lógica; gerar outra chave pode criar outra mensagem. Consulte idempotência.

Inspecione o processamento e receba respostas

Use Get message e List message events:

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 .

Para atualizações assíncronas, configure webhooks para amb.accepted, amb.sent, amb.send_failed, amb.rejected, amb.received e os eventos obrigatórios de ciclo de vida da conversa. Verifique assinaturas, elimine entregas de webhook duplicadas e tolere eventos fora de ordem. Consulte a mensagem ao reconciliar um estado incerto.

Para amb.received, inspecione o conteúdo recebido e associe a conversa à tarefa pendente do cliente. Processe respostas nativas usando os identificadores enviados quando disponíveis; uma resposta de seletor de horário pode conter um rótulo selecionado. Verifique o sistema de reserva, pedido ou caso antes de executar uma ação irreversível ou confirmar seu resultado.

Amplie o conteúdo da mensagem

A referência de Send message define conteúdo text, rich_link e interactive. Mensagens interativas incluem respostas rápidas, listas, seletores de horário, formulários e apps iMessage personalizados. Use as orientações de design de mensagem nativa para a experiência do cliente.

Para prévias geradas pela Apple, use o fluxo de links compatível no painel. As URLs de origem da mídia são acessadas durante o processamento e podem falhar após a aceitação; use os requisitos de mídia.

Instalações CLI ou MCP que expõem bird amb ou as ferramentas amb_* correspondentes usam a mesma semântica de endereçamento e status. Verifique o esquema do comando ou ferramenta instalado antes de usá-lo; este passo a passo depende diretamente do contrato HTTP público.

Resolva erros

Um 404 pode indicar uma conversa desconhecida ou o espaço de trabalho errado. Um 403 exige o escopo da operação. Uma conversa fechada ou interação nativa não suportada pode retornar 422; o cliente precisa reabrir uma conversa fechada. Para 429, siga Retry-After e a orientação compartilhada de limitação de requisições.

Após a aceitação, inspecione eventos e status de mensagem em busca de falha de processamento ou cobrança. Sent é a aceitação pelo gateway da Apple; não fornece confirmação de entrega no dispositivo nem de leitura. Meça resultados de negócio separadamente.