Business use cases

Pull channels and push channels

Each workspace connects a provider per channel in Messaging → Channels (see Connect a messaging provider). A send on a channel with no active provider fails with No active channel configuration found.

Blocks as channels: popups and your own components

A campaign can deliver a dynamic block with the block's own fields instead of a fixed title, body and button. This is how a campaign makes a popup: in the Channels step, the Popup group lists the workspace's popup blocks. Every workspace has a ready-made Standard popup; any block your developers mark as a popup and link to campaigns is listed beside it. Other blocks linked to campaigns are under Dynamic blocks.

• Content: the Content step shows the block's own fields. Text fields are written per language; an image, a switch, a number or a choice is one value for every language.
• Delivery: when the campaign goes live (or to test), the block is published to the app as one ordinary block for that campaign, with the campaign's audience, schedule, frequency rule and priority. The app receives it on its next sync; for a popup, getPopup(screen) returns it as kind: 'block' on the block's own screen. Nothing changes in the app for SDK 2.4.0.
• Standard popup fields: #title, #body, #image, #cta_label and #cta_url. From SDK 2.4.1 the SDK draws it in its built-in card when the app sets no onBlockPopup handler; with SDK 2.4.0 it reaches your onBlockPopup handler (or getPopup), and your app draws it.
• Lifecycle: pausing, ending, rejecting, archiving or deleting the campaign takes the block down; editing a live campaign updates it; activating it again brings it back. The block is managed by its campaign: change it there, not in Dynamic blocks.
• Frequency: the campaign's frequency rule applies to the block. A popup with no rule shows at most once per day, the default every plan allows; the workspace popup limits apply on top.
• Results: impressions, taps (a tap and a button tap from the same press count once) and conversions on the block count toward the campaign's statistics.
• Other channels: a campaign can combine a block with push, SMS, WhatsApp or email; those send as usual. A block is never sent as a message.

