Envoi et repli

Envoyer une notification

POST /v1/push prend app_id, to (user_id pour tous les appareils actifs d'un utilisateur, ou device_id pour un seul), ainsi que title, body, data, badge, sound, thread_id, ttl (en secondes, jusqu'à 28 jours), priority (high par défaut, ou normal) et collapse_key (de 1 à 64 caractères ASCII visibles : une notification plus récente avec la même clé remplace une plus ancienne pas encore affichée). Il faut un titre, un corps ou des données. Les valeurs de data sont des chaînes, avec au plus 64 clés et 4096 octets en JSON. Les notifications de données seules (sans titre ni corps, vers un appareil sans clé de chiffrement) sont livrées en silence comme notifications d'arrière-plan : rien ne s'affiche sur l'écran verrouillé et votre application traite les données. Une notification d'arrière-plan ne porte ni pastille ni son, même si vous les envoyez.

Envoyez un en-tête Idempotency-Key. La même clé renvoie la notification d'origine, et la même clé avec un corps différent donne un 409 IDEMPOTENCY_KEY_REUSED. Les modes test et production ne se rejouent jamais l'un l'autre.

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, ... }

L'appel répond 202 avec la notification en file et son device_count. GET /v1/push/:id la renvoie avec le résultat de chaque appareil, et GET /v1/push liste les notifications.

La charge finale envoyée au fournisseur, après chiffrement pour un appareil qui a une clé, est limitée à 4096 octets. Une charge plus grande est refusée avec un 422 PUSH_PAYLOAD_TOO_LARGE et details.bytes_over, et rien n'est facturé.

Sans appareil actif et sans repli, la notification est acceptée et se termine en failed avec NO_DEVICES, sans aucune facturation.

const { data: push, error } = await honkio.push.get('PUSH_ID')
if (error) throw new Error(error.message)
console.log(push.status) // scheduled, queued, sending, sent, failed, fell_back or cancelled
for (const delivery of push.deliveries ?? []) console.log(delivery.device_id, delivery.status, delivery.error_code)

from honkio import Honkio

client = Honkio()  # reads HONKIO_API_KEY

push = client.push.get("PUSH_ID")
print(push["status"])  # queued, sending, sent, failed or fell_back
for delivery in push.get("deliveries", []):
    print(delivery["device_id"], delivery["status"], delivery["error_code"])

<?php

use Honkio\Honkio;

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

$push = $honkio->push->get('PUSH_ID');
echo $push['status'], PHP_EOL; // queued, sending, sent, failed or fell_back
foreach ($push['deliveries'] ?? [] as $delivery) {
    echo $delivery['device_id'], ' ', $delivery['status'], ' ', $delivery['error_code'] ?? '', PHP_EOL;
}

Programmer une notification

Ajoutez scheduled_at pour envoyer plus tard, par exemple un rappel une heure avant un rendez-vous : une date et heure ISO 8601 avec un décalage, de 1 minute à 30 jours à l'avance. L'appel répond 202 avec le statut scheduled, est facturé tout de suite pour les appareils visés à ce moment, et compte dans la limite quotidienne de notifications du jour où elle part. Chaque notification relue porte scheduled_at, null pour une notification envoyée immédiatement, et GET /v1/push accepte status=scheduled ou status=cancelled.

const { data: push, error } = await honkio.push.send({
  appId: 'APP_ID',
  to: { userId: 'user_1042' },
  title: 'Appointment in one hour',
  body: 'Acme Dental, 2 pm today.',
  scheduledAt: '2026-10-01T13:00:00-04:00',
  expiresAt: '2026-10-01T13:45:00-04:00', // optional: not after 1:45 pm (default: 24 hours after scheduledAt)
}, { idempotencyKey: 'appt-5521-push-reminder' })
if (error) throw new Error(error.message)
console.log(push.id, push.status, push.scheduled_at, push.expires_at) // scheduled

curl -X POST https://api.honkio.ca/v1/push \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Idempotency-Key: appt-5521-push-reminder" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "APP_ID",
    "to": { "user_id": "user_1042" },
    "title": "Appointment in one hour",
    "body": "Acme Dental, 2 pm today.",
    "scheduled_at": "2026-10-01T13:00:00-04:00",
    "expires_at": "2026-10-01T13:45:00-04:00"
  }'

