Référence de l’API

Messages

Envoyer et recevoir des SMS.

get/v1/messages

Lister les messages

Permissionmessages:rSDK Node.jshonkio.messages.list()

Nécessite messages:r.

Paramètres

Paramètre	Type	Description
`q`requête	string	Rechercher par numéro de téléphone (correspondance partielle sur to/from)
`from`requête	string
`to`requête	string
`status`requête	string	Une valeur parmi : QUEUED \| SCHEDULED \| SENDING \| SENT \| DELIVERED \| FAILED \| UNDELIVERED \| RECEIVED \| CANCELLED
`direction`requête	string	Une valeur parmi : OUTBOUND \| INBOUND
`mode`requête	string	Uniquement les messages de ce mode. Sans ce paramètre, une clé de production liste les deux modes (chaque message porte son propre `mode`). Une clé de test ne liste que des messages TEST : avec une clé de test, LIVE ne liste donc rien. Une valeur parmi : LIVE \| TEST
`page`requête	integer	Minimum : 1 Par défaut : 1
`limit`requête	integer	Minimum : 1 Maximum : 100 Par défaut : 20
`date_from`requête	string	Format : date
`date_to`requête	string	Format : date

Réponses

200Une page de messages, du plus récent au plus ancien.

Champ	Type	Description
`data[]`obligatoire	object[]
`id`obligatoire	string
`direction`obligatoire	string	Une valeur parmi : OUTBOUND \| INBOUND
`from`obligatoire	string
`to`obligatoire	string
`body`obligatoire	string	Vaut null une fois le corps purgé (voir body_purged) et pour un code de vérification (NPU), qui n’est jamais stocké. Peut être null
`body_purged`obligatoire	boolean
`status`obligatoire	string	SCHEDULED : accepté avec scheduled_at et en attente de cette heure. CANCELLED : un message programmé annulé avant son départ ; ses frais ont été remboursés. Une valeur parmi : QUEUED \| SCHEDULED \| SENDING \| SENT \| DELIVERED \| FAILED \| UNDELIVERED \| RECEIVED \| CANCELLED
`segment_count`obligatoire	integer	Nombre de segments SMS en lesquels l’opérateur a divisé le corps (entrant : tel que reçu). La facturation se fait par segment. Peut être null
`mode`obligatoire	string	Les messages TEST sont simulés : ils ne sont jamais transmis à un opérateur ni facturés. Une valeur parmi : LIVE \| TEST
`is_verification`obligatoire	boolean	Le SMS contenant le code de vérification (NPU) d’une vérification. Son corps n’est jamais stocké.
`auto_reply_keyword`obligatoire	string	Défini pour la confirmation automatique envoyée lorsqu’un destinataire envoie STOP, START ou HELP par texto. Ce n’est pas vous qui l’avez envoyée, et elle ne vous est jamais facturée. Son corps peut être null pendant quelques minutes après l’envoi, jusqu’à ce que l’opérateur en communique le texte. Null pour tous les autres messages. Une valeur parmi : STOP \| START \| HELP Peut être null
`cost_cents`obligatoire	integer	Coût réel de ce message, en cents CAD : message_cost_cents multiplié par le nombre de segments selon le découpage de l’opérateur, ajusté au décompte de l’opérateur une fois l’envoi accepté (il peut donc différer d’une estimation faite avant l’envoi). 0 lorsque l’opérateur a refusé l’envoi d’emblée (remboursé ou jamais facturé), ainsi que pour une confirmation automatique STOP/START/HELP (auto_reply_keyword), qui n’est jamais facturée. Un message accepté par l’opérateur mais qui n’a pas pu être livré reste facturé. Les messages reçus portent les frais de réception. Pour un message TEST, il s’agit de ce qu’aurait coûté l’envoi ; rien n’a été facturé.
`error_code`obligatoire	string	Défini pour les messages FAILED et UNDELIVERED : le code de l’opérateur figurant dans l’accusé de réception (p. ex. 30003), ou le code de la plateforme pour un rejet synchrone (CARRIER_ERROR, INVALID_PHONE_NUMBER, NOT_A_MOBILE_NUMBER, INSUFFICIENT_BALANCE, RENT_OWED). CARRIER_THROTTLED quand l’opérateur nous a demandé de ralentir, ou a retiré le message de la file pleine du numéro d’envoi avant d’essayer le destinataire : remboursé, et sans risque à renvoyer. CARRIER_LOST quand l’opérateur a accepté le message puis l’a perdu : aucun accusé n’est jamais arrivé, et trois jours plus tard l’opérateur n’en avait aucune trace ; remboursé, et sans risque à renvoyer avec une nouvelle Idempotency-Key. Peut être null
`error_message`obligatoire	string	Raison lisible de l’échec d’un message FAILED ou UNDELIVERED, fournie par l’opérateur lorsqu’il en a donné une. Peut être null
`sent_at`obligatoire	string	Format : date-time Peut être null
`created_at`obligatoire	string	Format : date-time
`casl_consent_type`obligatoire	string	Le consentement LCAP sur lequel reposait un envoi sortant. Null pour les messages entrants et en mode test, pour les réponses STOP/HELP/START imposées par l’opérateur, et pour les envois effectués avant l’enregistrement de cette donnée (18 septembre 2026). Une valeur parmi : EXPRESS \| IMPLIED Peut être null
`delivered_at`obligatoire	string	Moment où l’opérateur a signalé la livraison du message à l’appareil. Format : date-time Peut être null
`scheduled_at`obligatoire	string	L’heure à laquelle un message programmé doit partir (ou devait partir). Null pour un message envoyé immédiatement. Format : date-time Peut être null
`expires_at`obligatoire	string	L’expires_at donné à un message programmé : l’heure limite de son départ. Null quand aucun n’a été donné, ce qui veut dire scheduled_at plus 24 heures. Un message qui ne peut pas partir d’ici là échoue avec l’error_code SCHEDULED_SEND_EXPIRED et est remboursé. Format : date-time Peut être null
`meta`obligatoire	object	Pagination par numéro de page, renvoyée sous `meta` par la liste des messages.
`page`obligatoire	integer
`limit`obligatoire	integer
`total`obligatoire	integer
`pages`obligatoire	integer

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 : la requête n’a pas passé la validation ; details indique les champs en cause.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.messages.list({ direction: 'INBOUND', limit: 20 })
if (error) throw new Error(error.message)
for (const message of data.data) console.log(message.from, message.body)

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

