SDK

Installation et démarrage rapide

Installez le paquet, puis créez un client avec une clé API.

npm install @honkio/node

@honkio/node fonctionne avec Node 18 ou plus récent, est offert en ESM et CommonJS, et n’a aucune dépendance à l’exécution. @honkio/node sur npm

Créez une clé dans le tableau de bord, sous API Keys → Create key; la clé complète n'est affichée qu'une fois, juste après sa création. Commencez avec une clé de test (mk_test_...) : rien n'est livré ni facturé.

import { Honkio } from '@honkio/node'

const honkio = new Honkio(process.env.HONKIO_API_KEY)

const { data, error } = await honkio.messages.send({
  from: '+1416XXXXXXX', // one of your HonkIO numbers
  to: '+1613XXXXXXX',   // a Canadian number you hold consent for
  body: 'Hello from HonkIO!',
})

if (error) {
  console.error(error.name, error.message) // e.g. NON_CANADIAN_NUMBER
} else {
  console.log(data.id, data.status)
}

new Honkio() sans argument lit HONKIO_API_KEY, et lève une exception si ni l'un ni l'autre n'est défini.

Résultats et erreurs

data contient la réponse de l'API telle qu'envoyée, en snake_case (scheduled_at, segment_count). En cas d'échec, error est { name, message, statusCode, details? }.

details contient le details de l'API quand elle en a envoyé un (chemins de validation, retry_after, clés de modèle manquantes). Sinon, il contient tout ce que l'API a envoyé à côté de l'enveloppe d'erreur, comme attempts_remaining sur VERIFICATION_INVALID_CODE.

Chaque code d’erreur que l’API peut renvoyer, et ce qu’il faut faire pour chacun, figure sur la page Erreurs.

Écrivez les champs de requête en camelCase (replyTo, scheduledAt, isCommercial, skipConsentCheck); ils sont envoyés en snake_case, comme l'attend l'API. Les clés à l'intérieur de variables, headers et metadata sont les vôtres et sont envoyées telles quelles.

Options et clés

Le second argument de new Honkio prend ces options : baseUrl, qui vaut https://api.honkio.ca par défaut; fetch, qui vaut le fetch global par défaut (Node 18 ou plus récent), à remplacer par le vôtre pour utiliser un polyfill ou pour intercepter les requêtes; et, à partir de la version 0.8.0, maxRetries et maxRetryDelayMs, qui règlent les nouvelles tentatives du client (ci-dessous).

import { Honkio } from '@honkio/node'

const honkio = new Honkio('mk_live_...', {
  baseUrl: 'https://api.honkio.ca', // default
  // default: the global fetch. Pass your own to log or proxy requests:
  fetch: (url, init) => {
    console.log(init?.method ?? 'GET', url)
    return fetch(url, init)
  },
  maxRetries: 2, // default; 0 turns retrying off (from version 0.8.0)
  maxRetryDelayMs: 60_000, // default: the longest single wait, in milliseconds
})

À partir de la version 0.8.0, le client réessaie un refus qu’une attente règle : NUMBER_RATE_LIMITED, CARRIER_THROTTLED et CARRIER_UNAVAILABLE. Il attend le délai demandé par Retry-After, ou patiente brièvement quand l’API n’en indique aucun. RATE_LIMITED et les erreurs réseau ne sont réessayés que sur un GET ou sur une requête qui porte une Idempotency-Key, et chaque messages.send, emails.send et batch.send en porte maintenant une : la vôtre si vous passez idempotencyKey, sinon une que le client crée et garde pour chaque nouvelle tentative de cet appel, pour qu’une nouvelle tentative ne puisse ni envoyer ni facturer deux fois. Par défaut, il réessaie deux fois et n’attend jamais plus de 60 secondes d’un coup; une attente plus longue vous revient sous forme d’erreur. maxRetries: 0 désactive les nouvelles tentatives, et maxRetryDelayMs fixe l’attente la plus longue, en millisecondes. CARRIER_TIMEOUT n’est jamais réessayé : le message est peut-être parti.

Le préfixe d'une clé est son mode : les clés mk_test_ simulent tout et n'atteignent jamais l'opérateur ni votre solde; les clés mk_live_ envoient pour vrai. Rien d'autre ne change dans l'appel au SDK entre les deux.

Index des méthodes

Chaque méthode du client, la route REST qu’elle appelle et la page qui l’explique, avec des exemples en Node.js et en cURL.

Webhooks