# Response 202: { "id": "push_...", "status": "scheduled", "scheduled_at": "2026-10-01T17:00:00.000Z",
#   "expires_at": "2026-10-01T17:45:00.000Z", ... }
# expires_at is optional: without it the push must go out within 24 hours of scheduled_at.

Tant qu'elle est programmée, PATCH /v1/push/:id avec un nouveau scheduled_at la déplace (la clé doit avoir push:m ; 429 PUSH_DAILY_CAP si le nouveau jour est plein) et DELETE /v1/push/:id l'annule, rembourse les frais et rend au mois ses envois gratuits (push:d). Une annulation est irréversible. L'un ou l'autre sur une notification qui n'est plus programmée donne un 422 PUSH_NOT_SCHEDULED. Ils déclenchent push.rescheduled et push.cancelled.

// Move it, or cancel it (refunded), while it is still scheduled:
const moved = await honkio.push.update('PUSH_ID', { scheduledAt: '2026-10-02T09:00:00-04:00' })
if (moved.error) throw new Error(moved.error.message)

const cancelled = await honkio.push.cancel('PUSH_ID')
if (cancelled.error) throw new Error(cancelled.error.message)

# Move it, or cancel it (refunded), while it is still scheduled:
curl -X PATCH https://api.honkio.ca/v1/push/PUSH_ID -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" -d '{ "scheduled_at": "2026-10-02T09:00:00-04:00" }'
curl -X DELETE https://api.honkio.ca/v1/push/PUSH_ID -H "Authorization: Bearer mk_live_YOUR_KEY"

Une notification programmée doit partir dans les 24 heures qui suivent son scheduled_at. Pour une limite plus serrée, ajoutez expires_at : une date et heure ISO 8601 avec un décalage, de 1 minute à 24 heures après scheduled_at, acceptée seulement avec lui (clés de test comprises ; toute autre valeur donne un 422 VALIDATION_ERROR). Une notification qui ne peut pas partir avant sa limite échoue avec le failure_code SCHEDULED_SEND_EXPIRED : rien n'est envoyé, elle est remboursée comme pour une annulation, et push.failed est déclenché. PATCH /v1/push/:id accepte aussi expires_at, vérifié par rapport au nouveau scheduled_at, ou null pour le délai par défaut de 24 heures ; s'il est omis, celui qui est enregistré est gardé tant qu'il convient encore à la nouvelle heure et abandonné sinon, ce qui ramène le délai par défaut de 24 heures. Chaque notification relue porte expires_at, null pour le délai par défaut de 24 heures.

À l'heure prévue, elle part comme toute autre notification, évaluée à ce moment : si le compte a été suspendu ou si les notifications ont été désactivées pour lui depuis (PUSH_DISABLED), la notification échoue et est remboursée ; un appareil désactivé depuis est un envoi refusé et remboursé ; et un SMS de repli applique toutes les règles d'un SMS envoyé à ce moment, donc un destinataire qui s'est désabonné ne reçoit pas de texto. Une notification de test passe par la livraison simulée comme toute notification de test.

Se replier sur un SMS

Ajoutez fallback.sms avec to, from et body, et honkio envoie ce SMS quand aucun appareil n'accepte la notification. from est obligatoire et doit être un numéro qui vous appartient, comme pour POST /v1/messages. La clé doit pouvoir envoyer des messages en plus des notifications (sinon 403 FORBIDDEN), et le doit encore au moment de l'envoi du SMS : si elle a été révoquée ou a perdu ce droit entre-temps, la notification échoue avec FORBIDDEN et aucun SMS ne part.

const { data: push, error } = await honkio.push.send({
  appId: 'APP_ID',
  to: { userId: 'user_1042' },
  title: 'Your code',
  body: '123456',
  fallback: {
    sms: { to: '+14165550123', from: '+14165550100', body: 'Your Acme code is 123456' },
  },
}, { idempotencyKey: 'login-code-1042-2026-11-03' })
if (error) throw new Error(error.message)

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",
    fallback={"sms": {"to": "+14165550123", "from": "+14165550100", "body": "Your Acme code is 123456"}},
    idempotency_key="login-code-1042-2026-11-03",
)

