Référence de l’API

Notify

Une notification à l’un de vos utilisateurs, par push, SMS ou courriel dans l’ordre de votre choix, facturée seulement sur le canal qui la livre.

post/v1/notify

Envoyer une notification

Permissionnotifications:wSDK Node.jshonkio.notify.send()

Essaie chaque canal dans l’ordre jusqu’à ce que l’un d’eux livre : push (tout appareil qui l’accepte compte), puis SMS, puis courriel par défaut. Un canal est ignoré quand la personne ne peut pas être jointe par ce canal (aucun appareil actif, aucun numéro de téléphone, aucune adresse courriel), quand il est désactivé et, dans l’ordre par défaut, quand la clé ne peut pas envoyer par ce canal ; chaque tentative est consignée avec sa raison. Un SMS ou un courriel que le canal refuse (consentement, désabonnement, suppression, limites d’envoi, pause, solde) passe au canal suivant, exactement là où /v1/messages ou /v1/emails le refuserait. Une notification push qu’aucun appareil n’accepte passe au canal suivant après la même attente, d’au plus une minute, qu’une notification push avec fallback.sms. Un courriel est livré dès que le service de courriel l’accepte ; un courriel refusé au moment de son expédition (une pause qui s’est terminée en échec, une suppression survenue depuis, un domaine perdu) passe au canal suivant, remboursé. Un échec signalé après que l’opérateur ou le service de courriel a accepté l’envoi (un accusé de livraison, un rebond, un rejet ultérieur) ne passe pas au canal suivant. Un courriel dont l’appel au service de courriel a échoué (SES_ERROR) compte comme non livré, est remboursé et passe au canal suivant, comme un SMS que l’opérateur n’a jamais pris ; un SMS dont l’appel à l’opérateur a expiré compte comme livré. Un canal sans verdict pendant une heure fait échouer la notification (NOTIFY_STUCK sur ce canal, les suivants ignorés avec notify_stuck) ; un courriel encore en file d’attente (une pause, le plafond quotidien) est laissé jusqu’à son terme, et s’il échoue ensuite, aucun autre canal n’est essayé. Un SMS refusé ou ralenti peut laisser un message échoué remboursé (/v1/messages) et déclencher message.failed, comme le même envoi par /v1/messages, même si le courriel livre ensuite. Seul le canal qui livre est facturé, à son prix normal ; un canal passé au suivant ne coûte rien. Un modèle est rendu une seule fois, à la création de la notification ; chaque canal envoie ce texte. Les coordonnées de la personne sont lues à ce moment aussi : un canal par lequel elle ne pouvait pas être jointe à ce moment est ignoré (no_active_device, no_phone_number, no_email) même si une coordonnée est ajoutée avant son tour, et rien n’est rendu ni conservé pour lui. Ce qui est conservé pour les canaux qui peuvent joindre la personne fait au plus 2 Mo, une fois rendu : au-delà, 422 NOTIFY_CONTENT_TOO_LARGE. Répond 202 avec la notification : delivered ou failed quand l’issue a été réglée immédiatement, pending pendant l’envoi d’une notification push ou d’un courriel. La clé a besoin de l’écriture notifications et de la lecture recipients, plus l’écriture push, messages ou emails pour chaque canal essayé ; sans channels et sans aucune des trois, 403 FORBIDDEN. from.sms est vérifié comme /v1/messages vérifie from (403 PHONE_NUMBER_NOT_OWNED, TOLL_FREE_NOT_VERIFIED, 422 MESSAGE_TOO_LONG...) quand la personne peut recevoir un SMS. La même Idempotency-Key renvoie la première notification, en attente ou non, sans second envoi ; avec un corps différent, c’est 409 IDEMPOTENCY_KEY_REUSED. Les notifications suivent le mode de la clé : une clé de test n’envoie qu’aux profils de test et ne lit que les profils et notifications de test, par le mode test de chaque canal.

Nécessite notifications:w.

Paramètres

Paramètre	Type	Description
`Idempotency-Key`en-tête	string	Au plus 255 caractères

Corps de la requête

Une notification à l’un de vos utilisateurs : qui, dans quel ordre de canaux, et quoi.

