From 882fc2ec70a2570f56a0cf875087782ba6976b9b Mon Sep 17 00:00:00 2001 From: underthestars-zhy Date: Sat, 20 Jun 2026 23:37:43 -0700 Subject: [PATCH] docs(spectrum-ts): Add iMessage troubleshooting page --- .../troubleshooting/imessage.mdx.vel | 69 +++++++++++++++++++ docs.json | 6 ++ 2 files changed, 75 insertions(+) create mode 100644 docs-src/spectrum-ts/troubleshooting/imessage.mdx.vel diff --git a/docs-src/spectrum-ts/troubleshooting/imessage.mdx.vel b/docs-src/spectrum-ts/troubleshooting/imessage.mdx.vel new file mode 100644 index 0000000..49b7d22 --- /dev/null +++ b/docs-src/spectrum-ts/troubleshooting/imessage.mdx.vel @@ -0,0 +1,69 @@ +--- +title: "iMessage troubleshooting" +sidebarTitle: "iMessage" +description: "Common iMessage problems on Spectrum, what they mean, and how to fix them." +--- + +If iMessage sends are failing and you've ruled out your code, this page is organized by the error you're seeing. Find the message in the headings below and follow the fix. Each section is self-contained, so you can land here from a search result and still get what you need. + +If your symptom isn't listed, jump to [Still stuck?](#still-stuck) for what to send us so we can trace it on our side. + +## "Target not allowed for this project" + +You're on the **Free** or **Pro** plan. On these plans your project sends through a [shared pool of lines](/spectrum-ts/providers/imessage/connection-and-routing#line-model), and a shared line will only message recipients you've registered as **users** of your project. Any other target is rejected with `Target not allowed for this project`. + + + This limit applies to shared-pool plans only. The **Business** plan uses a dedicated line and isn't subject to the allowlist — see [Line model](/spectrum-ts/providers/imessage/connection-and-routing#line-model). + + +Two things cause this error. + +### 1. You haven't added yourself as a user + +The target you're messaging has to exist as a user on the project first. Add the number your iMessage is linked to: + + + + Go to the [Dashboard](https://app.photon.codes) and select your project. + + + In the project, open **Users**. + + + Add a user with the phone number (or email) your iMessage is linked to, then send again. The target is now allowlisted. + + + +### 2. The number you added isn't the one iMessage actually uses + +If you've added yourself and still get the error, the handle you entered probably doesn't match the one Apple actually sends iMessage from. This happens — Apple sometimes registers iMessage under a number or email you wouldn't expect, so the user you added never matches the inbound sender. + +To find the handle iMessage is really using: + + + + Open [debug.photon.codes](https://debug.photon.codes). It opens an iMessage to our debug bot. + + + The debug bot replies with the exact handle (phone number or email) Apple is sending from for your device. + + + Add **that** handle under **Users** in the [Dashboard](https://app.photon.codes), then retry. + + + +If the handle the debug bot reports isn't what you expect at all, the underlying issue is on Apple's side — iMessage isn't registered to the number you think it is. Apple's official guides for fixing iMessage registration and activation: + +- [If you can't turn on or sign in to iMessage or FaceTime on your iPhone](https://support.apple.com/en-us/119859) — phone-number verification and activation. +- [If you can't send or receive messages on your iPhone or iPad](https://support.apple.com/en-us/118433) — general send/receive failures. +- [Messages support](https://support.apple.com/messages) — Apple's full Messages support hub. + +## Still stuck? + +Send us: + +- Your project id (from `photon projects show`). +- The exact error string you're seeing. +- The target handle you're trying to message and the handle the [debug line](https://debug.photon.codes) reports. + +We'll trace it on our side. Email us at [help@photon.codes](mailto:help@photon.codes) or ping us in the Discord linked in the footer. diff --git a/docs.json b/docs.json index bcbc113..6e67552 100644 --- a/docs.json +++ b/docs.json @@ -137,6 +137,12 @@ "best-practices/recovery-and-state", "best-practices/imessage-deliverability" ] + }, + { + "group": "Troubleshooting", + "pages": [ + "spectrum-ts/troubleshooting/imessage" + ] } ] },