API SMS

Démarrage rapide

1. Créer un compte gratuit, puis ouvrez Clés API → Créer la clé dans le tableau de bord. La clé complète ne s’affiche qu’une fois, juste après sa création : copiez-la à ce moment.
2. Commencez par une clé de test : elle fonctionne immédiatement, avant toute recharge, pour envoyer des messages de test et explorer l’API gratuitement.
3. Rechargez votre solde par carte via Stripe. Les clés de production retournent 402 PAYMENT_REQUIRED jusqu’à la première recharge.
4. Vérifiez votre numéro de téléphone en tant que propriétaire du compte. Un envoi réel nécessite un numéro de propriétaire vérifié.
5. Achetez un numéro canadien pour l’envoi ; un envoi réel nécessite un numéro appartenant à votre compte.
6. Enregistrez le consentement LCAP pour chaque numéro de téléphone que vous allez contacter.
7. Envoyez votre premier message via l’API REST.

Numéros de téléphone

Recherchez les numéros canadiens disponibles, provisionnez-en un et utilisez-le comme champ from lors de l'envoi.

curl https://api.honkio.ca/v1/phone-numbers/search?area_codes=416 \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

# Response 200 (per result): what buying it charges now and monthly, in CAD cents
# { "phone_number": "+14165550100", "region": "Ontario",
#   "upfront_cost_cents": 250, "activation_fee_cents": 100, "monthly_cost_cents": 250, ... }

# Provision a number
curl -X POST https://api.honkio.ca/v1/phone-numbers \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+14165550100"}'

# Accounts hold a limited number of numbers. GET /v1/accounts/me reports
# phone_number_limit and phone_numbers_used: check them before buying, or
# handle the 403 NUMBER_LIMIT_REACHED that a purchase past the cap returns.

# Ask HonkIO staff to raise the limit. One request may be pending at a time.
curl -X POST https://api.honkio.ca/v1/phone-numbers/allowance-requests \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requested_limit": 10, "reason": "Onboarding three new clinics this quarter"}'

# Response 201: { "status": "PENDING", "requested_limit": 10, ... }
# You are emailed if it is approved; the decision also shows in the dashboard.

# Check on it
curl https://api.honkio.ca/v1/phone-numbers/allowance-requests \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Consentement LCAP (requis avant l'envoi)

En vertu de la LCAP, vous devez enregistrer le consentement avant d'envoyer un message commercial à tout destinataire. L'API bloquera les envois vers des numéros de téléphone sans consentement valide (HTTP 451).

curl -X POST https://api.honkio.ca/v1/compliance/consents \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+1613XXXXXXX",
    "consent_type": "express",
    "source_description": "Website opt-in form",
    "source_ip": "203.0.113.1"
  }'

Consentement tacite pour un client existant, le délai courant à partir de sa dernière transaction :

curl -X POST https://api.honkio.ca/v1/compliance/consents \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+1613XXXXXXX",
    "consent_type": "implied",
    "relationship_type": "purchase",
    "last_transaction_date": "2025-11-04"
  }'

# → { "status": "recorded", "phone_number": "+1613XXXXXXX", "expires_at": "2027-11-04T00:00:00.000Z" }

Le consentement exprès n'expire jamais. Le consentement tacite expire après 2 ans selon l'art. 10(9) de la LCAP. Fournissez last_transaction_date pour que le délai de deux ans coure à partir de la relation réelle plutôt que du jour de l'enregistrement, ou indiquez directement expires_at si vous avez déjà calculé l'expiration. La réponse renvoie expires_at pour que vous puissiez le vérifier.

Envoi de SMS

Envoyez un message en utilisant un numéro provisionné. L'API valide le numéro de destination canadien, vérifie le consentement LCAP avant la livraison (vérification LNNTE du CRTC à venir).

# "from" is one of your HonkIO numbers; "to" is a real number you hold consent for
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! 🇨🇦"
  }'

Vérification de numéro de téléphone (OTP)

Utilisez l'API Verify pour confirmer la propriété d'un numéro de téléphone avant d'envoyer des messages commerciaux. Votre utilisateur final reçoit un code à usage unique par SMS; soumettez-le au point de terminaison de vérification pour confirmer.