Champ	Type	Description
`user_id`obligatoire	string	Votre propre identifiant pour la personne : son profil de destinataire (/v1/recipients) et le user_id sous lequel ses appareils push sont enregistrés. Au moins 1 caractères Au plus 255 caractères
`channels`	string[]	L’ordre d’essai, chaque canal au plus une fois : push, sms, email. Le premier qui livre met fin à l’envoi. Omis : push, sms, email, en ignorant tout canal désactivé ou par lequel la clé ne peut pas envoyer. Un canal indiqué ici par lequel la clé ne peut pas envoyer donne 403 FORBIDDEN. Une valeur parmi : push \| sms \| email
`text`	string	Le texte : le SMS, le corps de la notification push et le texte brut du courriel. Jusqu’à 1 600 caractères. Obligatoire sauf si vous envoyez un modèle. Au moins 1 caractères Au plus 1600 caractères
`title`	string	Le titre de la notification push. Pas avec un modèle. Au moins 1 caractères Au plus 1000 caractères
`subject`	string	L’objet du courriel. Obligatoire quand le courriel peut être essayé et que la personne a une adresse courriel, sauf si vous envoyez un modèle. Au moins 1 caractères Au plus 998 caractères
`html`	string	Le corps HTML du courriel. Facultatif : sans lui, le courriel est en texte brut.
`template`	string	L’identifiant ou l’alias d’un modèle (/v1/templates), à la place de text, title, subject et html : chaque canal envoie sa propre partie. Une clé de production envoie la version publiée, une clé de test le brouillon. Dans l’ordre par défaut, un canal pour lequel le modèle n’a pas de partie est ignoré ; indiqué dans channels, il donne 422 TEMPLATE_CHANNEL_MISSING. Au moins 1 caractères Au plus 200 caractères
`variables`	object	Les valeurs des variables du modèle. Une variable sans valeur ni valeur de repli fait refuser la notification (422 EMAIL_TEMPLATE_VARIABLE_MISSING, details.keys). Seulement avec template.
`language`	string	en ou fr : la version linguistique du modèle, à la place de la langue du profil. Une partie qui manque dans cette langue vient de la langue par défaut du modèle. Seulement avec template. Une valeur parmi : en \| fr
`from`	object	Les expéditeurs. 422 NOTIFY_SENDER_REQUIRED quand un canal qui sera essayé peut joindre la personne et n’en a pas.
`sms`	string	L’un de vos numéros, au format E.164, depuis lequel envoyer le SMS. Au moins 1 caractères Au plus 32 caractères
`email`	string	Une adresse sur l’un de vos domaines vérifiés. L’adresse d’expéditeur par défaut d’un modèle la remplit quand vous l’omettez. Au moins 1 caractères Au plus 998 caractères
`push_app_id`	string	L’application push avec laquelle envoyer. Facultative quand le compte en a exactement une. Au moins 1 caractères Au plus 100 caractères
`is_commercial`	boolean	false par défaut. true fait du volet courriel un courriel commercial, exactement comme dans /v1/emails : un consentement LCAP consigné est exigé et le pied de page de désabonnement est ajouté. Le SMS garde ses propres règles de consentement ; le push n’a pas d’indicateur de ce genre. Par défaut : false

Réponses

202La notification : delivered ou failed quand l’issue a été réglée immédiatement, pending pendant l’envoi d’une notification push ou d’un courriel. Une nouvelle tentative avec la même Idempotency-Key renvoie la première notification dans son état actuel.

