Notifications NotificationAPI

Aperçu

• Source: https://www.notificationapi.com
• Prise en charge des images: Non
• Prise en charge des pièces jointes: Non
• Limites de caractères des messages:
  • Corps: 160
• Créer votre URL Apprise

Configuration du Compte

NotificationAPI vous permet de déclencher des notifications par e-mail, SMS, appel, push et intégrées à l’application à l’aide d’une seule API. Le plugin Apprise prend en charge les hôtes régionaux US, CA et EU. Configurez le contenu une seule fois dans NotificationAPI, puis déclenchez-le depuis Apprise en envoyant le type de notification et les informations du destinataire, avec des paramètres de fusion facultatifs.

1. Créez un compte NotificationAPI et connectez-vous.
2. Dans le tableau de bord, repérez votre clientId et votre clientSecret dans la section Environments.
3. Créez ou identifiez le type de notification que vous souhaitez déclencher, par exemple order_tracking.
4. Vérifiez que vos destinataires disposent des bons identifiants :
   • Les notifications Email exigent une adresse e-mail dans l’objet to.
   • Les notifications SMS exigent un numéro au format E.164, par exemple +15005550006.
   • Vous pouvez aussi cibler des utilisateurs via un user id NotificationAPI.
5. Si votre hébergement n’est pas aux États-Unis, notez l’hôte API de votre région (US par défaut, CA ou EU).

Syntaxe

