Pour commencer

Modèles

Un modèle contient le texte de chaque canal que vous utilisez, en français et en anglais. Enregistrez-le une fois, publiez-le, puis envoyez-le par identifiant ou alias avec des variables : codes de connexion, rappels, reçus et alertes.

Parties

Un modèle est fait de parties, une par canal que vous utilisez. Les variables s’écrivent {{ code }} et fonctionnent de la même façon dans chaque partie. Déclarez chaque variable utilisée par le modèle, avec une valeur de repli facultative : un envoi qui laisse une variable sans valeur ni valeur de repli est refusé et liste les clés manquantes. Un modèle a au moins une partie.

Partie SMS : un texte brut, jusqu’à 1 600 caractères avant le remplissage des variables. L’éditeur du tableau de bord affiche le nombre de segments du texte rempli pendant que vous écrivez.

Partie courriel : un objet, et un corps html, un corps texte ou les deux. Les valeurs des variables sont toujours échappées en HTML dans le html.

Langues et repli

Chaque partie peut être écrite en anglais (en), en français (fr) ou dans les deux. Le modèle a une langue par défaut : en, sauf si vous la fixez à fr. Une partie dans l’autre langue exige la même partie dans la langue par défaut, sinon l’API répond 422 VALIDATION_ERROR et nomme le chemin, par exemple parts.fr.sms.

Un envoi indique sa langue dans le champ language, ou l’omet pour utiliser la langue par défaut. Le choix se fait partie par partie : si la langue a la partie du canal utilisé, cette partie sert ; sinon, on utilise celle de la langue par défaut. Un envoi en français d’un modèle sans partie SMS en français envoie le texte SMS en anglais, et n’échoue jamais pour une traduction manquante. L’envoi répond 422 TEMPLATE_CHANNEL_MISSING seulement quand aucune langue n’a la partie du canal.

Créer, publier et revenir en arrière

Les modifications sont enregistrées dans un brouillon. Publier fait du brouillon la prochaine version numérotée, avec toutes les parties dans les deux langues, et les envois en production l’utilisent alors. Revenir en arrière publie de nouveau une ancienne version comme une nouvelle. Un envoi avec une clé de test utilise le brouillon, publié ou non. Publier, revenir en arrière et supprimer exigent une clé de production. Vous pouvez aussi modifier les modèles sur la page Modèles du tableau de bord, qui présente un aperçu de chaque partie.

bash

# Create a draft: an SMS part in English and in French
curl -X POST https://api.honkio.ca/v1/templates -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Sign-in code", "alias": "signin-code",
        "variables": [{ "key": "code" }],
        "parts": {
          "en": { "sms": { "text": "Your code is {{ code }}" } },
          "fr": { "sms": { "text": "Votre code est {{ code }}" } }
        } }'

bash

# Publish it as version 1
curl -X POST https://api.honkio.ca/v1/templates/signin-code/publish -H "Authorization: Bearer mk_live_YOUR_KEY"

Envoyer avec un modèle

Nommez le modèle par identifiant ou alias dans template, donnez ses valeurs dans variables et, si vous le voulez, une langue. Une requête contient un modèle ou son propre contenu, pas les deux.

SMS : POST /v1/messages accepte template, variables et language à la place de body. Le texte produit est celui qui est enregistré et envoyé, et le consentement, les désinscriptions, les limites d’envoi et la tarification s’appliquent exactement comme pour tout autre message. Un envoi à un groupe, POST /v1/contact-groups/{id}/messages, les accepte aussi et rend le texte une seule fois, avec les mêmes valeurs, pour chaque membre.

bash

# Send the French text by SMS
curl -X POST https://api.honkio.ca/v1/messages -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+14165551234", "template": "signin-code",
        "variables": { "code": "482913" }, "language": "fr" }'

Courriel : POST /v1/emails accepte le modèle comme avant, avec son identifiant et ses variables, et maintenant un champ language. Le point d’accès par lot accepte aussi language.

bash

# The template's email part, in French
curl -X POST https://api.honkio.ca/v1/emails -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "noreply@mail.acme.ca", "to": "ada@example.com",
        "template": { "id": "signin-code", "variables": { "code": "482913" } },
        "language": "fr" }'

Limites

Un compte peut avoir jusqu’à 200 modèles, y compris ceux créés par /v1/email-templates, qui partage les mêmes modèles et ne liste que ceux qui ont une partie courriel. En créer un de plus que 200 répond 422 TEMPLATE_LIMIT_REACHED : supprimez-en un d’abord.

Les modèles sont inclus sans frais supplémentaires.