Champ	Type	Description
`id`obligatoire	string	ntf_…
`object`obligatoire	string	Une valeur parmi : notification
`user_id`obligatoire	string
`status`obligatoire	string	pending pendant l’envoi d’une notification push ; delivered dès qu’un canal l’a prise ; failed quand chaque canal a été ignoré, a refusé ou a échoué. Une valeur parmi : pending \| delivered \| failed
`channel`obligatoire	string	Le canal qui l’a livrée. Une valeur parmi : push \| sms \| email Peut être null
`message_id`obligatoire	string	Le SMS (/v1/messages) qui l’a livrée. Peut être null
`email_id`obligatoire	string	Le courriel (/v1/emails) qui l’a livrée. Peut être null
`push_id`	string	La notification push (/v1/push) qui l’a livrée. Peut être null
`attempts[]`obligatoire	object[]	Chaque canal essayé, dans l’ordre.
`channel`obligatoire	string	Une valeur parmi : push \| sms \| email
`outcome`obligatoire	string	delivered : le canal l’a prise (une notification push acceptée par un appareil, un SMS pris par l’opérateur, un courriel accepté par le service de courriel). pending : une notification push ou un courriel est en cours d’envoi. skipped : le canal n’a pas pu être essayé (aucun appareil, numéro de téléphone ou adresse courriel ; canal désactivé ou non permis à la clé ; aucune partie du modèle pour ce canal). refused : le canal a refusé l’envoi, comme son propre point de terminaison l’aurait fait. failed : une notification push qu’aucun appareil n’a acceptée, ou un courriel refusé au moment de son expédition, y compris un appel échoué au service de courriel (SES_ERROR), remboursé ; NOTIFY_STUCK quand un canal est resté sans verdict pendant une heure (un courriel encore en file d’attente est laissé jusqu’à son terme ; s’il échoue ensuite, les canaux suivants sont ignorés avec notify_stuck et aucun n’est essayé). Une valeur parmi : delivered \| pending \| skipped \| refused \| failed
`reason`obligatoire	string	La raison pour laquelle il a été ignoré, refusé ou a échoué : une raison en minuscules (no_active_device, no_push_app, no_phone_number, no_email, no_sender, push_unavailable, push_disabled, email_unavailable, not_permitted, template_channel_missing, content_purged, notify_stuck) ou le code d’erreur propre au canal (p. ex. OPT_OUT_BLOCKED, NO_CONSENT, EMAIL_SUPPRESSED, ou ENCRYPTION_KEY_MISSING quand l’application push a require_encryption et qu’aucun des appareils de l’utilisateur n’a enregistré de clé). Null sinon. Peut être null
`livemode`obligatoire	boolean
`created_at`obligatoire	string	Format : date-time

401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
403FORBIDDEN : la clé n’a pas la lecture recipients, ne peut pas envoyer par un canal indiqué dans channels (details.channel) ou, sans channels, ne peut envoyer par aucun canal. Ou les refus que /v1/messages donne pour un from depuis lequel elle ne peut pas envoyer (PHONE_NUMBER_NOT_OWNED, PHONE_NUMBER_SUSPENDED, TOLL_FREE_NOT_VERIFIED).Le corps d’erreur standard.
404RECIPIENT_NOT_FOUND : aucun profil ni appareil push actif pour user_id dans le mode de la clé appelante. Ou NOT_FOUND (details.resource template) : aucun modèle avec cet identifiant ou cet alias.Le corps d’erreur standard.
409IDEMPOTENCY_KEY_REUSED : l’Idempotency-Key a été utilisée pour une autre notification.Le corps d’erreur standard.
422VALIDATION_ERROR ; NOTIFY_CONTENT_REQUIRED (aucun texte ni modèle, ou aucun objet quand le courriel peut être essayé : details.field, details.channel) ; NOTIFY_SENDER_REQUIRED (un canal qui sera essayé peut joindre la personne mais n’a pas d’expéditeur : details.channel) ; TEMPLATE_CHANNEL_MISSING (un canal indiqué dans channels, ou chaque canal essayé, n’a pas de partie de modèle : details.channel) ; NOTIFY_CONTENT_TOO_LARGE (ce qui serait envoyé sur les canaux qui peuvent joindre la personne, une fois rendu, dépasse 2 Mo : details.bytes, details.limit) ; EMAIL_TEMPLATE_NOT_PUBLISHED ; EMAIL_TEMPLATE_VARIABLE_MISSING (details.keys) ; MESSAGE_TOO_LONG ou une règle de contenu pour le texte, comme /v1/messages y répond.Le corps d’erreur standard.
429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { data: notification, error } = await honkio.notify.send({
  userId: 'user_1042',
  text: 'Your Acme code is 123456',
  subject: 'Your Acme code',
  from: { sms: '+1416XXXXXXX', email: 'hello@yourapp.ca' },
}, { idempotencyKey: 'login-code-1042-2026-11-03' })
if (error) throw new Error(error.message)
console.log(notification.id, notification.status, notification.channel)