post/v1/messages

Envoyer un SMS

Permissionmessages:wSDK Node.jshonkio.messages.send()

Les envois réels sont contrôlés avant toute facturation : 403 SENDING_PAUSED, 429 DAILY_LIMIT_REACHED / NUMBER_RATE_LIMITED / RECIPIENT_RATE_LIMITED (NUMBER_RATE_LIMITED : le numéro d’envoi a déjà une minute de segments de message en attente chez l’opérateur, qui envoie 10 segments par minute depuis un numéro local ; RECIPIENT_RATE_LIMITED : 30 messages par heure et 100 par jour vers un même destinataire ; l’en-tête Retry-After est renseigné dans les deux cas) / FANOUT_LIMIT_REACHED, 422 UNDELIVERABLE_NUMBER (trois échecs consécutifs de l’opérateur vers le numéro, quel que soit le client, l’inscrivent sur la liste pour 90 jours), 422 NOT_A_MOBILE_NUMBER (une destination fixe ou VoIP, refusée par l’opérateur avant l’envoi), 422 RESERVED_DESTINATION (un central réservé comme 555-XXXX, N11 ou un code de test d’opérateur, refusé ici dans les deux modes), 422 LINK_SHORTENER_BLOCKED, ainsi que les codes liés à la LCAP. Depuis un numéro sans frais : 403 TOLL_FREE_NOT_VERIFIED tant que la vérification sans frais du numéro n’est pas approuvée (clés de test comprises), et 451 DOUBLE_OPT_IN_REQUIRED tant que le destinataire n’a pas répondu OUI à une confirmation de consentement envoyée depuis ce numéro (POST /v1/compliance/opt-in-confirmations). Un envoi refusé ne coûte rien. 503 CARRIER_UNAVAILABLE signifie que l’opérateur n’a pas pu être joint : rien n’a été envoyé ni facturé, réessayez sous peu. 503 CARRIER_THROTTLED signifie que l’opérateur nous a demandé de ralentir et n’a pas pris le message : rien n’a été facturé ; réessayez après le délai Retry-After avec la même Idempotency-Key, ce qui l’envoie. 503 CARRIER_TIMEOUT signifie que l’opérateur n’a pas répondu à temps : le message a pu être envoyé ou non, son montant est retenu puis remboursé dès que les relevés de l’opérateur montrent qu’il n’a pas été envoyé, et une nouvelle tentative avec la même Idempotency-Key renvoie le message en échec au lieu de l’envoyer de nouveau. Envoyez un en-tête Idempotency-Key depuis tout processus qui effectue de nouvelles tentatives : la même clé renvoie le message d’origine. Un envoi réel répond avec estimated_send_at, une estimation du moment où l’opérateur l’enverra. Avec scheduled_at (de 1 minute à 30 jours à l’avance), le message est accepté avec le statut SCHEDULED et facturé tout de suite ; toutes les vérifications ci-dessus sauf les limites d’envoi se font maintenant, et toutes se refont à l’heure prévue : un destinataire qui s’est désabonné depuis, une clé révoquée, un numéro ou un compte suspendu, ou un loyer dû le fait échouer (remboursé, message.failed), tandis qu’une limite d’envoi, une pause, ou un opérateur qui le ralentit ou qu’on ne peut pas joindre le retient, et il est retenté jusqu’à ce qu’il puisse partir. Il doit partir au plus tard à expires_at (de 1 minute à 24 heures après scheduled_at ; par défaut, scheduled_at plus 24 heures) : sinon, il échoue avec l’error_code SCHEDULED_SEND_EXPIRED, est remboursé et déclenche message.failed. D’ici là, PATCH /v1/messages/{id} le déplace et DELETE /v1/messages/{id} l’annule et rembourse les frais. À la place de body, template (l’identifiant ou l’alias d’un modèle), variables et language (en ou fr) envoient la partie SMS de ce modèle, rendue : la version publiée avec une clé de production, le brouillon avec une clé de test. Une langue sans partie SMS utilise celle de la langue par défaut ; un modèle sans partie SMS répond 422 TEMPLATE_CHANNEL_MISSING. Le texte rendu est soumis aux 1 600 caractères de body, et c’est lui qui est enregistré, facturé et envoyé.

