Responde a través del API de Apple Messages

Envía una respuesta de texto a una conversación existente de Apple Messages mediante la API pública de Bird, comprueba su estado de procesamiento y recibe las respuestas de los clientes.

Prepara el espacio de trabajo y la credencial

Completa la guía rápida de la primera conversación en el panel para conectar una empresa y abrir una conversación de prueba. Una empresa en estado Draft puede enviar mensajes de prueba antes de recibir la aprobación. Las respuestas normales usan el identificador opaco de Apple del cliente; un número de teléfono no puede sustituirlo.

Crea una clave API del espacio de trabajo con amb:read, amb:write y amb_management:read. Usa Bash con curl, jq y uuidgen. Ejecuta los siguientes bloques en un solo script o shell de Bash. La configuración de errores detiene el recorrido si una solicitud o validación falla. Mantén las credenciales en tu entorno en lugar de en archivos de código fuente:

Ejemplo de código

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

La clave proporciona el contexto del espacio de trabajo. Consulta regiones si recibes un error de discrepancia de región.

Selecciona el negocio y la conversación

Lista los negocios y las conversaciones:

Ejemplo de código

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 ejemplo es para una conversación de prueba autorizada; el estado Draft no autoriza el lanzamiento público. Detente si alguna comprobación devuelve false o si falla una solicitud. Selecciona registros de la misma empresa. Para obtener más resultados, usa la paginación por cursor; la primera página no contiene el inventario completo.

Revisa y envía la respuesta

Construye la solicitud usando apple_business_id como from y opaque_user_id como to:

Ejemplo de código

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 .

Revisa el negocio, el destinatario y el texto. La siguiente solicitud pone en cola un mensaje real y potencialmente facturable:

Ejemplo de código

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

Una respuesta 202 confirma la aceptación para procesamiento asíncrono. Conserva REQUEST_ID y el cuerpo sin cambios al reintentar esa solicitud lógica; generar otra clave puede crear otro mensaje. Consulta idempotencia.

Inspecciona el procesamiento y recibe respuestas

Usa Get message y List message events:

Ejemplo de código

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 actualizaciones asíncronas, configura webhooks para amb.accepted, amb.sent, amb.send_failed, amb.rejected, amb.received y los eventos de ciclo de vida de conversación requeridos. Verifica las firmas, deduplica las entregas de webhooks y tolera eventos desordenados. Consulta el mensaje cuando necesites reconciliar un estado incierto.

Para amb.received, inspecciona el contenido entrante y asocia la conversación con la tarea pendiente del cliente. Procesa las respuestas nativas usando los identificadores enviados cuando estén disponibles; la respuesta de un selector de hora puede contener una etiqueta seleccionada. Verifica el sistema de reservas, pedidos o casos antes de ejecutar una acción irreversible o confirmar su resultado.

Extiende el contenido del mensaje

La referencia de Send message define contenido text, rich_link y interactive. Los mensajes interactivos incluyen respuestas rápidas, listas, selectores de hora, formularios y apps personalizadas de iMessage. Usa la guía de diseño de mensajes nativos para la experiencia del cliente.

Para las vistas previas generadas por Apple, usa el flujo de enlaces del panel compatible. Las URL de origen de los archivos multimedia se consultan durante el procesamiento y pueden fallar después de la aceptación; sigue los requisitos de contenido multimedia.

Las instalaciones de CLI o MCP que exponen bird amb o las herramientas amb_* correspondientes usan la misma semántica de direccionamiento y estado. Verifica el esquema del comando o herramienta instalada antes de usarlo; este tutorial depende directamente del contrato HTTP público.

Resuelve errores

Un 404 puede indicar una conversación desconocida o el espacio de trabajo incorrecto. Un 403 requiere el alcance de la operación. Una conversación cerrada o una interacción nativa no soportada puede devolver 422; el cliente debe reabrir una conversación cerrada. Para 429, sigue Retry-After y la guía compartida de limitación de solicitudes.

Después de la aceptación, inspecciona los eventos y estados de mensaje en busca de un fallo de procesamiento o facturación. Sent es la aceptación por la pasarela de Apple; no proporciona un acuse de entrega al dispositivo ni de lectura. Mide los resultados de negocio por separado.