Download the PHP package getokta/okta-connect-sdk without Composer

Okta Connect PHP SDK

A framework-agnostic PHP client for the Okta Connect omnichannel platform: WhatsApp messaging, transactional + bulk email, social publishing (Telegram / X / Instagram / …) and broadcast campaigns — all under one client surface. No Laravel dependency in the SDK code itself — a separate getokta/okta-connect-sdk-laravel bridge package will be published later.

Installation

Quickstart

Tenant scope (read / write / send)

Email

Send transactional email (receipts, OTPs, notifications) as one of your verified sending domains — DKIM-signed server-side — read the send log, and manage templates, broadcasts and the suppression list. Needs the send ability to send.

Bring your own SMTP. A domain connected via your own SMTP/provider (SES / Postmark / Resend) is usable immediately — no DNS verification needed; your server authenticates the mail. Platform-managed domains still publish SPF/DKIM/DMARC first.

Social publishing

Compose a post once and fan it out to one or more social channels. With a future scheduledAt the post is scheduled; without one it's a draft.

Campaigns

Broadcast (bulk / drip) message campaigns: create a draft, then queue it to materialise the audience and start sending.

Provisioning workspaces? That is the Partner API, not this SDK. If you are building a product on top of Connect and need to create workspaces, add and manage their users, mint workspace tokens or reserve channels, apply for a technical-partner account: you get your own client_id/client_secret, and the endpoints live under /api/v1/partner/*. This SDK covers the per-workspace developer surface only — messages, conversations, contacts, channels, templates, groups, webhooks and embed tokens.

Connecting an account (OAuth-style, one click)

The easy way to get a token for a user's organization — no copy-pasting API keys. Send the user to the consent screen, then swap the returned one-time code for a token. No client_secret, no PKCE: the code is single-use, expires in 5 minutes, and is bound to your redirect_uri.

handleCallback() throws a WhatsAppException when the user denied consent (?error=access_denied), the state doesn't match (CSRF), or no code is present. Prefer it over calling exchange($code, $redirectUri) directly so the security checks always run.

Checking your grant. Introspect what the token may do, and ask for more when you need it — the consent screen highlights the new permissions and the exchange replaces the old, narrower grant:

Disconnecting. Your app can sever its own link at any time — the token is revoked and the workspace is notified via a connection.revoked webhook:

The workspace can also unlink your app from its dashboard, which fires the same connection.revoked event (with source: "workspace") to any webhook you registered — subscribe to it to react when access is pulled.

Embedding the inbox (iframe)

Mint embed tokens and build iframe URLs natively — no hand-rolled JWTs. Obtain the shared secret from your platform operator (provisioned server-side), then:

Unknown ui_hide keys and out-of-range TTLs throw at mint time, so misconfigured embeds fail loudly here instead of silently in the browser.

Which workspace does the session land on? An operator who belongs to several workspaces lands on their oldest membership unless you say otherwise. Name one:

It grants nothing — the platform still requires an active membership. The claim picks between doors the user can already open.

Technical partners: sign with your issuer (partner:{your-ulid}), not okta-web. PartnerClient::embedSigner() derives it for you — see below.

Partner API (technical partners)

A technical partner (شريك تقني) wires Connect into its own product: it provisions workspaces, manages their people, mints tokens for them, reserves channels and drops users into the dashboard — all with its own key pair.

PartnerClient is deliberately a separate object from Client. A partner token is bound to the partner organization rather than to a tenant, lives in its own store, and is rejected by the tenant API exactly as a tenant token is rejected here. One object per credential keeps that boundary visible instead of turning it into a 401 that reads like a bug.

Tokens live one hour and are exchanged, refreshed and retried for you: one exchange at a time, a re-exchange before expiry, and exactly one retry on a 401 that slips through anyway. For local development, PartnerClient::withStaticToken() uses the long-lived token from /app/partner verbatim.

Embedding, as a partner

Your own signing key and framing allowlist, both self-service:

A token signed with a partner key resolves only to a user who already exists and is an active member of a workspace you manage. It cannot create an account, grant a role, or name anyone else's workspace.

Full reference: the platform's docs/PARTNER_API.md.

WhatsApp QR pairing

Pairing runs with a workspace token (the kind tokens()->create() mints), because the channel belongs to the workspace, not to the partner.

Branch on error, not on elapsed time. start() boots the gateway session inside the request, so it raises on 502 gateway_unavailable instead of handing back a row that would sit at pending forever; 422 channel_type_unavailable means the operator has not enabled the baileys channel type for that workspace (an availability switch, not a billing one).

Webhooks

Register outbound webhooks over the API instead of adding them by hand in the dashboard. The signing secret is returned once on create — store it.

A token needs the webhooks ability (a least-privilege scope for exactly this), or the broader write / admin scope. Request just ['read', 'webhooks'] when your app only manages webhooks and shouldn't touch anything else.

Verify inbound deliveries before trusting them — the platform signs the raw body with your secret and sends it in X-Okta-Signature: sha256=<hmac>:

Or verify + decode in one step into a typed WebhookNotification and branch on the event. Message events carry which conversation + channel they belong to and whether they're a reply:

Prefer a router over a match, and typed per-family views over raw arrays:

$hook->message(), ->channel(), ->subscription() return typed views (MessageEvent/ChannelEvent/SubscriptionEvent) — or null for a different family.

More resources — tickets, tags, analytics

Idempotency

Mutating calls accept an optional Idempotency-Key header so safe retries are server-deduped:

Configuration

Error handling

All non-2xx responses raise typed exceptions extending Okta\Connect\WhatsApp\Exceptions\WhatsAppException:

Each exception exposes ->statusCode(), ->responseBody(), and the original PSR-7 response.

Running the tests

License

MIT — see LICENSE.