Nécessite messages:w.

Paramètres

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

Corps de la requête

Champ	Type	Description
`from`obligatoire	string	Numéro d’envoi (E.164, doit appartenir au compte)
`to`obligatoire	string	Numéro du destinataire (E.164, numéros canadiens seulement)
`body`	string	Jusqu’à 1 600 caractères et 10 segments SMS (environ 1 530 caractères GSM-7 ou 670 caractères Unicode). Un corps plus long est refusé avec 422 MESSAGE_TOO_LONG avant toute facturation. Facturé par segment, selon le découpage effectué par l’opérateur. Obligatoire sauf si vous envoyez un modèle ; interdit avec un modèle. Au plus 1600 caractères
`template`	string	L’identifiant ou l’alias d’un modèle (/v1/templates). Sa partie pour ce canal est rendue et envoyée à la place de votre propre texte. Une clé de production envoie la version publiée, une clé de test le brouillon. Avec un Idempotency-Key, une nouvelle tentative est comparée à la requête telle qu’elle a été envoyée : l’identifiant du modèle et son alias, 1 et « 1 » comme valeur de variable, et une langue omise et la langue par défaut indiquée comptent comme des requêtes différentes (409 IDEMPOTENCY_KEY_REUSED). 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 l’envoi (422 EMAIL_TEMPLATE_VARIABLE_MISSING, details.keys). Seulement avec template.
`language`	string	en ou fr : la version linguistique à rendre. Une partie qui manque à cette langue vient de la langue par défaut du modèle. Omettez-le pour la langue par défaut. Seulement avec template. Une valeur parmi : en \| fr
`skip_consent_check`	boolean	Ignorer le contrôle du consentement LCAP. Clés de mode test uniquement : une clé de production reçoit 403 FORBIDDEN. À utiliser seulement si vous avez un consentement consigné en dehors de HonkIO.
`scheduled_at`	string	Envoi différé : une date et heure ISO 8601 avec décalage horaire, de 1 minute à 30 jours à l’avance. Peut être null
`expires_at`	string	L’heure limite de départ de l’envoi programmé : de 1 minute à 24 heures après scheduled_at, et seulement avec lui. Sans elle, scheduled_at plus 24 heures. Un envoi qui ne peut pas partir d’ici là échoue avec SCHEDULED_SEND_EXPIRED et est remboursé. Peut être null