# Start a verification (sends OTP SMS)
curl -X POST https://api.honkio.ca/v1/verify   -H "Authorization: Bearer mk_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{
    "from": "+1416XXXXXXX",
    "to":   "+1613XXXXXXX",
    "code_length": 6,
    "ttl_minutes": 10,
    "app_name": "Acme"
  }'
# Response: { "id": "clxxx...", "status": "pending", "code_length": 6, ... }

# Check the code submitted by your user
curl -X POST https://api.honkio.ca/v1/verify/clxxx.../check   -H "Authorization: Bearer mk_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{ "code": "483721" }'
# Response 200: { "status": "verified", ... }
# Response 422: { "code": "VERIFICATION_INVALID_CODE", "attempts_remaining": 4 }

# Fetch status at any time
curl https://api.honkio.ca/v1/verify/clxxx...   -H "Authorization: Bearer mk_live_YOUR_KEY"

En mode test, le code est toujours composé de zéros selon la longueur choisie (ex. 000000 pour 6 chiffres). Aucun SMS n'est envoyé et rien n'est facturé. Chaque vérification retourne un champ « mode » valant « LIVE » ou « TEST » afin de distinguer une vérification simulée d'une vérification réelle.

Tarification

Les prix sont définis à l'exécution et peuvent changer sans nouvelle version : lisez-les plutôt que de les coder en dur. Tous les montants sont en cents CAD. L'envoi est facturé par partie SMS : message_cost_cents × le nombre de parties en lesquelles l'opérateur découpe le texte. Les parties sont comptées comme l'opérateur les compte : guillemets typographiques, tirets et points de suspension sont convertis en GSM-7 (160 caractères, puis 153 par partie), tandis que les émojis et la plupart des lettres accentuées imposent des parties Unicode (70, puis 67). Le montant est ajusté au décompte de l'opérateur après l'envoi. Un message refusé d'emblée par l'opérateur ne coûte rien, pas plus qu'un envoi vers un central réservé (555-XXXX et semblables), refusé ici ; un message accepté par l'opérateur mais non livré conserve ses frais. Un texte de plus de 10 parties est rejeté avec 422 MESSAGE_TOO_LONG avant toute facturation. verification_cost_cents couvre un OTP typique d'une seule partie ; un app_name long ou non GSM peut ajouter une partie. phone_number_activation_fee_cents est facturé une seule fois, avec le premier mois, pour chaque numéro provisionné, local ou sans frais, et n'est pas remboursé à la libération. inbound_message_cost_cents est facturé par partie pour chaque SMS reçu sur un numéro provisionné, quel que soit l'expéditeur ou l'opérateur, sauf les mots-clés STOP, START et HELP ; un message reçu est débité même si le solde passe sous zéro, ce qui suspend l'envoi jusqu'à la prochaine recharge.

# Current prices, in CAD cents
curl https://api.honkio.ca/v1/pricing \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

# Response 200:
# {
#   "message_cost_cents": 3,
#   "verification_upcharge_cents": 25,
#   "verification_cost_cents": 28,
#   "phone_number_upfront_cost_cents": 250,
#   "phone_number_monthly_cost_cents": 250,
#   "phone_number_activation_fee_cents": 100,
#   "inbound_message_cost_cents": 3
# }

Les requêtes en mode test sont tarifées de façon identique dans la réponse, mais ne sont jamais facturées : vous pouvez donc voir ce que coûterait une intégration sans rien dépenser.

Limites d’envoi

HonkIO est conçu pour la messagerie transactionnelle et relationnelle, pas pour les campagnes, et la délivrabilité de chaque client repose sur un profil opérateur partagé. Ces limites gardent le marketing de masse hors de la plateforme ; une clinique, un entrepreneur ou un SaaS qui envoie des codes ne les remarquera pas. Les limites d’envoi s’appliquent uniquement au mode réel ; la règle sur les raccourcisseurs de liens, les vérifications de destination réservée et injoignable, et le plafond de taille des diffusions s’appliquent aux deux modes.