Passez le corps brut, pas du JSON déjà analysé, à webhooks.verify (ou l'export autonome verifyWebhook). Il ne lève jamais d'exception : un corps déjà analysé, un secret manquant ou des en-têtes manquants répondent invalid_argument, et une signature invalide ou périmée répond invalid_signature.

const webhookSecret = process.env.HONKIO_WEBHOOK_SECRET
if (!webhookSecret) throw new Error('Set HONKIO_WEBHOOK_SECRET')

app.post('/webhooks/honkio', express.raw({ type: 'application/json' }), (req, res) => {
  const { data: event, error } = honkio.webhooks.verify(req.body, req.headers, webhookSecret)
  if (error) return res.status(400).end()
  if (!event.livemode) console.log('test event')
  res.status(200).end()
})

La signature est du HMAC-SHA256, en hexadécimal, sur l'horodatage et le corps brut, envoyée dans X-HonkIO-Signature avec X-HonkIO-Timestamp et X-HonkIO-Event. Les livraisons de plus de 300 secondes sont refusées par défaut; changez cela avec toleranceSeconds.

Un événement vérifié est l'enveloppe : id, type, created, account_id, livemode, data. Dédupliquez sur id : une livraison échouée est retentée pendant environ 24 heures, chaque tentative signée à nouveau avec le même id d'événement.

deliveries(id) liste les tentatives récentes. Les événements qui ont échoué à chaque tentative sont des lettres mortes : deadLetters(id) les liste, replay(deadLetterId) en renvoie une, et discard(deadLetterId) l'abandonne. reactivate(id) réactive un point de terminaison que la plateforme a désactivé.

Pagination

Les appels de liste suivent l'une de trois formes. Par page (page, limit, et un objet meta avec page, limit, total et pages) : messages.list et consents.list. Par décalage (limit, offset) : verify.list. Par curseur (limit, cursor, répondant avec data, has_more et next_cursor) : emails.list, emails.received.list, suppressions.list et templates.list. Tout le reste, comme phoneNumbers.list et webhooks.list, renvoie chaque ligne en un seul appel.

Python

Le paquet honkio demande Python 3.10 ou plus récent et ne dépend que de httpx. Il est typé, avec un client synchrone (Honkio) et un client asynchrone (AsyncHonkio) qui ont les mêmes ressources et les mêmes arguments.

pip install honkio

Créez une clé comme ci-dessus. Honkio() sans argument lit HONKIO_API_KEY et lève InvalidArgumentError si aucune n’est définie. Les arguments après l’identifiant sont nommés et portent le nom des champs de l’API; from est un mot réservé de Python, donc il s’écrit from_. Omettez un argument pour ne pas l’envoyer; passez None pour envoyer null.

from honkio import ApiError, Honkio

client = Honkio()  # reads HONKIO_API_KEY

try:
    message = client.messages.send(
        from_="+1416XXXXXXX",  # one of your HonkIO numbers
        to="+1613XXXXXXX",     # a Canadian number you hold consent for
        body="Hello from HonkIO!",
        idempotency_key="order-1042",
    )
    print(message["id"], message["status"])
except ApiError as e:
    print(e.code, e.message)  # e.g. NON_CANADIAN_NUMBER

Envoyez un courriel de la même façon :

import os

from honkio import Honkio

client = Honkio(os.environ["HONKIO_API_KEY"])

sent = client.emails.send(
    from_="Acme <onboarding@test.honkio.ca>",
    to="delivered@test.honkio.ca",
    subject="Hello from HonkIO",
    html="<p>It works.</p>",
)
print(sent["id"])

Les mêmes appels, en asynchrone :

import asyncio

from honkio import AsyncHonkio


async def main() -> None:
    async with AsyncHonkio() as client:
        message = await client.messages.send(from_="+1416XXXXXXX", to="+1613XXXXXXX", body="Hi")
        print(message["id"])


asyncio.run(main())

Contrairement au SDK Node.js, les erreurs sont des exceptions. Toute erreur de l’API est une sous-classe d’ApiError, avec code, message, status_code et details. L’absence de réponse lève APIConnectionError ou APITimeoutError, et un argument invalide lève InvalidArgumentError. À partir de la version 0.2.0, certains refus sont réessayés avant qu’une exception soit levée (ci-dessous).

from honkio import APIConnectionError, ApiError, UnprocessableEntityError

try:
    client.verify.check("VERIFICATION_ID", code="123456")
except UnprocessableEntityError as e:
    print(e.code, e.details)  # e.g. VERIFICATION_INVALID_CODE {"attempts_remaining": 2}
except ApiError as e:
    print(e.status_code, e.code, e.message)
except APIConnectionError:
    ...  # no response arrived (timeouts too): safe to try the check again

À partir de la version 0.2.0, Honkio et AsyncHonkio réessaient NUMBER_RATE_LIMITED, CARRIER_THROTTLED et CARRIER_UNAVAILABLE, en attendant le délai demandé par Retry-After. RATE_LIMITED et les erreurs de connexion ne sont réessayés que sur un GET ou sur une requête qui porte une clé d’idempotence, et messages.send, emails.send et batch.send en envoient toujours une : votre idempotency_key, sinon une que le client crée et garde pour chaque nouvelle tentative de cet appel. Par défaut, le client réessaie deux fois et n’attend jamais plus de 60 secondes d’un coup; quand réessayer n’aide pas, la dernière exception est levée. max_retries=0 désactive les nouvelles tentatives, et max_retry_delay fixe l’attente la plus longue, en secondes.

from honkio import Honkio

# The defaults (from version 0.2.0): 2 retries, no single wait over 60 seconds.
client = Honkio(max_retries=2, max_retry_delay=60)

# Retrying off: every refusal is raised at once.
no_retries = Honkio(max_retries=0)

Chaque code d’erreur que l’API peut renvoyer, et ce qu’il faut faire pour chacun, figure sur la page Erreurs.

verify_webhook prend le corps brut (str ou bytes), les en-têtes et votre secret de signature. Elle retourne l’événement analysé et lève InvalidSignatureError quand la signature, l’horodatage (plus de 300 secondes) ou le corps est invalide. Passez le corps avant tout traitement JSON.

import os

from honkio import InvalidSignatureError, verify_webhook

WEBHOOK_SECRET = os.environ["HONKIO_WEBHOOK_SECRET"]


def handle(request):  # a Flask-style request
    try:
        event = verify_webhook(request.get_data(), request.headers, WEBHOOK_SECRET)
    except InvalidSignatureError:
        return "bad signature", 400
    if not event["livemode"]:
        print("test event")
    return "", 204

PHP

honkio/honkio-php demande PHP 8.2 ou plus récent et Guzzle 7. Les requêtes sont des tableaux dont les clés sont celles de l’API, en snake_case, et les réponses sont des tableaux décodés. Omettez une clé pour ne pas l’envoyer; null envoie null.

composer require honkio/honkio-php

Créez une clé comme ci-dessus. new Honkio() sans argument lit HONKIO_API_KEY et lance InvalidArgumentException si aucune n’est définie.

<?php

use Honkio\Exception\ApiException;
use Honkio\Honkio;

$honkio = new Honkio(); // reads HONKIO_API_KEY

try {
    $message = $honkio->messages->send([
        'from' => '+1416XXXXXXX', // one of your HonkIO numbers
        'to' => '+1613XXXXXXX',   // a Canadian number you hold consent for
        'body' => 'Hello from HonkIO!',
    ], idempotencyKey: 'order-1042');

    echo $message['id'], ' ', $message['status'], "\n";
} catch (ApiException $e) {
    echo $e->errorCode, ': ', $e->getMessage(), "\n"; // e.g. NON_CANADIAN_NUMBER
}

Envoyez un courriel de la même façon :

<?php

use Honkio\Honkio;

$honkio = new Honkio(getenv('HONKIO_API_KEY'));

$email = $honkio->emails->send([
    'from' => 'Acme <onboarding@test.honkio.ca>',
    'to' => 'delivered@test.honkio.ca',
    'subject' => 'Hello from HonkIO',
    'html' => '<p>It works.</p>',
]);
echo $email['id'], "\n";

Les erreurs sont des exceptions, et chacune implémente Honkio\Exception\HonkioException. Une erreur de l’API est une ApiException (ou la sous-classe de son statut) avec errorCode, statusCode, getMessage() et details. L’absence de réponse lance ConnectionException, et l’envoi a pu avoir lieu ou non. Passez une clé d’idempotence comme dernier argument de messages->send, emails->send et batch->send, et réutilisez-la en cas de nouvel essai.

<?php

use Honkio\Exception\ApiException;
use Honkio\Exception\ConnectionException;

try {
    $honkio->verify->check('VERIFICATION_ID', ['code' => '123456']);
} catch (ApiException $e) {
    if ($e->errorCode === 'VERIFICATION_INVALID_CODE') {
        echo $e->details['attempts_remaining'];
    }
} catch (ConnectionException $e) {
    // No response arrived: safe to try the check again.
}

À partir de la version 0.2.0, le client réessaie NUMBER_RATE_LIMITED, CARRIER_THROTTLED et CARRIER_UNAVAILABLE, en attendant le délai demandé par Retry-After. RATE_LIMITED et les erreurs de connexion ne sont réessayés que sur un GET ou sur une requête qui porte une clé d’idempotence, et messages->send, emails->send et batch->send en envoient toujours une : la vôtre, sinon une que le client crée et garde pour chaque nouvelle tentative de cet appel. Par défaut, le client réessaie deux fois et n’attend jamais plus de 60 secondes d’un coup; quand réessayer n’aide pas, la dernière exception est lancée. Dans le tableau d’options, max_retries => 0 désactive les nouvelles tentatives, et max_retry_delay fixe l’attente la plus longue, en secondes.

<?php

use Honkio\Honkio;

// The defaults (from version 0.2.0): 2 retries, no single wait over 60 seconds.
$honkio = new Honkio(null, ['max_retries' => 2, 'max_retry_delay' => 60]);

// Retrying off: every refusal is thrown at once.
$noRetries = new Honkio(null, ['max_retries' => 0]);

Chaque code d’erreur que l’API peut renvoyer, et ce qu’il faut faire pour chacun, figure sur la page Erreurs.

Webhook::verify prend le corps brut, les en-têtes et votre secret de signature. Elle retourne l’événement sous forme de tableau et lance SignatureVerificationException quand elle ne peut pas vérifier une livraison. Passez le corps avant tout traitement JSON.

<?php

use Honkio\Exception\SignatureVerificationException;
use Honkio\Webhook;

$rawBody = file_get_contents('php://input');

try {
    $event = Webhook::verify($rawBody, getallheaders(), getenv('HONKIO_WEBHOOK_SECRET'));
} catch (SignatureVerificationException $e) {
    http_response_code(400);
    exit;
}

if (! $event['livemode']) {
    error_log('test event');
}
http_response_code(204);

Laravel

honkio/laravel ajoute un transport de courriel et un canal de notification SMS au SDK PHP. Il demande PHP 8.2 ou plus récent et Laravel 12 ou 13, et Laravel le découvre automatiquement.

composer require honkio/laravel

Définissez votre clé et le numéro d’où partent les notifications (HONKIO_BASE_URL ne sert qu’à viser un autre hôte d’API) :

HONKIO_API_KEY=mk_test_...
HONKIO_SMS_FROM=+14165550100
# MAIL_MAILER=honkio

À partir de la version 0.2.0, HONKIO_MAX_RETRIES (2 par défaut; 0 désactive les nouvelles tentatives) et HONKIO_MAX_RETRY_DELAY (en secondes, 60 par défaut) règlent les nouvelles tentatives du client, comme pour le SDK PHP.

# The defaults, from version 0.2.0
HONKIO_MAX_RETRIES=2
HONKIO_MAX_RETRY_DELAY=60

Ajoutez un mailer à config/mail.php, puis définissez MAIL_MAILER=honkio ou appelez Mail::mailer('honkio'). L’adresse d’expédition doit appartenir à un domaine d’envoi vérifié de votre compte.

<?php

// config/mail.php
return [
    'mailers' => [
        'honkio' => ['transport' => 'honkio'],
    ],
];

Le courriel est transactionnel par défaut. Marquez un Mailable comme commercial avec l’en-tête X-HonkIO-Commercial : le transport le retire et envoie is_commercial à true, et l’API exige alors un consentement LCAP au dossier et un seul destinataire par message. Un refus lance l’exception du SDK depuis Mail::send(). Les nouvelles tentatives d’un courriel mis en file ne sont pas dédupliquées : une tâche relancée peut envoyer de nouveau.

<?php

use Illuminate\Mail\Mailable;
use Symfony\Component\Mime\Email;

class SpringSale extends Mailable
{
    public function build(): static
    {
        return $this
            ->subject('Spring sale')
            ->view('mail.spring-sale')
            ->withSymfonyMessage(fn (Email $message) => $message->getHeaders()->addTextHeader('X-HonkIO-Commercial', 'true'));
    }
}

Une notification SMS utilise le canal honkio et retourne un HonkioMessage depuis toHonkio. Le numéro du destinataire (E.164) vient de routeNotificationForHonkio sur le notifiable, et un notifiable sans numéro est ignoré sans appeler l’API. Chaque destinataire doit avoir un consentement au dossier selon la LCAP. Les notifications portent une clé d’idempotence : une tâche en file relancée ne peut donc ni envoyer ni facturer deux fois.

<?php

use Honkio\Laravel\Notifications\HonkioMessage;
use Illuminate\Notifications\Notification;

class ShipmentSent extends Notification
{
    public function via($notifiable): array
    {
        return ['honkio'];
    }

    public function toHonkio($notifiable): HonkioMessage
    {
        return HonkioMessage::create('Your order has shipped.')
            ->from('+14165550100'); // optional, defaults to HONKIO_SMS_FROM
    }
}

<?php

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable
{
    use Notifiable;

    // The recipient's number, in E.164. A user with none is skipped without calling the API.
    public function routeNotificationForHonkio($notification): ?string
    {
        return $this->phone_number;
    }
}

Le client est aussi disponible par la façade Honkio (Honkio::messages()->send([...])) et, comme singleton, en typant Honkio\Honkio.