Réponses

201Message envoyé (LIVE) ou simulé (TEST). Avec une Idempotency-Key déjà utilisée pour les mêmes from, to et body, le message d’origine.

Champ	Type	Description
`id`obligatoire	string
`direction`obligatoire	string	Une valeur parmi : OUTBOUND \| INBOUND
`from`obligatoire	string
`to`obligatoire	string
`body`obligatoire	string	Vaut null une fois le corps purgé (voir body_purged) et pour un code de vérification (NPU), qui n’est jamais stocké. Peut être null
`body_purged`obligatoire	boolean
`status`obligatoire	string	SCHEDULED : accepté avec scheduled_at et en attente de cette heure. CANCELLED : un message programmé annulé avant son départ ; ses frais ont été remboursés. Une valeur parmi : QUEUED \| SCHEDULED \| SENDING \| SENT \| DELIVERED \| FAILED \| UNDELIVERED \| RECEIVED \| CANCELLED
`segment_count`obligatoire	integer	Nombre de segments SMS en lesquels l’opérateur a divisé le corps (entrant : tel que reçu). La facturation se fait par segment. Peut être null
`mode`obligatoire	string	Les messages TEST sont simulés : ils ne sont jamais transmis à un opérateur ni facturés. Une valeur parmi : LIVE \| TEST
`is_verification`obligatoire	boolean	Le SMS contenant le code de vérification (NPU) d’une vérification. Son corps n’est jamais stocké.
`auto_reply_keyword`obligatoire	string	Défini pour la confirmation automatique envoyée lorsqu’un destinataire envoie STOP, START ou HELP par texto. Ce n’est pas vous qui l’avez envoyée, et elle ne vous est jamais facturée. Son corps peut être null pendant quelques minutes après l’envoi, jusqu’à ce que l’opérateur en communique le texte. Null pour tous les autres messages. Une valeur parmi : STOP \| START \| HELP Peut être null
`cost_cents`obligatoire	integer	Coût réel de ce message, en cents CAD : message_cost_cents multiplié par le nombre de segments selon le découpage de l’opérateur, ajusté au décompte de l’opérateur une fois l’envoi accepté (il peut donc différer d’une estimation faite avant l’envoi). 0 lorsque l’opérateur a refusé l’envoi d’emblée (remboursé ou jamais facturé), ainsi que pour une confirmation automatique STOP/START/HELP (auto_reply_keyword), qui n’est jamais facturée. Un message accepté par l’opérateur mais qui n’a pas pu être livré reste facturé. Les messages reçus portent les frais de réception. Pour un message TEST, il s’agit de ce qu’aurait coûté l’envoi ; rien n’a été facturé.
`error_code`obligatoire	string	Défini pour les messages FAILED et UNDELIVERED : le code de l’opérateur figurant dans l’accusé de réception (p. ex. 30003), ou le code de la plateforme pour un rejet synchrone (CARRIER_ERROR, INVALID_PHONE_NUMBER, NOT_A_MOBILE_NUMBER, INSUFFICIENT_BALANCE, RENT_OWED). CARRIER_THROTTLED quand l’opérateur nous a demandé de ralentir, ou a retiré le message de la file pleine du numéro d’envoi avant d’essayer le destinataire : remboursé, et sans risque à renvoyer. CARRIER_LOST quand l’opérateur a accepté le message puis l’a perdu : aucun accusé n’est jamais arrivé, et trois jours plus tard l’opérateur n’en avait aucune trace ; remboursé, et sans risque à renvoyer avec une nouvelle Idempotency-Key. Peut être null
`error_message`obligatoire	string	Raison lisible de l’échec d’un message FAILED ou UNDELIVERED, fournie par l’opérateur lorsqu’il en a donné une. Peut être null
`sent_at`obligatoire	string	Format : date-time Peut être null
`created_at`obligatoire	string	Format : date-time
`casl_consent_type`obligatoire	string	Le consentement LCAP sur lequel reposait un envoi sortant. Null pour les messages entrants et en mode test, pour les réponses STOP/HELP/START imposées par l’opérateur, et pour les envois effectués avant l’enregistrement de cette donnée (18 septembre 2026). Une valeur parmi : EXPRESS \| IMPLIED Peut être null
`delivered_at`obligatoire	string	Moment où l’opérateur a signalé la livraison du message à l’appareil. Format : date-time Peut être null
`scheduled_at`obligatoire	string	L’heure à laquelle un message programmé doit partir (ou devait partir). Null pour un message envoyé immédiatement. Format : date-time Peut être null
`expires_at`obligatoire	string	L’expires_at donné à un message programmé : l’heure limite de son départ. Null quand aucun n’a été donné, ce qui veut dire scheduled_at plus 24 heures. Un message qui ne peut pas partir d’ici là échoue avec l’error_code SCHEDULED_SEND_EXPIRED et est remboursé. Format : date-time Peut être null
`estimated_send_at`obligatoire	string	Une estimation du moment où l’opérateur commencera à envoyer ce message, d’après les segments déjà en attente sur le numéro d’envoi (un numéro local en envoie 10 par minute). Proche de maintenant quand rien n’attend. Pour un envoi réel programmé, son scheduled_at. Null en mode test et lors d’une nouvelle tentative qui a retourné un envoi antérieur. Format : date-time Peut être null

