Push

Send a push message

POST/v1/push/messages

Requires an API key with the push:send scope. About keys and scopes

Takes an Idempotency-Key header: a retry with the same key returns the first result instead of acting twice. Derive the key from what you are sending, and reuse it on every retry. About idempotency

Sends a marketing push notification to one contact's devices on every ready app of the push project (pushProjectId): iOS, Android and web. It is marketing-tier: the contact needs push consent, a push suppression refuses it, and it is recorded as a marketing message. Receipts, sign-in codes and alerts belong on POST /v1/transactional/messages with push. content.urgency defaults to normal; content.overrides.ios takes interruptionLevel and threadId. Read what each device answered at GET /v1/push/messages/{id}/deliveries. An Idempotency-Key header is required: a retry with the same key and request returns the first push, with Idempotency-Replay: true, and sends nothing again; the same key with a different request is 409 IDEMPOTENCY_KEY_REUSED. Agent keys are refused with 403.

Header parameters

Idempotency-Keystringrequired: 8–255 characters

Request body

contactIdstringrequired

The contact to notify.

uuid

pushProjectIdstringrequired

Reaches the contact's devices on every app of the project.

uuid

contentobjectrequired

13 child attributes

titlestringrequired

The notification title (up to 100 characters).

1–100 characters

bodystringrequired

The notification text (up to 500 characters).

1–500 characters

actionUrlstringoptional

The HTTPS page opened when the notification is tapped.

uri · up to 2048 characters

imageUrlstringoptional

A large picture: web and Android show it; iOS needs the app's service extension.

uri · up to 2048 characters

iconUrlstringoptional

Web only; iOS and Android show the app's own notification icon.

uri · up to 2048 characters

dataobjectoptional

Up to 10 string key-value pairs passed to the app untouched, for deep links and in-app routing.

buttonsobject[]optional

Up to 2 action buttons.

at least 1 item · at most 2 items

2 child attributes

titlestringrequired

The button label.

1–30 characters

urlstringrequired

The HTTPS page the button opens.

uri · up to 2048 characters

collapseKeystringoptional

A newer notification with the same key replaces the older one on the device.

soundstringoptional

The name of a sound the app ships; the device's default if unset.

1–64 characters

badgeintegeroptional

The number shown on the iOS app icon.

min 0 · max 99999

ttlSecondsintegeroptional

Seconds a provider keeps trying an offline device (up to 28 days); defaults to 86400 (one day).

min 0 · max 2419200

urgencystringoptional

high wakes the device now; normal lets it wait for a good moment to save battery. Unset, a transactional push is high and any other normal.

one of high, normal

overridesobjectoptional

Fields that differ on one platform, each replacing the shared one there (a whole data map, not merged key by key). On iOS and Android actionUrl may be an app link such as myapp://orders; the shared one and the web one must be HTTPS.

3 child attributes

iosobjectoptional

Replaces shared fields on iOS.

14 child attributes

titlestringoptional

The notification title (up to 100 characters).

1–100 characters

bodystringoptional

The notification text (up to 500 characters).

1–500 characters

actionUrlstringoptional

up to 2048 characters

imageUrlstringoptional

A large picture: web and Android show it; iOS needs the app's service extension.

uri · up to 2048 characters

iconUrlstringoptional

Web only; iOS and Android show the app's own notification icon.

uri · up to 2048 characters

dataobjectoptional

Up to 10 string key-value pairs passed to the app untouched, for deep links and in-app routing.

buttonsobject[]optional

Up to 2 action buttons.

at least 1 item · at most 2 items

2 child attributes

titlestringrequired

The button label.

1–30 characters

urlstringrequired

The HTTPS page the button opens.

uri · up to 2048 characters

collapseKeystringoptional

A newer notification with the same key replaces the older one on the device.

soundstringoptional

The name of a sound the app ships; the device's default if unset.

1–64 characters

badgeintegeroptional

The number shown on the iOS app icon.

