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 \| SENDING \| SENT \| DELIVERED \| FAILED \| UNDELIVERED \| RECEIVED
`direction`requête	string	Une valeur parmi : OUTBOUND \| INBOUND
`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	Une valeur parmi : QUEUED \| SENDING \| SENT \| DELIVERED \| FAILED \| UNDELIVERED \| RECEIVED
`segment_count`obligatoire	integer	Nombre de parties SMS en lesquelles l’opérateur a divisé le corps (entrant : tel que reçu). La facturation se fait par partie. 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 parties 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). 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
`dncl_exemption`obligatoire	string	L’exemption à la LNNTE du CRTC sur laquelle reposait l’envoi, le cas échéant. 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
`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 (30 messages par heure et 100 par jour vers un même destinataire ; l’en-tête Retry-After est renseigné) / 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. 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_TIMEOUT signifie que l’opérateur n’a pas répondu à temps : le message a pu être envoyé ou non, rien n’a été facturé, 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.

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`obligatoire	string	Jusqu’à 1 600 caractères et 10 parties 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 partie, selon le découpage effectué par l’opérateur. Au plus 1600 caractères
`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.
`dncl_exemptions`	string[]	Motifs d’exemption de la LNNTE. La vérification auprès de la LNNTE du CRTC sera bientôt offerte et n’est pas encore appliquée : ce champ est donc accepté pour l’instant, mais n’a aucun effet. Une valeur parmi : existing_business_relationship \| registered_charity \| political \| survey \| newspaper_subscription \| personal

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	Une valeur parmi : QUEUED \| SENDING \| SENT \| DELIVERED \| FAILED \| UNDELIVERED \| RECEIVED
`segment_count`obligatoire	integer	Nombre de parties SMS en lesquelles l’opérateur a divisé le corps (entrant : tel que reçu). La facturation se fait par partie. 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 parties 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). 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
`dncl_exemption`obligatoire	string	L’exemption à la LNNTE du CRTC sur laquelle reposait l’envoi, le cas échéant. 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

401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
402INSUFFICIENT_BALANCE : le solde ne couvre pas l’envoi. 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 ou SENDING_PAUSED.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 ou INVALID_PHONE_NUMBER (l’opérateur a jugé le numéro invalide). 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.Le corps d’erreur standard.
451Le contrôle LCAP a refusé le destinataire : NO_CONSENT, OPT_OUT_BLOCKED ou CONSENT_EXPIRED.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_TIMEOUT : l’opérateur n’a pas répondu à temps, le message a donc pu être envoyé ou non. Rien n’est facturé. 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",
    "body": "Hello from HonkIO!"
  }'

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	Une valeur parmi : QUEUED \| SENDING \| SENT \| DELIVERED \| FAILED \| UNDELIVERED \| RECEIVED
`segment_count`obligatoire	integer	Nombre de parties SMS en lesquelles l’opérateur a divisé le corps (entrant : tel que reçu). La facturation se fait par partie. 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 parties 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). 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
`dncl_exemption`obligatoire	string	L’exemption à la LNNTE du CRTC sur laquelle reposait l’envoi, le cas échéant. 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

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"