401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
402INSUFFICIENT_BALANCE : le solde ne couvre pas l’envoi. RENT_OWED : un loyer est dû pour un numéro libéré pendant sa suspension; rechargez d’abord pour le payer. Aussi PAYMENT_REQUIRED lorsqu’une clé de production est utilisée avant la première recharge.Le corps d’erreur standard.
403FORBIDDEN (skip_consent_check avec une clé de production, ou la clé n’a pas l’autorisation messages:w), ACCOUNT_NOT_VERIFIED, PHONE_NUMBER_NOT_OWNED, ALLOW_LIST_BLOCKED, DENY_LIST_BLOCKED, SENDING_PAUSED, ou TOLL_FREE_NOT_VERIFIED (un numéro from sans frais dont la vérification sans frais n’est pas approuvée ; clés de test comprises).Le corps d’erreur standard.
409PHONE_NUMBER_SUSPENDED (le numéro from est suspendu pour loyer impayé) ou IDEMPOTENCY_KEY_REUSED (la clé a été utilisée pour des valeurs from, to ou body différentes).Le corps d’erreur standard.
422VALIDATION_ERROR, NON_CANADIAN_NUMBER, RESERVED_DESTINATION, MESSAGE_TOO_LONG, LINK_SHORTENER_BLOCKED, UNDELIVERABLE_NUMBER, NOT_A_MOBILE_NUMBER, INVALID_PHONE_NUMBER (l’opérateur a jugé le numéro invalide) ou IDEMPOTENCY_KEY_RESERVED (l’Idempotency-Key commence par notify:, un préfixe que HonkIO réserve). Un envoi refusé ne coûte rien.Le corps d’erreur standard.
429DAILY_LIMIT_REACHED, FANOUT_LIMIT_REACHED, NUMBER_RATE_LIMITED ou RECIPIENT_RATE_LIMITED (Retry-After est défini pour les deux limites de débit), ou RATE_LIMITED au-delà de 100 requêtes par seconde. NUMBER_RATE_LIMITED : le numéro d’envoi a déjà une minute de segments de message en attente chez l’opérateur (un numéro local en envoie 10 par minute) ; attendez le délai Retry-After. SCHEDULED_LIMIT_REACHED (avec scheduled_at) : le compte a déjà 10 000 messages réels programmés, ou 1 000 messages de test programmés ; rien n’est programmé ni facturé (details contient mode, limit, scheduled et requested).Le corps d’erreur standard.
451Le contrôle LCAP a refusé le destinataire : NO_CONSENT, OPT_OUT_BLOCKED ou CONSENT_EXPIRED. Depuis un numéro sans frais, aussi DOUBLE_OPT_IN_REQUIRED : le destinataire n’a pas encore répondu OUI à une confirmation de consentement envoyée depuis ce numéro (POST /v1/compliance/opt-in-confirmations).Le corps d’erreur standard.
500Erreur de serveur inattendue.Le corps d’erreur standard.
502CARRIER_ERROR : l’opérateur a refusé l’envoi. Tout montant facturé est remboursé.Le corps d’erreur standard.
503CARRIER_UNAVAILABLE : impossible de joindre l’opérateur. Rien n’a été envoyé ni facturé ; réessayez sous peu. CARRIER_THROTTLED : l’opérateur nous a demandé de ralentir et n’a pas pris le message. Rien n’a été facturé ; réessayez après le délai Retry-After avec la même Idempotency-Key, ce qui l’envoie. CARRIER_TIMEOUT : l’opérateur n’a pas répondu à temps, le message a donc pu être envoyé ou non. Son montant est retenu, puis remboursé dès que les relevés de l’opérateur montrent qu’il n’a pas été envoyé. Vérifiez le statut du message avant de l’envoyer de nouveau : une nouvelle tentative avec la même Idempotency-Key retourne le message en échec plutôt que de l’envoyer de nouveau.Le corps d’erreur standard.

