HonkIOHonkIO

SMS

Numéros sans frais

Envoyez depuis un seul numéro valable partout au Canada, jusqu’à 1 200 messages par minute. Les SMS sans frais exigent une vérification unique de votre entreprise et le double consentement de chaque destinataire.

À quoi sert un numéro sans frais

Un numéro sans frais (833, 844, 855, 866, 877 ou 888) n’est rattaché à aucune province : un seul numéro sert vos clients partout au Canada. C’est aussi le canal à plus fort volume : une fois vérifié, un numéro sans frais envoie jusqu’à 1 200 messages par minute, contre 6 par minute pour un numéro local. Il convient à un expéditeur qui doit joindre beaucoup de personnes en peu de temps, comme les rappels d’un réseau de cliniques ou les suivis de commande d’un commerce national.

Les envois sans frais ont aussi leurs propres limites quotidiennes, comptées à part des envois depuis vos numéros locaux. Il n’y a pas de période probatoire : depuis ses numéros sans frais, un compte peut envoyer 10 000 messages réels par jour, joindre au plus 2 500 destinataires distincts avec un même message et envoyer 30 diffusions de groupe par jour d’au plus 2 500 destinataires chacune. Le plafond par destinataire, la pause automatique, la règle sur les raccourcisseurs de liens et les plafonds de rechargement sont les mêmes que pour les numéros locaux (voir Limites d’envoi).

Un numéro sans frais s’achète comme un numéro local : cherchez avec un préfixe sans frais, puis provisionnez-le (voir Numéros de téléphone). Avant qu’il puisse envoyer des SMS, l’opérateur doit vérifier l’entreprise qui l’utilise. D’ici là, un envoi depuis ce numéro est refusé avec 403 TOLL_FREE_NOT_VERIFIED avant toute facturation, en mode test aussi, pour qu’une intégration échoue tôt.

Les messages coûtent le même prix que depuis un numéro local : 0,03 $ par segment, envoyé ou reçu. Le numéro coûte 99,00 $ par mois, et la vérification coûte 499,00 $ une seule fois par demande (voir Tarifs).

Vérification

La vérification est une demande unique qui couvre jusqu’à 5 de vos numéros sans frais. Elle exige une clé de production, et les frais se paient par carte à la soumission, à part de votre solde prépayé, pour ne jamais entamer ce qui sert à vos envois. Chaque demande passe par deux examens : celui de HonkIO, puis celui de l’opérateur.

  1. Faites la demande. Dans le tableau de bord, ouvrez Numéros de téléphone et choisissez Vérifier pour les SMS sur un numéro sans frais, ou appelez POST /v1/toll-free-verifications. La demande commence à l’état DRAFT (brouillon) : vous pouvez la modifier avec PATCH ou l’annuler avec DELETE.
  2. Soumettez et payez. POST /v1/toll-free-verifications/:id/submit la fait passer à AWAITING_PAYMENT et renvoie une payment_url : ouvrez-la, connecté au tableau de bord, pour payer les frais de 499,00 $ par carte. Une fois le paiement reçu, elle passe à IN_REVIEW.
  3. HonkIO l’examine, habituellement en quelques jours ouvrables. Nous vérifions l’entreprise dans les registres publics et lisons le cas d’utilisation, les exemples de messages et le processus de consentement comme l’opérateur le fera. Ensuite, nous la transmettons à l’opérateur (SUBMITTED), vous demandons des modifications (CHANGES_REQUESTED, avec une reviewer_note qui précise quoi corriger) ou la refusons (DECLINED, avec la raison).
  4. L’opérateur l’examine, ce qui prend généralement environ une semaine. APPROVED signifie que tous les numéros de la demande peuvent envoyer des SMS. REJECTED est accompagné de la raison de l’opérateur : corrigez la demande et soumettez-la de nouveau, et HonkIO vérifie la modification avant de la renvoyer à l’opérateur. Vous pouvez aussi la retirer avec DELETE, ce qui libère ses numéros pour une nouvelle demande ; les frais ne sont pas remboursés.

