skills/credentials/guided-channels.md

# Web, Email DNS, SMS: no secret file to upload

None of these channels has a secret credential file. Web is the exception on API access: the agent can set the initial web platform config through the write-once provisioning endpoint — `chrome_web_origin`, MCP tool preferred (see the Web push section). Email, SMS, and a user-owned Safari `.p12` stay **guide-only**: the configuration happens in the OneSignal dashboard, the user's DNS provider, or through carrier registration. The agent guides those and (for email) prompts a re-check, but cannot finish them through the apps API. Set expectations honestly and hand off cleanly.

Verified against the OneSignal docs (July 2026): `web-sdk-setup.mdx`, `email-setup.mdx`, `sms-setup.mdx`, and the Create/Update App reference pages. See [references/platform-matrix.md](references/platform-matrix.md) for the automate-vs-human split and [references/safety-contract.md](references/safety-contract.md) for the rules.

---

## Web push

Web has no per-key secret to procure for the common case — OneSignal auto-provisions Safari certificates for free. The two things that actually block web push are the **Site URL match** and the **service worker being reachable same-origin** (the service-worker file is written by the SDK-setup skill, not here).

### Site URL must exactly match the origin
In the dashboard: **Settings → Push & In-App → Web**. Set **Site URL** to the exact [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin) of the deployed site, e.g. `https://yourdomain.com`.
- It is scheme + host (+ port), nothing else — no path, no trailing junk.
- `www.` matters: if the site doesn't serve `www.`, don't put `www.` in the Site URL (and vice versa). A mismatch here silently breaks subscription.
- **One origin per OneSignal app.** Multiple domains/subdomains need either a redirect to a single origin or one OneSignal app per origin (browser same-origin limitation).
- **Localhost testing** uses a *separate* OneSignal app with the Site URL set to the exact localhost origin (`http://localhost`, `https://localhost:3000`, etc.) and `allowLocalhostAsSecureOrigin: true` in the SDK init. Never point the production app's Site URL at localhost.