Exemple

const { data, error } = await honkio.messages.send({
  from: '+1416XXXXXXX', // one of your HonkIO numbers
  to: '+1613XXXXXXX',
  body: 'Your order has shipped.',
})
if (error) throw new Error(`${error.name}: ${error.message}`)
console.log(data.id, data.status)

curl -X POST https://api.honkio.ca/v1/messages \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+1416XXXXXXX",
    "to": "+1613XXXXXXX"
  }'

get/v1/messages/{id}

Récupérer un message par identifiant

Permissionmessages:rSDK Node.jshonkio.messages.get()

Nécessite messages:r.

Paramètres

Paramètre	Type	Description
`id`obligatoirechemin	string

Réponses

200Le message.

Champ	Type	Description
`id`obligatoire	string
`direction`obligatoire	string	Une valeur parmi : OUTBOUND \| INBOUND
`from`obligatoire	string
`to`obligatoire	string
`body`obligatoire	string	Vaut null une fois le corps purgé (voir body_purged) et pour un code de vérification (NPU), qui n’est jamais stocké. Peut être null
`body_purged`obligatoire	boolean
`status`obligatoire	string	SCHEDULED : accepté avec scheduled_at et en attente de cette heure. CANCELLED : un message programmé annulé avant son départ ; ses frais ont été remboursés. Une valeur parmi : QUEUED \| SCHEDULED \| SENDING \| SENT \| DELIVERED \| FAILED \| UNDELIVERED \| RECEIVED \| CANCELLED
`segment_count`obligatoire	integer	Nombre de segments SMS en lesquels l’opérateur a divisé le corps (entrant : tel que reçu). La facturation se fait par segment. Peut être null
`mode`obligatoire	string	Les messages TEST sont simulés : ils ne sont jamais transmis à un opérateur ni facturés. Une valeur parmi : LIVE \| TEST
`is_verification`obligatoire	boolean	Le SMS contenant le code de vérification (NPU) d’une vérification. Son corps n’est jamais stocké.
`auto_reply_keyword`obligatoire	string	Défini pour la confirmation automatique envoyée lorsqu’un destinataire envoie STOP, START ou HELP par texto. Ce n’est pas vous qui l’avez envoyée, et elle ne vous est jamais facturée. Son corps peut être null pendant quelques minutes après l’envoi, jusqu’à ce que l’opérateur en communique le texte. Null pour tous les autres messages. Une valeur parmi : STOP \| START \| HELP Peut être null
`cost_cents`obligatoire	integer	Coût réel de ce message, en cents CAD : message_cost_cents multiplié par le nombre de segments selon le découpage de l’opérateur, ajusté au décompte de l’opérateur une fois l’envoi accepté (il peut donc différer d’une estimation faite avant l’envoi). 0 lorsque l’opérateur a refusé l’envoi d’emblée (remboursé ou jamais facturé), ainsi que pour une confirmation automatique STOP/START/HELP (auto_reply_keyword), qui n’est jamais facturée. Un message accepté par l’opérateur mais qui n’a pas pu être livré reste facturé. Les messages reçus portent les frais de réception. Pour un message TEST, il s’agit de ce qu’aurait coûté l’envoi ; rien n’a été facturé.
`error_code`obligatoire	string	Défini pour les messages FAILED et UNDELIVERED : le code de l’opérateur figurant dans l’accusé de réception (p. ex. 30003), ou le code de la plateforme pour un rejet synchrone (CARRIER_ERROR, INVALID_PHONE_NUMBER, NOT_A_MOBILE_NUMBER, INSUFFICIENT_BALANCE, RENT_OWED). CARRIER_THROTTLED quand l’opérateur nous a demandé de ralentir, ou a retiré le message de la file pleine du numéro d’envoi avant d’essayer le destinataire : remboursé, et sans risque à renvoyer. CARRIER_LOST quand l’opérateur a accepté le message puis l’a perdu : aucun accusé n’est jamais arrivé, et trois jours plus tard l’opérateur n’en avait aucune trace ; remboursé, et sans risque à renvoyer avec une nouvelle Idempotency-Key. Peut être null
`error_message`obligatoire	string	Raison lisible de l’échec d’un message FAILED ou UNDELIVERED, fournie par l’opérateur lorsqu’il en a donné une. Peut être null
`sent_at`obligatoire	string	Format : date-time Peut être null
`created_at`obligatoire	string	Format : date-time
`casl_consent_type`obligatoire	string	Le consentement LCAP sur lequel reposait un envoi sortant. Null pour les messages entrants et en mode test, pour les réponses STOP/HELP/START imposées par l’opérateur, et pour les envois effectués avant l’enregistrement de cette donnée (18 septembre 2026). Une valeur parmi : EXPRESS \| IMPLIED Peut être null
`delivered_at`obligatoire	string	Moment où l’opérateur a signalé la livraison du message à l’appareil. Format : date-time Peut être null
`scheduled_at`obligatoire	string	L’heure à laquelle un message programmé doit partir (ou devait partir). Null pour un message envoyé immédiatement. Format : date-time Peut être null
`expires_at`obligatoire	string	L’expires_at donné à un message programmé : l’heure limite de son départ. Null quand aucun n’a été donné, ce qui veut dire scheduled_at plus 24 heures. Un message qui ne peut pas partir d’ici là échoue avec l’error_code SCHEDULED_SEND_EXPIRED et est remboursé. Format : date-time 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.
404NOT_FOUND : aucun message correspondant sur ce compte. Une clé de test ne trouve que les messages TEST.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.messages.get('MESSAGE_ID')
if (error) throw new Error(error.message)
console.log(data.status, data.cost_cents)

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

