Responder a una conversación de Apple Messages

Envía una respuesta de texto a un cliente que ha abierto una conversación en Apple Messages for Business y luego inspecciona el resultado del mensaje.

Requisitos previos

Tu espacio de trabajo necesita un negocio de Apple aprobado y una conversación abierta iniciada por su cliente. Los paquetes CLI y SDK con compatibilidad AMB están pendientes de publicación. Estos comandos requieren una compilación que incluya bird amb; comprueba bird amb --help antes de continuar. Hasta que se publique un paquete con estos comandos, usa la referencia de API o el panel de Apple Messages. Autentícate en la región que aloja tu espacio de trabajo.

Usa Bash con jq y uuidgen instalados. Autentícate en CLI para ese espacio de trabajo. Tu credencial necesita amb:read para inspeccionar conversaciones y mensajes, amb:write para enviar y amb_management:read para inspeccionar negocios. Usa una conversación de prueba existente con permiso para contactar a su destinatario.

1. Selecciona el negocio y la conversación

Ejemplo de código

bird amb businesses list
bird amb conversations list

En las indicaciones, pega los ID de registro que seleccionaste de esas listas:

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

Verifica que el negocio esté aprobado, la conversación esté abierta y su negocio coincida con el registro seleccionado. Extrae los identificadores de Apple que usa la solicitud de envío:

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

Un número de teléfono no puede sustituir al identificador opaco del cliente en una respuesta ordinaria.

2. Previsualiza la respuesta

Ejemplo de código

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

El comando muestra la solicitud sin enviarla. Comprueba el negocio, el destinatario y el texto del mensaje. Para inspeccionar la forma completa de la solicitud, ejecuta bird amb send --example. Un archivo JSON pasado a través de --body-file puede incluir campos opcionales como categoría, etiquetas o configuración regional.

3. Enviar el mensaje revisado

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

El comando genera un identificador de solicitud y guarda el ID de respuesta en MESSAGE_ID. El envío pone en cola un mensaje facturable para procesamiento asíncrono. Si reintentás, reutiliza REQUEST_ID; no ejecutes uuidgen de nuevo para esa solicitud.

4. Inspeccionar el resultado

Ejemplo de código

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

sent registra la aceptación por parte de la pasarela de Apple. No confirma la entrega al dispositivo ni que el cliente haya leído el mensaje. Un envío fallido o incierto requiere investigación antes de enviar otro mensaje. Tu reserva, pedido u otra acción comercial debe esperar a su propio resultado confirmado.

Para actualizaciones asíncronas, suscríbete a través de webhooks a amb.accepted, amb.sent, amb.send_failed, amb.rejected, amb.received o los eventos del ciclo de vida de la conversación. Verifica las firmas y deduplica las entregas por ID de webhook. Los eventos pueden llegar desordenados.

Usa MCP para el mismo intercambio

MCP expone las herramientas correspondientes: amb_businesses_list, amb_businesses_get, amb_conversations_list, amb_conversations_get, amb_send, amb_get y amb_list_events. Pasa a amb_send los mismos from, to y el objeto content, además de idempotency_key cuando reintentas una solicitud. Revisa el destinatario y el contenido exactos antes de autorizar la llamada a la herramienta.

Si una herramienta no aparece, comprueba la versión del servidor y los alcances otorgados a tu conexión.

Límites de solicitudes

Apple Messages establece por defecto 10 solicitudes por minuto por organización. Las respuestas, los indicadores de escritura y la preparación de adjuntos comparten esa cuota entre tus espacios de trabajo y credenciales en una región. Tu plan o un límite de cliente aprobado pueden aumentarla; contacta con soporte para solicitar un incremento. Consulta al administrador de tu organización o a soporte para confirmar tu límite efectivo. Cuando una solicitud devuelve 429, espera el intervalo de Retry-After antes de reintentar.

Solución de problemas

Si el canal devuelve una respuesta de recurso no encontrado, comprueba si el recurso pertenece al espacio de trabajo autenticado. Ante un rechazo de permisos, comprueba el alcance del canal en la credencial. El negocio debe estar aprobado y la conversación abierta para poder recibir una respuesta; las supresiones también pueden bloquear el envío.

Si el procesamiento rechaza una solicitud ya aceptada, inspecciona sus eventos y la configuración de facturación. El resultado de la pasarela de un envío y el resultado del negocio del cliente son independientes. No asumas la entrega a partir de una respuesta API exitosa.

Próximos pasos

Lee la guía de integración de Apple Messages para intercambios nativos y resultados de negocio asíncronos, o la guía de registro para preparar otro negocio.

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Ver la guíaWebhooks done right: reliable delivery events Comprender el conceptoHow do I verify a webhook signature?Explorar la funcionalidadApple Messages for Business Seguir la ruta de aprendizajeOperate messaging reliably

Prueba el ejercicio y obtén un resumen de implementación