SapaganDocs sapagan.com

Get started

Quick start

From a key to a first push in about 15 minutes.

You will create keys, add a person, register a phone, send one push and read what happened to it.

Before you start#

You need:

  • A Sapagan workspace and an owner login to the console. Sapagan creates the organisation and its first owner for you.
  • A Firebase project for your app, with its service account file. See FCM and APNs credentials.
  • A phone or browser that can receive push. The Flutter and web SDKs register one for you; this guide registers a token by hand so you can see each step.

In a development workspace, only people on the test list receive anything. Add yourself first under Settings, Setup, "Test people". See Quiet hours and caps.

1. Get your keys#

Open the console and go to Settings, Setup. The page lists the steps and has a "For your developer" part with your API base URL and the workspace id.

Create two keys:

KeyLooks likeWhere it lives
Server keyktg_workspace_...Your backend only. It can do everything the API allows.
App keyktg_app_...Inside your app or web page. It is public by nature.

A key is shown once. Put it in your secret store at once. More in API keys.

export SAPAGAN_URL="https://api.example.com"
export SAPAGAN_KEY="ktg_workspace_..."

2. Identify a person#

A person is a profile with an external id: the id your own system uses for them. Send profiles, events and devices to POST /v1/batch.

curl -X POST "$SAPAGAN_URL/v1/batch" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "profile", "id": "user-42", "attributes": { "name": "Budi Santoso" } }
    ]
  }'

The answer has one result per item. An item that fails is reported at its index and does not stop the others.

3. Register a device#

A device is a push token tied to a person. Use the SDK in a real app (see Flutter and Web). From your backend, a device is one more batch item:

curl -X POST "$SAPAGAN_URL/v1/batch" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "device", "op": "upsert", "profileId": "user-42", "platform": "android", "token": "<FCM registration token>" }
    ]
  }'

platform is android, ios or web. For a browser, the token is the FCM web token from your own Firebase project.

4. Send a first push#

Upload your Firebase service account first (Settings, Setup, Push credentials), or the send has nowhere to go. Then send one transactional message with POST /v1/send:

curl -X POST "$SAPAGAN_URL/v1/send" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-push-1" \
  -d '{
    "to": { "externalId": "user-42" },
    "content": {
      "title": "Halo Budi",
      "body": "Ini push pertama dari Sapagan.",
      "destination": { "kind": "app", "path": "/home" }
    },
    "channels": ["push"]
  }'

The answer is 202 with the message id. The message is sent within a moment.

5. See the result#

Read the message and its deliveries with GET /v1/send/{id}, or open the console. Totals are at GET /v1/send/stats.

curl "$SAPAGAN_URL/v1/send/$MESSAGE_ID" -H "Authorization: Bearer $SAPAGAN_KEY"

A status of dispatched means the push went to the provider. suppressed and failed come with a statusReason, for example not_allowlisted for a person who is not on the test list of a development workspace. The SDKs report delivered and opened back, so opens show in the console and in GET /v1/send/stats.

Next#