Les frais et les remboursements

Les frais sont de 499,00 $ par demande, qu’elle couvre un numéro ou cinq. Ils sont remboursés en entier si HonkIO refuse la demande. Une fois la demande transmise par HonkIO à l’opérateur, les frais ne sont pas remboursés, quelle que soit la décision de l’opérateur ; un refus de l’opérateur peut être corrigé et soumis de nouveau gratuitement, autant de fois que nécessaire. Répondre à une demande de modifications ne coûte rien non plus, et une demande annulée avant le paiement n’est jamais facturée.

Chaque décision déclenche un webhook : toll_free_verification.changes_requested, toll_free_verification.approved ou toll_free_verification.rejected (voir la référence des événements). Le propriétaire du compte est aussi avisé de chaque décision par courriel, y compris un refus.

Ce que la demande contient, et pourquoi

L’opérateur approuve un numéro sans frais pour une entreprise et un usage, pas pour un compte : la demande décrit donc les deux. Les réponses que les examinateurs peuvent vérifier dans les registres publics passent le plus vite.

  • L’entreprise : dénomination sociale, nom commercial s’il est différent, type d’entité, numéro d’entreprise de l’ARC et adresse. Les examinateurs les comparent aux registres fédéral et provinciaux : utilisez le nom exactement tel qu’il est enregistré.
  • Une personne-ressource : la personne que HonkIO et l’opérateur peuvent joindre au sujet de la demande, avec un numéro de téléphone et une adresse courriel.
  • Site Web, politique de confidentialité et conditions : le site doit appartenir à l’entreprise, et la politique de confidentialité doit expliquer comment vous utilisez les numéros de téléphone et préciser que vous ne les vendez ni ne les partagez à des fins de marketing.
  • Cas d’utilisation : une catégorie de la liste et un court résumé de ce que vous envoyez, et à qui.
  • Consentement : comment les gens acceptent de recevoir vos messages (un formulaire Web, une case à cocher au paiement, un mot-clé texté à votre numéro), avec des liens vers au plus 5 captures d’écran. L’étape de consentement doit être claire et jamais cochée d’avance. C’est la partie pour laquelle les demandes sont le plus souvent renvoyées.
  • Messages : de 1 à 5 exemples de messages tels que vous les enverrez vraiment, avec le nom de votre marque et la mention de désabonnement ; la confirmation qu’un abonné reçoit après son consentement ; et votre réponse à HELP.
  • Volume et contenu : votre volume mensuel prévu, si le contenu est réservé aux adultes (alcool, cannabis et autres) et tout autre renseignement utile aux examinateurs.

GET /v1/toll-free-verifications/options liste les valeurs acceptées par use_case, monthly_volume et entity_type, chacune avec un libellé anglais et un libellé français, ainsi que les fee_cents en vigueur.

Avec l’API

// The values useCase, monthlyVolume and entityType accept, with labels
// in English and French, and the current fee
const { data: options, error } = await honkio.tollFreeVerifications.options()
if (error) throw new Error(error.message)