La syntaxe valide est la suivante (les alias napi:// et notificationapi:// sont acceptés) :

• napi://{ClientID}/{ClientSecret}/{Target}
• napi://{Type}@{ClientID}/{ClientSecret}/{Target}

Les cibles peuvent être combinées dans un seul chemin et sont regroupées autour d’un id en tête. Chaque segment {Target} peut être :

• un identifiant utilisateur (userid ou @userid)
• une adresse e-mail (name@example.com)
• un numéro de téléphone au format E.164 (+15551234567)

Exemples de cibles groupées :

• userid/test@example.com → id + email
• userid/+15551234567 → id + SMS
• userid/+15551234567/test@example.com → id + SMS + email

Détail des Paramètres

Variable	Requis	Description
type	Non	Identifiant du type de notification depuis votre tableau de bord NotificationAPI. La valeur par défaut est apprise.
mode	Non	Mode de notification, message ou template. La valeur par défaut est message.
id	Oui*	Identifiant client. Obligatoire sauf s’il est déjà fourni dans le chemin.
secret	Oui*	Secret client. Obligatoire sauf s’il est déjà fourni dans le chemin.
to	Non	Cible séparée par des virgules ; chaque sous-ensemble de cibles doit être associé à un id.
region	Non	us par défaut, ca ou eu pour sélectionner l’hôte API.
channels	Non	Les canaux sont détectés à partir de la première cible identifiée. Les canaux suivants peuvent être fournis : email, sms, inapp, web_push, mobile_push et/ou slack.
from	Non	Nom d’affichage de l’identité From de l’e-mail.
cc	Non	Liste d’adresses en copie, séparées par des virgules.
bcc	Non	Liste d’adresses en copie cachée, séparées par des virgules.
:{key}	Non	Jetons de paramètres dynamiques de modèle transmis à parameters, par exemple :orderId=123. Il est important de préfixer chacun avec un deux-points : pour qu’il soit correctement interprété. Utilisé uniquement si mode=template.

* Obligatoire si la valeur n’est pas déjà définie dans le composant de chemin de l’URL.

Paramètres par Défaut de NotificationAPI

Chaque requête NotificationAPI envoyée via Apprise inclut les paramètres par défaut suivants :

Paramètre	Description
appBody	Charge utile principale du corps du message de la notification.
appTitle	Titre du message ou ligne d’objet.
appType	Type de notification Apprise, par exemple info, success, warning ou failure.
appId	Identifiant de l’application Apprise, généralement apprise.
appDescription	Texte de description configuré pour le service Apprise.
appColor	Code couleur associé au type de notification, utilisé par certains canaux à des fins visuelles.
appImageUrl	URL pointant vers une image d’icône représentative du type de notification.
appUrl	URL de référence vers l’application source, si elle est configurée.

Ces paramètres sont toujours inclus par Apprise en plus des jetons personnalisés :{key}={value} que vous fournissez dans votre URL.

Ces valeurs par défaut sont communes à tous les plugins Apprise, en plus des paramètres spécifiques au service décrits ci-dessus.

Paramètres Globaux

Variable	Description
overflow	Ce paramètre peut être défini sur split, truncate ou upstream. Il détermine la manière dont Apprise remet le message que vous lui transmettez. Par défaut, il vaut upstream. 👉 upstream : ne fait aucune modification et transmet le message exactement tel qu’il a été reçu au service. 👉 truncate : veille à ce que le message tienne dans la limite amont documentée par le service. Si plus d’informations sont fournies que la limite définie, l’excédent est tronqué. 👉 split : similaire à truncate, sauf que si le message dépasse la limite amont documentée par le service, il est découpé en plusieurs morceaux plus petits puis envoyés séquentiellement.
format	Ce paramètre peut être défini sur text, html ou markdown. Certains services prennent en charge plusieurs formats de publication du contenu. La valeur par défaut varie selon le service choisi et peut correspondre à l’un de ces trois formats. Vous pouvez facultativement forcer cette option pour vous écarter du comportement par défaut. Si le service ne prend pas en charge plusieurs formats de transmission, ce champ est ignoré.
verify	Les requêtes externes vers des emplacements sécurisés, par exemple via https, utilisent des certificats. Par défaut, Apprise vérifie la validité de ces certificats ; si ce n’est pas le cas, aucune notification n’est envoyée à la source. Dans certains cas, un utilisateur ne dispose pas d’une autorité de certification pour valider la clé ou fait simplement confiance à la source ; dans ce cas, vous pouvez définir ce drapeau sur no. Par défaut, il vaut yes.
cto	Signifie Socket Connect Timeout. Il s’agit du nombre de secondes pendant lesquelles Requests attend que votre client établisse une connexion avec une machine distante, ce qui correspond à l’appel connect() sur la socket. La valeur par défaut est de 4.0 secondes.
rto	Signifie Socket Read Timeout. Il s’agit du nombre de secondes pendant lesquelles le client attend que le serveur envoie une réponse. La valeur par défaut est de 4.0 secondes.
emojis	Active la prise en charge des emojis, par exemple :+1: qui sera traduit en 👍. Par défaut, cette option vaut no. Remarque : selon la configuration côté serveur, l’administrateur peut désactiver globalement la prise en charge des emojis ; mais par défaut, ce n’est pas le cas.
tz	Identifie le fuseau horaire de la base IANA que vous souhaitez utiliser. Par défaut, celui-ci est détecté à partir de la configuration du serveur qui exécute Apprise. Vous pouvez le définir sur des valeurs comme America/Toronto, ou sur tout autre fuseau correctement formaté correspondant à votre région.

Exemples

Envoyer à un destinataire e-mail par type et laisser NotificationAPI choisir le canal :

apprise -vv -t "Mise a Jour de Commande" -b "Votre commande a ete expediee."   napi://order_tracking@CLIENT_ID/CLIENT_SECRET/id/user@example.com

Envoyer la même notification à plusieurs destinataires à l’aide de segments de chemin :

apprise -vv -t "Statut" -b "Traitement termine."   napi://order_tracking@CLIENT_ID/CLIENT_SECRET/\
     id/user@example.com/+15552341234/alice_123

Forcer le canal SMS et définir la région sur le Canada :

apprise -vv -t "Code" -b "Votre code de verification est 123456"   'napi://order_tracking@CLIENT_ID/CLIENT_SECRET/id/+16475550123?channel=sms&region=ca'

Définir From, CC et BCC pour un e-mail :

apprise -vv -t "Publication" -b "La version v2.0.1 est en ligne."   'napi://release_note@CLIENT_ID/CLIENT_SECRET/id/dev@example.ca?from=Dev%20Team&cc=qa@example.ca&bcc=ops@example.ca'

Transmettre des jetons dynamiques référencés par votre modèle NotificationAPI :

apprise -vv -t "Commande" -b " "   'napi://order_tracking@CLIENT_ID/CLIENT_SECRET/user@example.com?:orderId=12345&:status=shipped'

Utiliser une forme basée uniquement sur la chaîne de requête, pratique en YAML :

apprise -vv -t "Hello" -b "Bonjour a vous"   'napi://?id=CLIENT_ID&secret=CLIENT_SECRET&type=greeting&to=id,user@example.com'

Version minimale, id + e-mail :

apprise -vv -t "Bienvenue" -b "Bonjour d'Apprise"   "napi://welcome_email@CID/SECRET/user123/test@example.com"

Région EU avec substitutions de jetons :

apprise -vv -b "<b>Your order shipped!</b>" --format=html   "napi://order_update@CID/SECRET/user123/test@example.com?region=eu&:firstName=Chris&:trackingUrl=https://t.example/ABC123"

Définition de From / CC / BCC / Reply-To pour l’e-mail :

apprise -vv -b "Corps du Message"   "napi://newsletter@CID/SECRET/user123/test@example.com?from=Team<team@example.com>&cc=dev@example.com&bcc=ops@example.com&reply=help@example.com"