Open Support iOS

Open Support is a SwiftUI iPhone app for operating a WhatsApp Business support inbox without using Meta's WhatsApp Business app UI.

The app is a mobile operator client. It does not talk to Meta directly and it does not store WhatsApp API secrets on the device. You run your own backend, the backend receives Meta WhatsApp Cloud API webhooks, stores conversations, sends replies, registers APNs devices, and optionally generates AI suggestions.

What You Get

• WhatsApp-style inbox and conversation views
• Operator login with bearer-token sessions
• Text replies, images, videos, documents, and voice notes
• Voice-note playback before and after sending
• Push notifications for inbound customer messages
• AI draft replies and suggested actions from your backend
• Thread statuses, labels, owner/profile attachment, and read state
• Typing/read indicator calls for the latest inbound WhatsApp message

What You Need

• Xcode 16 or newer
• iOS 17 or newer
• An Apple Developer account if you want to install on real devices outside the simulator
• A backend implementing docs/backend-api.md
• A Meta WhatsApp Cloud API phone number and webhook receiver
• APNs credentials for your app bundle identifier

Quick Start

Clone the repository:

git clone https://github.com/jewprobablyknow/open-support-ios.git
cd open-support-ios
open OpenSupport.xcodeproj

In Xcode:

1. Select the Open Support target.
2. Set your Apple development team.
3. Change the bundle identifier from com.example.opensupport to your own id, for example com.yourcompany.opensupport.
4. Set SUPPORT_API_BASE_URL in Build Settings to your backend URL, for example https://support-api.yourcompany.com.
5. Build and run on a simulator or a paired iPhone.

The app stores the operator bearer token in the iOS Keychain under the app bundle identifier.

Installing On An iPhone

Xcode Development Install

This is the fastest path for testing:

1. Connect your iPhone to your Mac.
2. Open OpenSupport.xcodeproj.
3. Select your iPhone as the run destination.
4. Make sure the target has your Apple development team and bundle id.
5. Press Run.

If iOS blocks launch, open iPhone Settings and trust the developer profile for your Apple ID or team.

Team Distribution

For a small internal team, use one of:

• TestFlight
• Apple Business Manager / MDM
• Ad Hoc distribution with registered device UDIDs
• Enterprise distribution if your Apple account supports it

The repo does not ship a prebuilt .ipa, because every user needs their own bundle id, signing team, backend URL, and APNs topic.

Backend Setup

Your backend is responsible for the production behavior:

1. Create or connect a Meta WhatsApp Cloud API app and phone number.
2. Configure Meta webhook delivery to your backend.
3. Verify incoming webhook signatures.
4. Store contacts, threads, messages, media references, labels, owners, profiles, and unread state.
5. Send replies through Meta WhatsApp Cloud API.
6. Stream or proxy WhatsApp media to authenticated operators.
7. Register APNs device tokens from the app.
8. Send APNs notifications when new inbound messages arrive.
9. Optionally generate AI replies and suggested actions.

The exact API contract consumed by the app is documented in docs/backend-api.md.

Logging In

The app calls:

• POST /api/operator/support/auth/login
• GET /api/operator/support/session
• POST /api/operator/support/auth/logout

Your backend decides how operators are created and authenticated. A successful login returns an opaque bearer token and operator profile. The app sends that token as:

Authorization: Bearer <operator-token>

Push Notifications

The app posts APNs device tokens to:

• POST /api/operator/support/push/devices
• DELETE /api/operator/support/push/devices

Your backend should send APNs alerts when a WhatsApp webhook records a new inbound message. Use the configured app bundle id as the APNs topic.

For development builds, the app reports sandbox; for release builds, it reports production.

Media And Voice Notes

The app sends media through:

• POST /api/operator/support/threads/:threadId/reply-with-media

Uploads are multipart form requests with:

• body_text: optional caption/text
• attachments[]: one or more files

Incoming messages can include media.download_url. The app requests that URL with the operator bearer token, so the backend should authenticate and then stream or redirect the media.

AI Suggestions

The app can ask the backend for suggested replies and actions:

• POST /api/operator/support/threads/:threadId/suggest
• DELETE /api/operator/support/threads/:threadId/suggestion

Suggestions are treated as drafts. The app does not auto-send AI responses.

Local Build Check

You can compile the project from the command line:

xcodebuild \
  -project OpenSupport.xcodeproj \
  -scheme "Open Support" \
  -destination 'generic/platform=iOS Simulator' \
  CODE_SIGNING_ALLOWED=NO \
  build

Troubleshooting

The App Cannot Reach The Server

• Check SUPPORT_API_BASE_URL.
• Make sure the URL uses HTTPS for device installs.
• Confirm your backend has the endpoints listed in docs/backend-api.md.
• Check that CORS is not relevant here; this is a native app, not a browser.

Login Fails

• Confirm POST /api/operator/support/auth/login returns the JSON shape in docs/backend-api.md.
• Confirm the backend token is accepted by GET /api/operator/support/session.
• Delete the app from the device if you want to clear the stored Keychain token during testing.

Push Notifications Do Not Arrive

• Confirm the app has notification permission.
• Confirm the backend receives the APNs device token.
• Confirm the APNs topic equals your bundle id.
• Use sandbox APNs for debug builds and production APNs for release builds.

Media Does Not Load

• Confirm download_url is reachable by an authenticated operator.
• Confirm the response has the correct content type.
• Do not expose raw Meta access tokens or public unauthenticated media URLs.

Security Notes

• Do not put Meta access tokens or API secrets in the iOS app.
• Keep Meta WhatsApp Cloud API credentials only on your backend.
• Authenticate operators before returning media download URLs.
• Treat AI-generated suggestions as drafts, not automatic replies.

License

MIT. See LICENSE.