// { use_cases: [{ value: 'Appointments', label_en: '...', label_fr: '...' }, ...],
//   monthly_volumes: [...], entity_types: [...], fee_cents: 49900 }
console.log(options.use_cases, options.fee_cents)
// Create the application as a draft (nothing is charged yet)
const { data: application, error } = await honkio.tollFreeVerifications.create({
  phoneNumberIds: ['clxxxnumberxxxxxxxxxxxxxx'],
  application: {
    businessName: 'Acme Clinics Inc.',
    entityType: 'PRIVATE_PROFIT',
    businessRegistrationNumber: '123456789RC0001',
    businessAddress: { line1: '100 King St W', city: 'Toronto', province: 'ON', postalCode: 'M5X 1A9' },
    contact: { firstName: 'Ada', lastName: 'Lovelace', email: 'ada@acme.ca', phone: '+1416XXXXXXX' },
    website: 'https://acme.ca',
    useCase: 'Appointments',
    useCaseSummary: 'Appointment reminders and rescheduling links for our patients.',
    sampleMessages: ['Acme Clinics: your appointment is tomorrow at 2 pm. Reply C to confirm. Reply STOP to opt out.'],
    optInWorkflow: 'Patients tick an unchecked SMS box on the booking form, then confirm by replying YES.',
    optInImageUrls: ['https://acme.ca/img/booking-form-sms-box.png'],
    optInConfirmationMessage: 'Acme Clinics: you are subscribed to appointment texts. Reply STOP to opt out, HELP for help.',
    helpMessage: 'Acme Clinics: call 1-833-555-0100 or visit acme.ca/help. Reply STOP to opt out.',
    privacyPolicyUrl: 'https://acme.ca/privacy',
    monthlyVolume: '10,000',
    ageGated: false,
  },
})
if (error) throw new Error(`${error.name}: ${error.message}`)

// { id: 'tfv_...', status: 'DRAFT', phone_numbers: [...], application: {...}, fee_cents: 49900, ... }
console.log(application.id, application.status)
// Submit it: a draft moves to AWAITING_PAYMENT and returns where to pay
const { data: submitted, error } = await honkio.tollFreeVerifications.submit('tfv_...')
if (error) throw new Error(error.message)

// { id: 'tfv_...', status: 'AWAITING_PAYMENT', ...,
//   payment_url: 'https://honkio.ca/dashboard/numbers/toll-free/tfv_.../pay' }
console.log(submitted.status, submitted.payment_url)

// After CHANGES_REQUESTED or REJECTED: fix the fields, then submit again (no charge)
const { error: updateError } = await honkio.tollFreeVerifications.update('tfv_...', {
  application: { optInImageUrls: ['https://acme.ca/img/booking-form-v2.png'] },
})
if (updateError) throw new Error(updateError.message)
// Check on it, or list every application on the account
const { data: application, error } = await honkio.tollFreeVerifications.get('tfv_...')
if (error) throw new Error(error.message)

const { data: all, error: listError } = await honkio.tollFreeVerifications.list()
if (listError) throw new Error(listError.message)

// { id: 'tfv_...', status: 'CHANGES_REQUESTED',
//   reviewer_note: 'The screenshot does not show the SMS checkbox.', ... }
console.log(application.status, application.reviewer_note, all.data.length)

Créer et soumettre une demande exigent la permission phone_numbers:w. Un numéro ne peut appartenir qu’à une seule demande en cours à la fois (409 NUMBER_IN_OPEN_VERIFICATION), et une demande ne peut être modifiée qu’à l’état de brouillon, après une demande de modifications ou après un refus (409 VERIFICATION_NOT_EDITABLE).

Double consentement

Au Canada, la messagerie sans frais exige un double consentement. La personne accepte d’abord de recevoir vos messages, ce que vous enregistrez comme consentement (voir Consentement) ; elle le confirme ensuite par texto avant que vous lui écriviez depuis un numéro sans frais. La confirmation vaut pour le numéro sans frais qui l’a envoyée : si vous écrivez depuis plusieurs numéros sans frais, chacun demande la sienne. Un envoi sans frais en mode réel à un destinataire qui n’a pas confirmé avec ce numéro est refusé avec 451 DOUBLE_OPT_IN_REQUIRED, avant toute facturation. Les numéros locaux ne sont pas touchés, et le mode test saute cette vérification comme les autres vérifications de consentement.

Envoyez la confirmation avec POST /v1/compliance/opt-in-confirmations. from est l’un de vos numéros sans frais vérifiés, to un numéro mobile canadien pour lequel un consentement exprès ou tacite actif est déjà enregistré, et brand_name le nom sous lequel le destinataire vous connaît. Mettez language à fr pour le texte français. Elle est facturée comme un message ordinaire. HonkIO envoie exactement ceci :