<?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',
    'fallback' => [
        'sms' => ['to' => '+14165550123', 'from' => '+14165550100', 'body' => 'Your Acme code is 123456'],
    ],
], 'login-code-1042-2026-11-03');

<?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)
            ->fallbackSms($notifiable->phone_number, '+14165550100', "Your Acme code is {$this->code}");
    }
}

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",
    "fallback": {
      "sms": { "to": "+14165550123", "from": "+14165550100", "body": "Your Acme code is 123456" }
    }
  }'

Le SMS est envoyé quand chaque envoi à un appareil a échoué : aucun appareil actif, un jeton refusé, un identifiant refusé ou absent, ou Apple ou Google qui échouent encore après la fenêtre de reprise. Il n'est pas envoyé si un appareil a été accepté.

Accepté ne veut pas dire vu. Une fois qu'Apple ou Google accepte une notification, le travail de honkio est terminé. honkio ne peut pas savoir si le téléphone était éteint, sans connexion ou avec les notifications désactivées : une notification acceptée ne se replie donc jamais sur un SMS.

Le SMS passe par toutes les règles qu'applique POST /v1/messages : consentement, désabonnements, limites d'envoi, numéro de mobile vérifié du compte et solde. Ses vérifications statiques (le numéro vous appartient et peut envoyer, la destination, le contenu et sa longueur) s'exécutent à l'appel de POST /v1/push, de sorte qu'un repli défectueux échoue tout de suite. Les vérifications liées au destinataire ne s'exécutent qu'à l'envoi du SMS : une notification qui n'a pas besoin de SMS n'est donc jamais refusée pour une raison de SMS.

La notification passe à fell_back, et fallback_message_id désigne le message, facturé au prix normal d'un SMS et qui déclenche les événements de message habituels. Si le SMS est refusé, la notification passe à failed et fallback_reason porte le code d'erreur du SMS. Un SMS que l'opérateur ne confirme pas à temps compte tout de même comme fell_back : le statut du message et ses webhooks donnent le résultat.

Sans appareil actif et avec un repli, honkio saute la notification et envoie le SMS tout de suite. La notification elle-même n'est pas facturée.

Reprises

Un échec récupérable d'Apple ou de Google, comme un service occupé ou indisponible, est repris avec un délai croissant. Avec un repli, honkio reprend pendant au plus 60 secondes environ, puis se replie. Sans repli, il fait au plus trois tentatives en environ 60 secondes, puis l'envoi échoue.

Un échec permanent (jeton invalide, identifiant refusé ou absent) n'est jamais repris. Un SMS de repli refusé pour une raison récupérable, comme une limite de débit ou un opérateur indisponible, est repris jusqu'à environ deux minutes avant que la notification échoue.

Prix et allocation gratuite

5,00 $ par 1 000 après 2 500 gratuits chaque mois.

Vous payez par appareil qu'Apple ou Google accepte. Un appareil qui refuse la notification n'est pas facturé. Les 2 500 premiers envois acceptés en production de chaque mois civil (heure de l'Est) sont gratuits, sans report. Les notifications de test sont gratuites et ne comptent pas. GET /v1/push/usage indique free_used et free_monthly. Un SMS de repli est facturé comme un SMS, sur son propre message.

Tant qu'un loyer est dû pour un numéro libéré, les notifications en production sont refusées, même celles que l'allocation gratuite couvrirait. Une limite quotidienne de notifications s'applique à chaque compte, et le mode test est limité à 1 000 par jour : au-delà, l'appel donne un 429 PUSH_DAILY_CAP.

Erreurs

Erreurs propres au push, en plus des erreurs habituelles de validation et d'authentification :

Webhooks

Huit événements couvrent les notifications, les appareils et les identifiants. Les charges contiennent des identifiants, un statut et des codes d'erreur, jamais le contenu, ainsi que livemode. Les événements de message d'un SMS de repli se déclenchent comme d'habitude.