min 0 · max 99999

ttlSecondsintegeroptional

Seconds a provider keeps trying an offline device (up to 28 days); defaults to 86400 (one day).

min 0 · max 2419200

urgencystringoptional

high wakes the device now; normal lets it wait for a good moment to save battery. Unset, a transactional push is high and any other normal.

one of high, normal

interruptionLevelstringoptional

How iOS presents it: passive arrives silently, time-sensitive breaks through Focus and needs the app's Time Sensitive Notifications capability.

one of passive, active, time-sensitive

threadIdstringoptional

Notifications with the same thread are grouped together in Notification Center.

androidobjectoptional

Replaces shared fields on Android.

13 child attributes

titlestringoptional

The notification title (up to 100 characters).

1–100 characters

bodystringoptional

The notification text (up to 500 characters).

1–500 characters

actionUrlstringoptional

up to 2048 characters

imageUrlstringoptional

A large picture: web and Android show it; iOS needs the app's service extension.

uri · up to 2048 characters

iconUrlstringoptional

Web only; iOS and Android show the app's own notification icon.

uri · up to 2048 characters

dataobjectoptional

Up to 10 string key-value pairs passed to the app untouched, for deep links and in-app routing.

buttonsobject[]optional

Up to 2 action buttons.

at least 1 item · at most 2 items

2 child attributes

titlestringrequired

The button label.

1–30 characters

urlstringrequired

The HTTPS page the button opens.

uri · up to 2048 characters

collapseKeystringoptional

A newer notification with the same key replaces the older one on the device.

soundstringoptional

The name of a sound the app ships; the device's default if unset.

1–64 characters

badgeintegeroptional

The number shown on the iOS app icon.

min 0 · max 99999

ttlSecondsintegeroptional

Seconds a provider keeps trying an offline device (up to 28 days); defaults to 86400 (one day).

min 0 · max 2419200

urgencystringoptional

high wakes the device now; normal lets it wait for a good moment to save battery. Unset, a transactional push is high and any other normal.

one of high, normal

channelIdstringoptional

The Android notification channel to post in, which the app creates; it sets the sound and importance a person can tune, e.g. one for offers and one for orders.

webobjectoptional

Replaces shared fields on web.

12 child attributes

titlestringoptional

The notification title (up to 100 characters).

1–100 characters

bodystringoptional

The notification text (up to 500 characters).

1–500 characters

actionUrlstringoptional

The HTTPS page opened when the notification is tapped.

uri · up to 2048 characters

imageUrlstringoptional

A large picture: web and Android show it; iOS needs the app's service extension.

uri · up to 2048 characters

iconUrlstringoptional

Web only; iOS and Android show the app's own notification icon.

uri · up to 2048 characters

dataobjectoptional

Up to 10 string key-value pairs passed to the app untouched, for deep links and in-app routing.

buttonsobject[]optional

Up to 2 action buttons.

at least 1 item · at most 2 items

2 child attributes

titlestringrequired

The button label.

1–30 characters

urlstringrequired

The HTTPS page the button opens.

uri · up to 2048 characters

collapseKeystringoptional

A newer notification with the same key replaces the older one on the device.

soundstringoptional

The name of a sound the app ships; the device's default if unset.

1–64 characters

badgeintegeroptional

The number shown on the iOS app icon.

min 0 · max 99999

ttlSecondsintegeroptional

Seconds a provider keeps trying an offline device (up to 28 days); defaults to 86400 (one day).

min 0 · max 2419200

urgencystringoptional

high wakes the device now; normal lets it wait for a good moment to save battery. Unset, a transactional push is high and any other normal.

one of high, normal

Returns

Returns 202 Accepted with a PushMessage in data. Otherwise returns an error; Errors lists every code and which to retry.

idstringrequired: uuid
channel"push"required
statusstringrequired: one of queued, sending, skipped, sent, failed, delivered, bounced, complained
createdAtstringrequired: date-time

