Generic Web Request

API Token

To obtain your API token, please provide us with your push certificate. You can either create a new push certificate for us or use your existing one.

Endpoint to send messages

POST https://push.contextsdk.com/v1/campaigns/schedule_message_for_user

This endpoint is used to schedule a push notification message for a specific user on the ContextSDK platform. You need to send one web request per message you want to send.

Headers

Header	Description	Example Value
Authorization	The token used to authorize the request. Replace with a valid authentication token. Reach out to us to get access	Token CTX-1234567890abcdef

Request Body

Parameter	Type	Description	Example Value
bundle_id	String	The unique identifier of the application bundle	com.contextsdk.demo
platform	String	The platform on which the user will receive the message	ios
user_id	String	The unique identifier of the user	user@contextsdk.com
deliver_within_hours	Int	The time frame, in hours, within which the message should be delivered	6
campaign_id	String	The same type of message should always have the same campaign_id. This is used for performance insights, and to train custom models for each campaign_id.	daily-reminder
idempotency_key	String (optional)	A unique identifier for the push notification message. If the same idempotency_key is used in multiple requests, only the last request will be processed.	1234567890abcdef
delivery_method	String (optional)	The delivery method for the message. Possible values are context_aware and traditional. If no value is specified, we will automatically do an AB test on your behalf. If you already have the AB test cohort for the user, you can specify the corresponding value here.	context_aware
content	Object	Details of the message to be delivered. See subfields below.
title	String	The title of the push notification message.	James, It's time to learn English
subtitle	String (optional)	The subtitle of the push notification message	Start your English course now!
body	String	The body content of the push notification message	It's time to learn English. Start your course now!
sound	String (optional)	The full name of the audio file in the root of the main app bundle	sosumi.caf
badge	Int (optional)	The number to display as the badge of the app icon, 0 resets the badge	1
userInfo	Object (optional)	Custom data to be sent with the push notification message	{ "key": "value" }
thread-id	String (optional)	An app-specific identifier for grouping related notifications. This value corresponds to the threadIdentifier property in the UNNotificationContent object.
imageUrl	String (optional)	A URL pointing to a image file hosted publicly on the internet. Requires setting up a notification service extension to fetch the image, see section below

Example Request

POST /v1/campaigns/schedule_message_for_user HTTP/1.1
Host: push.contextsdk.com
Authorization: Token CTX-123456789ABCD
Content-Type: application/json

{
    "bundle_id": "com.contextsdk.demo",
    "platform": "ios",
    "user_id": "user@contextsdk.com",
    "content": {
        "title": "James, it's time for your english course!",
        "body": "Start your english course now!"
    },
    "deliver_within_hours": 3,
    "campaign_id": "daily-reminder",
    "delivery_method": "context_aware"
}

Alternative delivery window specification

The above deliver_within_hours parameter specifies the time frame within which the message should be delivered from the current time onwards. If you want to specify a specific time frame within which the message should be delivered, you can use the target_delivery_time parameter instead. That parameter should be a string in the format ISO 8601, e.g. 2025-01-25T18:32:00Z.

Supporting images

For context aware push notifications ContextSDK will handle fetching and setting the image on the notification before display. For notifications that are delivered traditionally (such as when explicitly using the traditional delivery mode, or in case there was no good moment during the delivery window) a UNNotificationServiceExtension needs to be used.

In your UNNotificationServiceExtension you can fetch the image and set it on the notification. Below is a full example for downloading and setting the image which can be integrated with your existing UNNotificationServiceExtension:

import UserNotifications

class NotificationService: UNNotificationServiceExtension {

    var contentHandler: ((UNNotificationContent) -> Void)?
    var bestAttemptContent: UNMutableNotificationContent?

    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {

        self.contentHandler = contentHandler
        guard let bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent) else {
            contentHandler(request.content)
            return
        }
        self.bestAttemptContent = bestAttemptContent

        if let imageUrl = bestAttemptContent.userInfo["ctx_image_url"] as? String,
           let idempotencyKey = bestAttemptContent.userInfo["ctx_idempotency_key"] as? String,
            let fileUrl = URL(string: imageUrl) {
            let task = URLSession.shared.downloadTask(with: URLRequest(url: fileUrl)) { url, response, error in
                if let httpResponse = response as? HTTPURLResponse, (200...299).contains(httpResponse.statusCode) {
                    if let url = url,
                       let attachment = UNNotificationAttachment.saveImageToDisk(fileIdentifier: "\(idempotencyKey).jpg", sourcePath: url , options: nil) {
                        bestAttemptContent.attachments = [ attachment ]
                    }
                }
                contentHandler(bestAttemptContent)
            }
            task.resume()
        } else {
            contentHandler(request.content)
        }
    }

    override func serviceExtensionTimeWillExpire() {
        // Called just before the extension will be terminated by the system.
        // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
        if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
            contentHandler(bestAttemptContent)
        }
    }
}

@available(iOSApplicationExtension 10.0, *)
extension UNNotificationAttachment {

    static func saveImageToDisk(fileIdentifier: String, sourcePath: URL, options: [NSObject : AnyObject]?) -> UNNotificationAttachment? {
        let fileManager = FileManager.default
        let folderName = ProcessInfo.processInfo.globallyUniqueString
        guard let folderURL = NSURL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent(folderName, isDirectory: true) else {
            return nil
        }

        do {
            try fileManager.createDirectory(at: folderURL, withIntermediateDirectories: true, attributes: nil)
            let fileURL = folderURL.appendingPathComponent(fileIdentifier)
            try fileManager.moveItem(at: sourcePath, to: fileURL)
            let attachment = try UNNotificationAttachment(identifier: fileIdentifier, url: fileURL, options: options)
            return attachment
        } catch let error {
            print(error)
        }

        return nil
    }
}

Note on traditional delivery

When using the traditional delivery method, the notification will be sent to the user as soon as possible, usually with in at most 5 minutes. As such cancelling is only possible immediately after scheduling it.

Endpoint to cancel delivery of a message

POST https://push.contextsdk.com/v1/campaigns/cancel_message_for_user

If a message is no longer applicable delivery can be cancelled if the message was not shown to the user yet. This requires you to set an idempotency key when scheduling the message. Cancelling a message is not possible if relying on the auto generated idempotency key.

Headers

Header	Description	Example Value
Authorization	The token used to authorize the request. Replace with a valid authentication token. Reach out to us to get access	Token CTX-1234567890abcdef

Request Body

Parameter	Type	Description	Example Value
bundle_id	String	The unique identifier of the application bundle	com.contextsdk.demo
platform	String	The platform on which the user will receive the message	ios
user_id	String	The unique identifier of the user	user@contextsdk.com
campaign_id	String	The same type of message should always have the same campaign_id. This is used for performance insights, and to train custom models for each campaign_id.	daily-reminder
idempotency_key	String	A unique identifier for the push notification message. If the same idempotency_key is used in multiple requests, only the last request will be processed.	1234567890abcdef

Example Request

POST /v1/campaigns/cancel_message_for_user HTTP/1.1
Host: push.contextsdk.com
Authorization: Token CTX-123456789ABCD
Content-Type: application/json

{
    "bundle_id": "com.contextsdk.demo",
    "platform": "ios",
    "user_id": "user@contextsdk.com",
    "campaign_id": "daily-reminder",
    "idempotency_key": "427c60db-c3df-4098-a0f7-9b5d153438f4"
}