• Plafond quotidien : les nouveaux comptes peuvent envoyer 250 messages réels par 24 heures glissantes. Il ne se lève pas de lui-même. 30 jours après votre premier message réel, vous pouvez demander un volume plus élevé depuis le tableau de bord ; l’approbation fixe 1 000 par jour ou le chiffre demandé. Les envois refusés renvoient 429 DAILY_LIMIT_REACHED avec votre limite et votre compte.
• Messages identiques : un même corps de message peut atteindre au plus 250 destinataires distincts par 24 heures (429 FANOUT_LIMIT_REACHED). Les messages personnalisés ne sont pas concernés.
• Débit par numéro : 60 messages par minute par numéro d’envoi, ce que les opérateurs canadiens accordent de toute façon à un numéro long (429 NUMBER_RATE_LIMITED avec Retry-After).
• Diffusions : jusqu’à 250 destinataires par diffusion de groupe et 3 diffusions par 24 heures (422 BROADCAST_TOO_LARGE, 429 BROADCAST_LIMIT_REACHED).
• Les raccourcisseurs de liens (bit.ly, tinyurl et similaires) sont refusés dans les deux modes, car les opérateurs les filtrent (422 LINK_SHORTENER_BLOCKED). Utilisez l’URL complète.
• Avertissement de livraison, puis pause automatique : si plus de 10 % de vos 50 derniers messages réels échouent chez l’opérateur, vous recevez un courriel (et l’événement account.delivery_warning) sans aucune pause. Si plus de 1 % des destinataires répondent STOP, ou plus de 5 % des messages sont rejetés par les opérateurs, sur vos envois récents, l’envoi réel est suspendu 24 heures et vous êtes avisé par courriel (403 SENDING_PAUSED avec l’heure de reprise ; l’événement account.sending_paused est émis).
• Rechargements : le solde ne peut dépasser 500 $ et les rechargements sont limités à 1 000 $ par 30 jours. Relevés sur demande.
• Plafond par destinataire : 30 messages vers un même destinataire par heure et 100 par 24 heures (429 RECIPIENT_RATE_LIMITED avec Retry-After). Une conversation bidirectionnelle n’en approche jamais ; un script qui réessaie le même numéro, oui.
• Les messages non livrés sont facturés : un message accepté par l’opérateur mais non livré conserve ses frais. Un central réservé (555-XXXX, centraux N11 comme 411 ou 911, codes de test des opérateurs, centraux commençant par 0 ou 1) est refusé sans frais avec 422 RESERVED_DESTINATION, en mode test aussi, et un indicatif régional réservé (555, 911 et semblables) comme tout numéro non canadien. Tout ce qui réessaie devrait envoyer un en-tête Idempotency-Key afin qu’une nouvelle tentative ne devienne jamais un second débit. Une heure de dépenses inhabituelles déclenche un courriel et l’événement account.spend_warning.
• Numéros injoignables : après 3 échecs consécutifs chez l’opérateur vers un même numéro en 30 jours, tous clients HonkIO confondus, les envois vers ce numéro sont refusés sans frais (422 UNDELIVERABLE_NUMBER avec le nombre d’échecs, la date d’inscription et la date d’expiration) pendant 90 jours, puis réessayés au cas où le numéro aurait été réattribué.

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

# → { "daily_limit": 250, "sent_last_24h": 12, "remaining": 238,
#     "recipient_rate_per_hour": 30, "recipient_rate_per_day": 100,
#     "probation": { "ends_at": "2026-09-26T14:02:11.000Z", "eligible_to_request": false },
#     "paused_until": null, "requests": [] }

Consultez vos limites et votre utilisation avec GET /v1/send-limit, et déposez une demande avec POST /v1/send-limit/requests. Chaque chiffre ci-dessus est une valeur par défaut de la plateforme qui peut être relevée par compte.

Événements webhook

Voici les événements SMS, de désabonnement et de numéro de téléphone. L’inscription d’un point de terminaison, l’enveloppe de chaque événement, les nouvelles tentatives et les signatures sont décrites dans Webhooks de la plateforme.