curl -X POST https://api.kirora.io/v1/push/messages \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Idempotency-Key: weekend-sale-0192f3a1" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
    "pushProjectId": "0192f3a1-91d4-7b2a-8c3e-4d5e6f7a8b9c",
    "content": {
      "title": "Weekend sale starts now",
      "body": "Free delivery on every order until Sunday."
    }
  }'

const response = await fetch('https://api.kirora.io/v1/push/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Idempotency-Key': "weekend-sale-0192f3a1",
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contactId": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
    "pushProjectId": "0192f3a1-91d4-7b2a-8c3e-4d5e6f7a8b9c",
    "content": {
      "title": "Weekend sale starts now",
      "body": "Free delivery on every order until Sunday."
    }
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/push/messages",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
        "Idempotency-Key": "weekend-sale-0192f3a1",
    },
    json={
        "contactId": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
        "pushProjectId": "0192f3a1-91d4-7b2a-8c3e-4d5e6f7a8b9c",
        "content": {
            "title": "Weekend sale starts now",
            "body": "Free delivery on every order until Sunday.",
        },
    },
)
data = response.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "contactId": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
	  "pushProjectId": "0192f3a1-91d4-7b2a-8c3e-4d5e6f7a8b9c",
	  "content": {
	    "title": "Weekend sale starts now",
	    "body": "Free delivery on every order until Sunday."
	  }
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/push/messages", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Idempotency-Key", "weekend-sale-0192f3a1")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

Response · 202

{
  "data": {
    "id": "0192f3b0-2b3c-7d4e-9f50-6b7c8d9e0f1a",
    "channel": "push",
    "status": "queued",
    "createdAt": "2030-03-14T09:30:00.000Z"
  }
}

curl -X POST https://api.kirora.io/v1/push/messages \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Idempotency-Key: cart-hold-7731" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
    "pushProjectId": "0192f3a1-91d4-7b2a-8c3e-4d5e6f7a8b9c",
    "content": {
      "title": "Last hour: your cart is held",
      "body": "Check out before 18:00 to keep your items.",
      "urgency": "high",
      "overrides": {
        "ios": {
          "threadId": "cart-reminders"
        }
      }
    }
  }'

const response = await fetch('https://api.kirora.io/v1/push/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Idempotency-Key': "cart-hold-7731",
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contactId": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
    "pushProjectId": "0192f3a1-91d4-7b2a-8c3e-4d5e6f7a8b9c",
    "content": {
      "title": "Last hour: your cart is held",
      "body": "Check out before 18:00 to keep your items.",
      "urgency": "high",
      "overrides": {
        "ios": {
          "threadId": "cart-reminders"
        }
      }
    }
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/push/messages",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
        "Idempotency-Key": "cart-hold-7731",
    },
    json={
        "contactId": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
        "pushProjectId": "0192f3a1-91d4-7b2a-8c3e-4d5e6f7a8b9c",
        "content": {
            "title": "Last hour: your cart is held",
            "body": "Check out before 18:00 to keep your items.",
            "urgency": "high",
            "overrides": {
                "ios": {
                    "threadId": "cart-reminders",
                },
            },
        },
    },
)
data = response.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "contactId": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
	  "pushProjectId": "0192f3a1-91d4-7b2a-8c3e-4d5e6f7a8b9c",
	  "content": {
	    "title": "Last hour: your cart is held",
	    "body": "Check out before 18:00 to keep your items.",
	    "urgency": "high",
	    "overrides": {
	      "ios": {
	        "threadId": "cart-reminders"
	      }
	    }
	  }
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/push/messages", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Idempotency-Key", "cart-hold-7731")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

Response · 202

{
  "data": {
    "id": "0192f3b0-4d5e-7f60-8b72-8d9e0f1a2b3c",
    "channel": "push",
    "status": "queued",
    "createdAt": "2030-03-14T09:30:00.000Z"
  }
}