Anglais (par défaut){brand_name}: reply YES to confirm you want text messages from us. Msg & data rates may apply. Reply STOP to opt out.
Français (language : fr){brand_name} : répondez OUI pour confirmer que vous voulez recevoir nos textos. Des frais de messagerie et de données peuvent s’appliquer. Répondez ARRET pour vous désabonner.
// Ask the recipient to confirm (they need an active consent on file first)
const { data: confirmation, error } = await honkio.optInConfirmations.send({
  from: '+1833XXXXXXX',
  to: '+1613XXXXXXX',
  brandName: 'Acme Clinics',
  language: 'en',
})
if (error) throw new Error(`${error.name}: ${error.message}`)

// { id: 'oic_...', status: 'PENDING', from: '+1833XXXXXXX',
//   to: '+1613XXXXXXX', expires_at: '...', ... }
console.log(confirmation.id, confirmation.status)

La confirmation reste PENDING pendant 7 jours. Quand le destinataire répond OUI, O, YES ou Y (majuscules ou minuscules ; les espaces et la ponctuation finale sont ignorés, mais la réponse doit être ce seul mot) à ce numéro sans frais, elle passe à CONFIRMED, son consentement enregistre la confirmation et le webhook consent.double_opt_in_confirmed se déclenche. Dès lors, les envois vers cette personne depuis ce numéro passent. La réponse reste un message reçu ordinaire : elle est facturée et déclenche message.received. STOP fonctionne comme d’habitude : il révoque le consentement, refuse la confirmation en attente et retire le double consentement pour le numéro qui l’a reçu.

Une seule confirmation peut être en attente par destinataire ; en envoyer une autre la remplace. Vous pouvez en envoyer au plus 3 au même destinataire en 24 heures (429 OPT_IN_CONFIRMATION_LIMIT). Une confirmation restée sans réponse passe à EXPIRED après 7 jours ; envoyez-en une nouvelle si la personne veut toujours recevoir vos messages.

// Where a recipient stands: PENDING, CONFIRMED, EXPIRED or DECLINED
const { data, error } = await honkio.optInConfirmations.list({ to: '+1613XXXXXXX' })
if (error) throw new Error(error.message)
for (const c of data.data) console.log(c.id, c.status)

La confirmation elle-même échappe à la vérification du double consentement, puisque c’est elle qui permet d’y satisfaire, tout comme les codes de vérification (POST /v1/verify), qui répondent à une demande que le destinataire vient de faire ; les deux exigent tout de même un numéro sans frais vérifié. Le contenu de consent.double_opt_in_confirmed figure dans la référence des événements.

Erreurs

Les codes qu’ajoutent les numéros sans frais et le double consentement. Tous les autres codes, avec leur statut HTTP, figurent sur la page des erreurs.

  • 403 TOLL_FREE_NOT_VERIFIED: Le numéro sans frais n’est pas encore vérifié pour les SMS. Demandez la vérification, puis envoyez une fois qu’elle est approuvée.
  • 451 DOUBLE_OPT_IN_REQUIRED: Envoi sans frais à un destinataire qui n’a pas confirmé son double consentement. Envoyez une confirmation et attendez son OUI.
  • 422 NOT_A_TOLL_FREE_NUMBER: Le numéro n’est pas l’un de vos numéros sans frais : il ne peut ni être vérifié ni envoyer de confirmations de consentement.
  • 409 NUMBER_IN_OPEN_VERIFICATION: Le numéro fait déjà partie d’une autre demande de vérification sans frais en cours.
  • 409 VERIFICATION_NOT_EDITABLE: La demande de vérification sans frais ne peut pas être modifiée ni soumise dans son état actuel.
  • 422 LIVE_MODE_REQUIRED: Cette action exige une clé de production. La vérification sans frais, par exemple, n’existe qu’en mode réel.
  • 429 OPT_IN_CONFIRMATION_LIMIT: Déjà 3 confirmations de consentement envoyées à ce destinataire au cours des dernières 24 heures. Réessayez plus tard.