Push

Push notifications

Send a push to your app's users in one API call, with an optional text message when the push cannot reach them.

Quickstart

You bring your own Apple and Google credentials, register device tokens from your backend, and send with one call. No mobile SDK is required: your app gets its token from Apple or Google as usual and your server passes it on. Optional Swift and Android packages handle the token and per-device encryption. Start with a test key, which needs no real device.

Create a push app and upload your APNs key, your Firebase service account, or both.
Register each device token from your backend with PUT /v1/push/devices.
Send with POST /v1/push to a user_id. Every active device of that user gets the push.
Optionally add fallback.sms to send a text when no device accepts the push.

New to the Apple and Google side? Set up your app covers the developer accounts, the keys and the code that gets a device token.

If you accepted HonkIO’s data processing agreement, accept the version that covers push notifications (Settings, Data processing agreement) before you add your first app. Until then, creating one is refused with 409 DPA_PUSH_ACCEPTANCE_REQUIRED.

const { data: push, error } = await honkio.push.send({
  appId: 'APP_ID',
  to: { userId: 'user_1042' },
  title: 'Your code',
  body: '123456',
}, { idempotencyKey: 'login-code-1042-2026-11-03' })
if (error) throw new Error(error.message)
console.log(push.id, push.status, push.device_count) // queued 2

from honkio import Honkio

client = Honkio()  # reads HONKIO_API_KEY

push = client.push.send(
    app_id="APP_ID",
    to={"user_id": "user_1042"},
    title="Your code",
    body="123456",
    idempotency_key="login-code-1042-2026-11-03",
)
print(push["id"], push["status"], push["device_count"])  # queued 2

<?php

use Honkio\Honkio;

$honkio = new Honkio(); // reads HONKIO_API_KEY

$push = $honkio->push->send([
    'app_id' => 'APP_ID',
    'to' => ['user_id' => 'user_1042'],
    'title' => 'Your code',
    'body' => '123456',
], 'login-code-1042-2026-11-03');
echo $push['id'], ' ', $push['status'], ' ', $push['device_count'], PHP_EOL; // queued 2

<?php

use Honkio\Laravel\Notifications\HonkioPushMessage;
use Illuminate\Notifications\Notification;

class LoginCode extends Notification
{
    public function __construct(private string $code)
    {
    }

    public function via($notifiable): array
    {
        return ['honkio-push'];
    }

    public function toHonkioPush($notifiable): HonkioPushMessage
    {
        return HonkioPushMessage::create()
            ->app('APP_ID')
            ->title('Your code')
            ->body($this->code);
    }
}

// On the notifiable model: the user_id the devices were registered under.
// public function routeNotificationForHonkioPush($notification): ?string
// {
//     return (string) $this->id;
// }

curl -X POST https://api.honkio.ca/v1/push \
  -H "Authorization: Bearer mk_test_YOUR_KEY" \
  -H "Idempotency-Key: login-code-1042-2026-11-03" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "APP_ID",
    "to": { "user_id": "user_1042" },
    "title": "Your code",
    "body": "123456"
  }'

# Response 202: { "id": "push_...", "status": "queued", "device_count": 1, ... }

The steps are on the pages that follow: app setup, credentials, devices, sending and fallback, encryption, test mode and where data goes.

How it works

A send call answers 202 with the push queued. honkio then makes one delivery per active device, straight to Apple's APNs or Google's FCM with your credentials, never with honkio's own.

A push is queued, sending, sent, failed or fell_back. Sent means at least one device was accepted. Fell_back means no device accepted it and the fallback text was submitted.

Accepted by Apple or Google is not the same as seen. honkio cannot tell whether the phone was off or offline, the app was removed or notifications were switched off, so it never treats an accepted push as undelivered.

Push is built for transactional messages: sign-in codes, reminders, receipts and alerts.

Next: credentials, sending and fallback, encryption.