Chaque charge utile est signée avec HMAC-SHA256 : vérifiez l’en-tête X-HonkIO-Signature. Un évènement message.received contient l’expéditeur, votre numéro, le texte, keyword_action (traitement STOP/START), ainsi que segment_count et cost_cents, le montant facturé pour ce message. Un évènement message.sent contient carrier_message_id, l’identifiant que l’opérateur a attribué au message, avec les deux mêmes champs de facturation.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "message.delivered",
  "created": "2026-09-19T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "message_id": "clxxxmessagexxxxxxxxxxxxx",
    "status": "delivered",
    "message_status": "DELIVERED",
    "to": "+1613XXXXXXX",
    "from": "+1416XXXXXXX",
    "errors": []
  }
}
// Headers: X-HonkIO-Signature, X-HonkIO-Timestamp, X-HonkIO-Event

Un même message_id peut émettre message.failed (seulement si l’échec était CARRIER_UNAVAILABLE ; un échec INSUFFICIENT_BALANCE n’émet aucun webhook) puis de nouveau message.queued, puis message.sent, lorsqu’une nouvelle tentative avec la même Idempotency-Key relance un message ayant échoué avant d’atteindre l’opérateur.

Chaque évènement, tel que votre point de terminaison le reçoit. Les exemples sont caviardés : identifiants, numéros et adresses sont fictifs. Des champs peuvent s’ajouter avec le temps, ignorez donc ceux que vous ne reconnaissez pas.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "message.queued",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "message_id": "clxxxmessagexxxxxxxxxxxxx",
    "from": "+1416XXXXXXX",
    "to": "+1613XXXXXXX",
    "status": "QUEUED",
    "message_status": "QUEUED"
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "message.sending",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "message_id": "clxxxmessagexxxxxxxxxxxxx",
    "status": "sending",
    "message_status": "SENDING",
    "to": "+1613XXXXXXX",
    "from": "+1416XXXXXXX",
    "errors": []
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "message.sent",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "message_id": "clxxxmessagexxxxxxxxxxxxx",
    "from": "+1416XXXXXXX",
    "to": "+1613XXXXXXX",
    "status": "SENDING",
    "message_status": "SENDING",
    "carrier_message_id": "40319xxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "segment_count": 1,
    "cost_cents": 3
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "message.delivered",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "message_id": "clxxxmessagexxxxxxxxxxxxx",
    "status": "delivered",
    "message_status": "DELIVERED",
    "to": "+1613XXXXXXX",
    "from": "+1416XXXXXXX",
    "errors": []
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "message.failed",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "message_id": "clxxxmessagexxxxxxxxxxxxx",
    "from": "+1416XXXXXXX",
    "to": "+1613XXXXXXX",
    "status": "FAILED",
    "message_status": "FAILED",
    "error_code": "INVALID_PHONE_NUMBER",
    "error_message": "The destination is not a valid phone number."
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "message.undelivered",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "message_id": "clxxxmessagexxxxxxxxxxxxx",
    "status": "delivery_failed",
    "message_status": "UNDELIVERED",
    "to": "+1613XXXXXXX",
    "from": "+1416XXXXXXX",
    "errors": [
      {
        "code": "40002",
        "title": "Blocked as spam",
        "detail": "The destination carrier blocked the message."
      }
    ]
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "message.received",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "message_id": "clxxxmessagexxxxxxxxxxxxx",
    "from": "+1613XXXXXXX",
    "to": "+1416XXXXXXX",
    "body": "Yes, see you at 3",
    "keyword_action": "ignored",
    "segment_count": 1,
    "cost_cents": 1,
    "message_status": "RECEIVED"
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "opt_out.recorded",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "phone_number": "+1613XXXXXXX",
    "from_number": "+1416XXXXXXX",
    "keyword": "STOP"
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "opt_out.reinstated",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "phone_number": "+1613XXXXXXX",
    "from_number": "+1416XXXXXXX",
    "keyword": "START"
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "phone_number.suspended",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "phone_number": "+1416XXXXXXX",
    "reason": "insufficient_balance",
    "monthly_cost_cents": 299
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "phone_number.released",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "phone_number": "+1416XXXXXXX",
    "reason": "customer_released"
  }
}

Codes d'erreur

Les codes ci-dessous sont propres aux SMS, aux numéros de téléphone, à la vérification et à la LCAP. Tout appel peut aussi répondre avec les codes généraux du tableau d’erreurs de la plateforme, comme VALIDATION_ERROR, INSUFFICIENT_BALANCE et NOT_FOUND.