If a block channel can't be delivered, the campaign page says why under Block channels, for example a block that was archived or unlinked from campaigns, copy missing in the workspace's main language, a segment that no longer exists, or excluded segments (a block channel can't exclude segments yet). The rest of the campaign is unaffected.

Push or in-app?

A push notification reaches the person outside your app, on the lock screen, even when the app is closed. An in-app message (a banner, a popup or an in-app notification) reaches them inside your app, the next time they use it, and can look like any other part of your app.

Use push when the message matters now and the person may not open the app on their own. Use in-app when it can wait until they next open the app, needs rich layout, or should not interrupt them. A journey can combine them: for example a push on day one, then an in-app banner if the person hasn't acted (see How journeys work), and one campaign can send on several channels at once.

Connect a messaging provider

Push, SMS, WhatsApp and email go out through a provider your workspace connects; in-app needs none. Connect them in Messaging → Channels. Everyone can see which channels are connected; only admins can connect, edit, disconnect or test them.

• Plan. Connecting an SMS or WhatsApp provider is a plan feature; on a plan without it the request is refused with UPGRADE_REQUIRED.
• Which provider sends. When a channel has more than one active provider, the one with the highest priority is used. If several share the highest priority, the dashboard warns that delivery may use any of them.
• Test sends use a fixed test message, not your campaign text, and go through the channel's live provider. They are rate limited per person (CHANNEL_TEST_RATE_LIMITED: wait a few minutes). A disabled channel must be enabled before it can be tested. A test that the provider accepts is not proof of delivery to the handset.
• Email test from a campaign. Admins and editors can send a campaign's email to themselves with the same route; only an admin can send the test to another address, and then it is the fixed test email.

The same operations on the management API (portal sign-in token, see REST endpoints):

GET    /api/v1/notifications/channels?type=sms     list (any role; secrets are redacted)
GET    /api/v1/notifications/channels/{id}          one config (admin)
POST   /api/v1/notifications/channels               connect: { type, provider, name, configuration } (admin)
PUT    /api/v1/notifications/channels/{id}          edit (admin)
DELETE /api/v1/notifications/channels/{id}          disconnect (admin)
POST   /api/v1/notifications/channels/{id}/test     { "to": "+9665…" } or a device token for push (admin)
POST   /api/v1/notifications/channels/email/test    { "to": "…" }, optional; empty sends to your own account email (admin, editor)

type is email, sms, whatsapp or push, and provider one of smtp, sendgrid, mailgun, resend, contentflow-sms, taqnyat, twilio, twilio-whatsapp, fcm, apns, hms. Push provider setup is covered in Push notifications.

Lifecycle and approval

Statuses: draft, pending_review, approved, scheduled, active, test, paused, completed, expired, rejected.

The dispatch pipeline

When it doesn't work

Saudi calendar and prayer times

• Hijri dates: schedule by Hijri start and end as well as Gregorian. Tag campaigns ramadan, eid_fitr, eid_adha, national_day, founding_day or hajj_season for planning.
• Prayer-time blackout: turn it on per campaign and pick the city (Riyadh, Jeddah, Mecca, Medina, Dammam). Outbound sends falling within each prayer's window are deferred, not dropped. You can add your own blackout windows too.
• Time zone: campaigns default to Asia/Riyadh.
• Journeys: start on ramadan_start or eid_start, and wait until iftar (maghrib for the day) before the next step.

Languages and personalisation

Content is stored per locale with its own text direction. Each person gets their preferredLanguage; if there's no content in it, the order is: the base language, a regional variant, the workspace's source locale, Arabic, English, then any. {{tokens}} are filled from the profile and from Shared Values; a token without a value skips that person rather than sending a broken message.

Personalising in-app campaigns

Outbound messages (push, SMS, WhatsApp, email and journey sends) are personalised on the server, as above. Banners and popups that the app pulls (getCampaigns, getPopup, presentPopup) are not: POST /campaigns returns the text as you wrote it, tokens included, and filling them happens on the device.

• JavaScript, React and React Native. The SDK fills {{key}} (and the older {key}) in the campaign's title, body and button label from the traits this device sent with identify or updateTraits. first_name, last_name and full_name come from the name trait, and plan_tier from plan. A token with no matching trait stays exactly as typed, braces included. It is on by default; interpolate: false in the client config turns it off. The original text is in the campaign's raw field.
• Swift, Kotlin and Flutter. These SDKs return campaign text as authored, without filling tokens. Replace them in your own code before you show the campaign, or avoid tokens in pulled campaigns.
• Shared values. A key from Content Library → Shared values is filled on the device only if the device has a trait with that key. Workspace constants are not substituted in pulled campaigns, unlike in-app blocks, where the server fills constants on delivery (see Dynamic blocks).
• Unresolved tokens. Outbound sends skip a person whose declared token has no value (unresolvedToken); a pulled campaign is still shown, with the raw token. Preview the campaign with a test device that has the traits you use, or keep tokens out of banner text.

How journeys work

A journey is a list of steps with optional yes/no branches. Each person enrolled moves through it independently; the engine checks every minute, moving each person up to 20 steps per check. A person can enter a given journey once. They finish when they reach the end of their path. Pausing a journey freezes everyone in place.

Triggers and steps

Event triggers only enrol people who have a profile, so the app must identify them with analytics consent. To start a journey on sign-up, use Signs up (app event) and call trackSignUp in the app. The API also still accepts an older signup trigger (profiles created since the last check), which the dashboard no longer offers.

Steps: wait (seconds, minutes, hours, days, or until iftar), action (banner, push, in-app, SMS, WhatsApp, email, Arabic greeting, or send a campaign; one or several channels), condition (in a segment? then the yes or no branch) and exit (the person leaves the journey there).

Exit criteria: set Exit when in segment on the trigger (exitSeg). Someone in that segment leaves before their next step, including one a wait is about to release. Both ways out mark the enrollment exited and count in the journey's stats.exited.

Journey sequence: welcome series

REST endpoints

Management API, https://api.contentflow.click/api/v1, with Authorization: Bearer <token> and X-Tenant-Id: <workspaceId>. The token is a person's portal sign-in token: POST /api/v1/auth/login with their email and password answers { token, user }, or a two-step verification challenge when the account requires one. It lasts one day and ends when that session is signed out. There is no service-account or server key for the management API: SDK keys (the publishable key <workspaceId>_cfpk…, the older <workspaceId>_app / _test keys, pk_live_…, pk_test_…) open only the SDK routes under /sdk/v1. Creating, editing, sending and enrolling need the admin or editor role.

Check success in every response body. Many refusals come back as { "success": false, "error": { "message": "…", "code": "…" } } with the route's normal status (201 for a POST, 200 otherwise), for example CAMPAIGN_SUBMIT_REVIEW_FAILED, CAMPAIGN_REJECT_FAILED, or FORBIDDEN when someone who cannot approve calls approve. Real HTTP errors are 400 for a body that fails validation (a missing required field or an unknown one), 401 without a valid token, 403 for a role the route does not allow and for SELF_APPROVAL_NOT_ALLOWED, and 409 for REVIEW_REQUIRED.

A first campaign, end to end (every call after sign-in also sends Authorization and X-Tenant-Id):

# 1. The editor signs in (a person, not a server key)
POST /api/v1/auth/login
{ "email": "editor@example.invalid", "password": "…" }

# 2. Create the draft
POST /api/v1/campaigns
{ "name": "Welcome offer", "type": "push_notification", "priority": 5,
  "segments": ["All users"], "schedule": { "startTime": "2026-11-01T09:00:00.000Z" },
  "content": { "en": { "headline": "Welcome", "body": "Your offer is ready" } } }

# 3. Submit it for review
POST /api/v1/campaigns/{id}/submit-review
{ "note": "Ready for review" }

# 4. A different admin or can-approve user approves it into Test mode
POST /api/v1/campaigns/{id}/approve
{ "activateTarget": "test" }

Webhooks campaign.submitted_for_review, campaign.approved, campaign.rejected and campaign.status_changed are described in the REST guide. Activating a journey that uses a campaign which can't send returns 409 JOURNEY_CAMPAIGN_NOT_SENDABLE.

Measuring results

• Delivery: per-channel sent, skipped by reason, deferred and failed on the campaign, and per-status counts at /notifications/campaign/{id}/progress.
• Engagement: impressions, taps and conversions from the app land in Analytics; pulled campaigns are tracked with trackCampaignImpression and trackCampaignTap. Live (not test) events that carry a campaignId, and events on a campaign's in-app message, also add to the campaign's own statistics (impressions, clicks, conversions, CTR) and to each A/B variant's.
• Experiments: A/B results per variant at /campaigns/{id}/experiment/results.

Current limits

• Frequency is optional and off by default: set it with the Frequency field in the campaign's Schedule step, from a preset or under Advanced (rules.frequencyCapping). For in-app campaigns the server applies the whole rule (most views, most taps, a wait between shows, never again after a tap, close or conversion), counted in the workspace time zone: see Popup frequency: the rule. Push, SMS, WhatsApp and email count sends per channel against the rule's most views, so a journey that repeats the campaign stops at the limit, and the extra sends show as frequencyCapped. Those send windows are fixed UTC hours, days or 7-day blocks, not rolling; a month or lifetime period is counted per day for sends. The server counts in-app views from the SDK's campaign impression and tap events, so it never caps a device without analytics consent; from SDK 2.4.0 the device's own count caps it even without consent (see Popup frequency: in the app). On the Free plan a campaign can only use no rule or Once per day; other rules need the Pro or Enterprise plan.
• Block channels: a block channel targets the campaign's segments (or everyone) and its start and end; excluded segments, Hijri dates, prayer blackouts and send windows are not applied to it, and a campaign with excluded segments shows its block channel as not delivered. A/B variants do not split a block channel.
• A/B on outbound channels: variants split pulled in-app campaigns only. Push, SMS, WhatsApp and email send the main content.
• Quiet hours: a person's quiet hours aren't applied to customer messages; use the campaign's prayer blackout and custom windows.
• Push conversions: a push send has no conversion attribution; campaign statistics count what the app reports.
• Journeys: a person enters a journey once, ever. Exit criteria are checked when the person's next step is due. Location triggers are geofence events only; there is no trigger on a person's distance from a point.

Next

• Push notifications: register device tokens so push campaigns have someone to reach.
• Audience & privacy: consent: collect the channel consent that most skip reasons depend on.