If the web platform has never been configured, the agent can set it via the write-once provisioning endpoint (`POST /api/v1/apps/{app_id}/credentials`). The transport and its rules are owned by [SKILL.md](SKILL.md) → "The API-upload mechanism" (don't restate them here): prefer the `provision_app_credentials` MCP tool when the MCP is connected — its schema takes the web params, and the App-ID precondition applies — else use the direct app-scoped-key `POST`. The web-specific params: `chrome_web_origin` (must be `https://` and exactly match the origin) plus optional `chrome_web_default_notification_icon`. The endpoint does NOT take Site Name or any Safari params — those, and any later changes to an already-configured web platform, happen in the dashboard (Settings → Push & In-App → Web).

**The consent question for this write** (safety contract §14a; the wording rules are in [SKILL.md](SKILL.md) → "The API-upload mechanism"). Ask it with the structured-question tool after the App-ID precondition passes and after the user typed the origin. Use this wording — the user reads the outcome, not the transport:

> Can I set up web push for your OneSignal app on your behalf? I will set the Site URL to `<origin>`. This is a one-time setup from here. Later changes happen in the dashboard (Settings > Push & In-App > Web).

Choices:

- Yes, set it up for me
- No, I will set it up in the dashboard

On "No", skip the API call, give the dashboard path above, and continue with the next step.

### Safari certificates
OneSignal auto-provides Safari Web Push certificates at no cost — the user does **nothing** for the normal case. Only if the user already owns their own Safari Web Push `.p12` do they toggle it on and upload it (then it becomes a real secret: gitignore/keep-external, never paste in chat). Default guidance: leave it off, let OneSignal handle it.

### iOS web push caveat
Web push on iPhone/iPad requires iOS 16.4+, a `manifest.json`, and the user adding the site to their home screen. That's SDK-setup territory — mention it if the user asks about iOS web push, but it isn't a credential.

---

## Email — SPF / DKIM / DMARC DNS (guide only, ~24h)

The agent cannot edit the user's DNS. The exact record values are generated by the OneSignal dashboard during setup; a human with DNS access adds them, then propagation takes **up to 24 hours**, then the dashboard re-checks.

### Access pre-check (Step 0)
Confirm the user (or a named teammate) has access to the **domain's DNS provider**. This is the long pole — surface it before anything else. Also: the sending address must be on a **domain the user owns**; free mailboxes (Gmail/Outlook) are not supported as sending domains.

### The flow to guide
1. Dashboard: **Settings → Set up Email**. Choose **OneSignal Email** (or an external provider: SendGrid / Mailgun / Mandrill).
2. **Create a sender:** default sender email, sender name, reply-to, and sending domain. Recommend a **subdomain** (e.g. `mail.yourdomain.com`) to isolate sending reputation from the root domain.
3. **Configure DNS:** the dashboard shows the required **SPF, DKIM, and DMARC** records. If the registrar is supported, **Auto-Configure** is offered; otherwise the human copies the exact values into the DNS provider manually. Tell the user to copy values **exactly** — a mismatch shows a warning icon and mail gets filtered to spam.
4. **Propagation:** DNS changes can take **up to 24 hours** to propagate. Each record shows a check icon in the dashboard once it's live.
5. **Re-check:** after propagation, the user clicks **Verify Account**. OneSignal reviews domain health / reputation / blocklists; approval usually completes within minutes and the result is emailed. Before approval, only **test emails to their own addresses** are allowed; full-audience sending unlocks after verification.

### The agent's role
- Walk the user to the dashboard DNS values; do **not** invent record values.
- Set the 24h expectation explicitly so the user doesn't think it failed.
- Offer to **re-check status** with the user after they've added the records — but the check itself is the dashboard's **Verify Account** button; there is no REST-key path for the agent to flip verification.
- If a record shows a mismatch/warning, point the user at the exact record in the dashboard to correct.

---

## SMS — sender registration (guide only, days–weeks)

SMS is the least automatable. Carrier/sender-resource registration is **outside anyone's control** and takes **days to weeks** (some resource types 8–16 weeks). No agent step finishes it. The job here is to set expectations and route the user correctly.

### Set expectations up front
- Registration timelines by resource type (verified — `sms-setup.mdx`): alphanumeric sender IDs are fast (fast, geo-limited), toll-free ~days, long codes ~weeks, short codes weeks–months, RCS ~8–16 weeks. US 10DLC ~1–3 weeks.
- This is a compliance/carrier process, not a file upload. There is nothing the agent uploads via API.

### The two setup paths (dashboard: Settings → SMS → Set up SMS)
- **OneSignal SMS** — OneSignal's compliance team handles carrier applications and registration. Best for >5,000 SMS/month and paid plans. The user clicks **Book Demo with SMS Expert** / works with their account manager; the compliance team drives the applications.
- **Twilio integration** — the user owns their Twilio account and sender resources, then connects Twilio to OneSignal with their **Account SID** + **Auth Token**. Best for <5,000/month or full Twilio control. (Those Twilio credentials are secrets — env vars / dashboard entry, never chat, never repo.)

### The agent's role
- Explain the two paths and the timeline honestly.
- Point the user to **Settings → SMS → Set up SMS** and, for OneSignal SMS, to their account manager / the SMS-expert booking.
- Do **not** promise a timeline you can control, and do not attempt any API upload for SMS senders.
- The user can design SMS/MMS templates and gather brand info while registration is pending.

---

## Summary: what the agent can and can't finish

| Channel | Agent finishes via API? | Agent's actual role | Wait |
|---|---|---|---|
| Web | Site URL config can be set via apps API params, but it's usually a dashboard step | Get the origin exactly right; verify SW is same-origin (SDK skill) | none |
| Email | No | Guide DNS values, set 24h expectation, prompt re-check (dashboard Verify Account) | ~24h |
| SMS | No | Explain paths + timeline, route to dashboard / account manager | days–weeks |

For anything with a real secret (own Safari `.p12`, Twilio Auth Token): env var or dashboard entry only, gitignore/keep-external, never paste in chat, never commit. See [references/safety-contract.md](references/safety-contract.md).