curl -X POST https://api.honkio.ca/v1/notify \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_42"
  }'

get/v1/notifications

Lister les notifications

Permissionnotifications:rSDK Node.jshonkio.notifications.list()

Les plus récentes d’abord. Les notifications suivent le mode de la clé : une clé de test n’envoie qu’aux profils de test et ne lit que les profils et notifications de test, par le mode test de chaque canal.

Nécessite notifications:r.

Paramètres

Paramètre	Type	Description
`limit`requête	string	De 1 à 100. Valeur par défaut : 50.
`cursor`requête	string	La valeur next_cursor de la page précédente.
`user_id`requête	string	Seulement les notifications de cet utilisateur.
`status`requête	string	Seulement les notifications dans cet état. Une valeur parmi : pending \| delivered \| failed

Réponses

200Une page de notifications dans le mode de la clé appelante, les plus récentes d’abord.

Champ	Type	Description
`data[]`obligatoire	object[]
`id`obligatoire	string	ntf_…
`object`obligatoire	string	Une valeur parmi : notification
`user_id`obligatoire	string
`status`obligatoire	string	pending pendant l’envoi d’une notification push ; delivered dès qu’un canal l’a prise ; failed quand chaque canal a été ignoré, a refusé ou a échoué. Une valeur parmi : pending \| delivered \| failed
`channel`obligatoire	string	Le canal qui l’a livrée. Une valeur parmi : push \| sms \| email Peut être null
`message_id`obligatoire	string	Le SMS (/v1/messages) qui l’a livrée. Peut être null
`email_id`obligatoire	string	Le courriel (/v1/emails) qui l’a livrée. Peut être null
`push_id`	string	La notification push (/v1/push) qui l’a livrée. Peut être null
`attempts[]`obligatoire	object[]	Chaque canal essayé, dans l’ordre.
`channel`obligatoire	string	Une valeur parmi : push \| sms \| email
`outcome`obligatoire	string	delivered : le canal l’a prise (une notification push acceptée par un appareil, un SMS pris par l’opérateur, un courriel accepté par le service de courriel). pending : une notification push ou un courriel est en cours d’envoi. skipped : le canal n’a pas pu être essayé (aucun appareil, numéro de téléphone ou adresse courriel ; canal désactivé ou non permis à la clé ; aucune partie du modèle pour ce canal). refused : le canal a refusé l’envoi, comme son propre point de terminaison l’aurait fait. failed : une notification push qu’aucun appareil n’a acceptée, ou un courriel refusé au moment de son expédition, y compris un appel échoué au service de courriel (SES_ERROR), remboursé ; NOTIFY_STUCK quand un canal est resté sans verdict pendant une heure (un courriel encore en file d’attente est laissé jusqu’à son terme ; s’il échoue ensuite, les canaux suivants sont ignorés avec notify_stuck et aucun n’est essayé). Une valeur parmi : delivered \| pending \| skipped \| refused \| failed
`reason`obligatoire	string	La raison pour laquelle il a été ignoré, refusé ou a échoué : une raison en minuscules (no_active_device, no_push_app, no_phone_number, no_email, no_sender, push_unavailable, push_disabled, email_unavailable, not_permitted, template_channel_missing, content_purged, notify_stuck) ou le code d’erreur propre au canal (p. ex. OPT_OUT_BLOCKED, NO_CONSENT, EMAIL_SUPPRESSED, ou ENCRYPTION_KEY_MISSING quand l’application push a require_encryption et qu’aucun des appareils de l’utilisateur n’a enregistré de clé). Null sinon. Peut être null
`livemode`obligatoire	boolean
`created_at`obligatoire	string	Format : date-time
`has_more`obligatoire	boolean
`next_cursor`obligatoire	string	Passez-le comme cursor pour la page suivante. Null sur la dernière page. Peut être null