patch/v1/messages/{id}

Reprogrammer un message programmé

Permissionmessages:mSDK Node.jshonkio.messages.update()

Seulement tant que le message est SCHEDULED (sinon 422 MESSAGE_NOT_SCHEDULED). Les frais restent les mêmes. Envoie message.rescheduled.

Nécessite messages:m.

Paramètres

Paramètre	Type	Description
`id`obligatoirechemin	string

Corps de la requête

La nouvelle heure d’envoi d’un message programmé.

Champ	Type	Description
`scheduled_at`obligatoire	string	Une date et heure ISO 8601 avec décalage horaire, de 1 minute à 30 jours à l’avance. Format : date-time
`expires_at`	string	L’heure limite de son départ : de 1 minute à 24 heures après le nouveau scheduled_at, ou null pour scheduled_at plus 24 heures. S’il est omis, l’expires_at enregistré est gardé s’il convient encore au nouveau scheduled_at, et abandonné (retour au délai par défaut de 24 heures) sinon. Format : date-time Peut être null

Réponses

200La nouvelle heure d’envoi du message.

Champ	Type	Description
`id`obligatoire	string
`status`obligatoire	string	Une valeur parmi : SCHEDULED
`scheduled_at`obligatoire	string	Format : date-time
`expires_at`obligatoire	string	L’expires_at maintenant enregistré, ou null pour scheduled_at plus 24 heures. Format : date-time 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.
404NOT_FOUND (details.resource "message") : aucun message sortant avec cet identifiant dans le mode de la clé appelante.Le corps d’erreur standard.
422MESSAGE_NOT_SCHEDULED (seul un message SCHEDULED peut être déplacé ; details.current_status indique son statut actuel) ou VALIDATION_ERROR (scheduled_at doit être de 1 minute à 30 jours à l’avance ; expires_at, de 1 minute à 24 heures après).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.messages.update('MESSAGE_ID', { scheduledAt: '2026-10-01T14:00:00Z' })
if (error) throw new Error(error.message)
console.log(data.scheduled_at, data.expires_at) // expires_at: null means scheduled_at plus 24 hours

curl -X PATCH https://api.honkio.ca/v1/messages/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_at": "2026-10-01T14:00:00Z"
  }'

delete/v1/messages/{id}

Annuler un message programmé

Permissionmessages:dSDK Node.jshonkio.messages.cancel()

Seulement tant que le message est SCHEDULED (sinon 422 MESSAGE_NOT_SCHEDULED). Ses frais sont remboursés et message.cancelled est envoyé. Irréversible.

Nécessite messages:d.

Paramètres

Paramètre	Type	Description
`id`obligatoirechemin	string

Réponses

204Annulé : les frais ont été remboursés.
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 (details.resource "message") : aucun message sortant avec cet identifiant dans le mode de la clé appelante.Le corps d’erreur standard.
422MESSAGE_NOT_SCHEDULED : seul un message SCHEDULED peut être annulé ; details.current_status indique son statut actuel.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 { error } = await honkio.messages.cancel('MESSAGE_ID')
if (error) throw new Error(error.message)

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