​

Troubleshooting: Apple Messages for Business onboarding and send failures

​

Symptom map

​

Agent stuck in pending — Apple-side clearance has not landed

1. Check Apple Business Register for an open action on the business entry. A missing document or a failed review keeps the agent pending no matter what Orbit does.
2. Confirm the business_id you passed at create time is the approved identity, not a draft or sandbox one.
3. Keep polling with backoff. No retry from your side moves the status.
4. If the register shows the business as approved but the agent still reads pending, escalate: the MSP-side handoff is the remaining leg, and support can check it with your agent ID and business_id.

​

Suspended means repair or re-register

​

422 on a send: the missing *Json metadata key

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "amb interactive send requires listPickerJson in metadata"
  },
  "meta": {
    "request_id": "req_amb_4f2c",
    "timestamp": "2026-09-30T09:14:00Z"
  }
}

1. Read the key name off the rejection. It is exactly the key your send omitted.
2. Add the serialized payload under that key. The value is a JSON string, not a nested object.
3. Confirm the agent holds the matching capability (see the next section). A correct key on an agent without the capability fails the next gate.
4. Resend. The reject is deterministic; the corrected body passes on the first retry.

​

Capability-gated rejects

• Rich payload on an agent without the capability. The send is rejected or the payload is dropped. Read the agent record’s capabilities, enable the one the payload needs, or fall back to plain text for that conversation.
• Native Apple Pay without the merchant identifier. The checkout resolver degrades by design: with applePayEnabled and merchantIdentifier both set it returns method: "native" and the Apple Pay sheet payload; otherwise it returns method: "hosted" with native null. If you expected a native sheet and received a hosted link, the merchant identifier is the gap. Register it with Apple and set it in the checkout config, or keep sending hosted.url into the thread. Both paths reconcile against the same paymentRequest, so your order logic does not fork. The commerce guide covers the decline-and-retry loop.

​

The HMAC secret at onboarding

• Stored indicator set, events verifying. Nothing to do. This is the healthy state.
• Secret lost on your side. You cannot read it back out of Orbit. Issue a new key in Apple Business Register and update the agent with the onboarding guide’s rotation steps. Until the stored secret matches Apple’s current one, inbound events fail verification.
• Secret changed at Apple. Update the agent before the old key stops working. Rotating or deleting an agent changes webhook verification and routing for that Apple business.

​

Decision checklist

1. Onboarding or send? pending/suspended and secret problems are onboarding; 422 and capability rejects are send-side.
2. Onboarding: read the agent status. pending means wait on Apple and check the register; suspended means repair or re-register, with no sends in between.
3. Send-side 422: read the key the rejection names, fix the template, resend once. Never retry the same body.
4. Capability reject: compare the payload against the agent’s capabilities; for native pay, confirm the merchantIdentifier is registered and set.
5. Webhook-side: check the stored-secret indicator; rotate when the secret changed at Apple.

​

What not to try

• Do not send live traffic to a pending agent. Apple has not cleared it; the status will not move from your side.
• Do not retry a 422 that names a *Json key. The reject is deterministic and nothing queues; the same body fails identically.
• Do not move an Apple payload to another channel to dodge a capability reject. Apple payloads are not interchangeable with WhatsApp, RCS, or web-chat payloads; they are rejected rather than rendered elsewhere.
• Do not expect Orbit to return your HMAC secret. Only the stored indicator is exposed; rotate instead.
• Do not treat suspended as transient. It does not clear by itself; repair or re-register.

​

When to escalate

• The agent ID (data.id from the create response), not just the Apple business_id.
• One meta.request_id from the rejection, for send-side failures.
• The agent’s capabilities array and, for pay failures, the merchantIdentifier you configured.

​

See also

• Apple Messages for Business — the channel page this runbook triages.
• Apple Messages for Business onboarding — the wizard, request bodies, status polling, and secret rotation.
• AMB commerce: interactive flows and Apple Pay checkout — payloads, cart merge, token capture, and reconciliation.
• KakaoTalk template gates — the comparable deterministic-422 runbook for another approval-gated channel.