401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
403La clé API ne dispose pas de la permission requise pour cette opération, ou le compte est suspendu ou fermé.Le corps d’erreur standard.
422VALIDATION_ERROR : limit n’est pas un entier positif.Le corps d’erreur standard.
429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { data, error } = await honkio.notifications.list({ userId: 'user_1042', status: 'failed', limit: 20 })
if (error) throw new Error(error.message)
for (const notification of data.data) console.log(notification.id, notification.status)

curl https://api.honkio.ca/v1/notifications \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

get/v1/notifications/{id}

Obtenir une notification

Permissionnotifications:rSDK Node.jshonkio.notifications.get()

Les notifications suivent le mode de la clé : une clé de test n’envoie qu’aux profils de test et ne lit que les profils et notifications de test, par le mode test de chaque canal.

Nécessite notifications:r.

Paramètres

Paramètre	Type	Description
`id`obligatoirechemin	string	L’identifiant de la notification (ntf_…).

Réponses

200La notification.

Champ	Type	Description
`id`obligatoire	string	ntf_…
`object`obligatoire	string	Une valeur parmi : notification
`user_id`obligatoire	string
`status`obligatoire	string	pending pendant l’envoi d’une notification push ; delivered dès qu’un canal l’a prise ; failed quand chaque canal a été ignoré, a refusé ou a échoué. Une valeur parmi : pending \| delivered \| failed
`channel`obligatoire	string	Le canal qui l’a livrée. Une valeur parmi : push \| sms \| email Peut être null
`message_id`obligatoire	string	Le SMS (/v1/messages) qui l’a livrée. Peut être null
`email_id`obligatoire	string	Le courriel (/v1/emails) qui l’a livrée. Peut être null
`push_id`	string	La notification push (/v1/push) qui l’a livrée. Peut être null
`attempts[]`obligatoire	object[]	Chaque canal essayé, dans l’ordre.
`channel`obligatoire	string	Une valeur parmi : push \| sms \| email
`outcome`obligatoire	string	delivered : le canal l’a prise (une notification push acceptée par un appareil, un SMS pris par l’opérateur, un courriel accepté par le service de courriel). pending : une notification push ou un courriel est en cours d’envoi. skipped : le canal n’a pas pu être essayé (aucun appareil, numéro de téléphone ou adresse courriel ; canal désactivé ou non permis à la clé ; aucune partie du modèle pour ce canal). refused : le canal a refusé l’envoi, comme son propre point de terminaison l’aurait fait. failed : une notification push qu’aucun appareil n’a acceptée, ou un courriel refusé au moment de son expédition, y compris un appel échoué au service de courriel (SES_ERROR), remboursé ; NOTIFY_STUCK quand un canal est resté sans verdict pendant une heure (un courriel encore en file d’attente est laissé jusqu’à son terme ; s’il échoue ensuite, les canaux suivants sont ignorés avec notify_stuck et aucun n’est essayé). Une valeur parmi : delivered \| pending \| skipped \| refused \| failed
`reason`obligatoire	string	La raison pour laquelle il a été ignoré, refusé ou a échoué : une raison en minuscules (no_active_device, no_push_app, no_phone_number, no_email, no_sender, push_unavailable, push_disabled, email_unavailable, not_permitted, template_channel_missing, content_purged, notify_stuck) ou le code d’erreur propre au canal (p. ex. OPT_OUT_BLOCKED, NO_CONSENT, EMAIL_SUPPRESSED, ou ENCRYPTION_KEY_MISSING quand l’application push a require_encryption et qu’aucun des appareils de l’utilisateur n’a enregistré de clé). Null sinon. Peut être null
`livemode`obligatoire	boolean
`created_at`obligatoire	string	Format : date-time

401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
403La clé API ne dispose pas de la permission requise pour cette opération, ou le compte est suspendu ou fermé.Le corps d’erreur standard.
404NOT_FOUND : aucune notification avec cet identifiant dans le mode de la clé appelante.Le corps d’erreur standard.
429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { data: notification, error } = await honkio.notifications.get('NOTIFICATION_ID')
if (error) throw new Error(error.message)
for (const attempt of notification.attempts) console.log(attempt.channel, attempt.outcome, attempt.reason)

curl https://api.honkio.ca/v1/notifications/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"