Envoyer un message

Vous pouvez utiliser GC Notification pour envoyer des courriels et des messages texte. Il peut s’agir d’une réponse à un événement généré par l’utilisateur, comme un reçu après qu’ils demandent votre service, ou comme un rappel lorsqu’un paiement est attendu.

Ce dont vous aurez besoin :

Pour envoyer un message à l’aide de GC Notification, vous devez configurer un gabarit dans l’interface utilisateur.

Pour créer un gabarit :

Connectez-vous à GC Notification.
Accédez à la page Gabarits.
Sélectionnez Nouveau gabarit.

Une fois le gabarit prêt, recherchez l’ID de gabarit associé. Vous aurez besoin de cet ID pour indiquer le gabarit que vous voulez utiliser lorsque vous appelez l’API.

Votre appel à l’API doit également inclure tous les champs qui ont été configurés comme des personnalisations. La personnalisation vous permet de modifier ce qui apparaît dans un message précis lors de son envoi. Vous pouvez utiliser la personnalisation pour :

Vous adresser à un utilisateur par son nom
Fournir aux utilisateurs un lien précis sur lequel cliquer
Envoyer un numéro de transaction unique comme suivi
Donner aux utilisateurs une liste dynamique des mesures qu’ils doivent prendre

Envoyer un courriel

POST /v2/notifications/email

Corps de la requête

{
  "email_address": "expéditeur@quelquechose.com",
  "template_id": "f33517ff-2a88-4f6e-b855-c550268ce08a"
}

Paramètres

Adresse courriel (obligatoire)

email_address est l’adresse de courriel du destinataire.

ID du gabarit (obligatoire)

Pour rechercher template_id (ID du gabarit) :

Connectez-vous à GC Notification (opens new window).
Accédez à la page Gabarits et sélectionnez le gabarit approprié.
Sélectionnez Copier template ID dans le presse-papier.

Personnalisation (facultatif)

Utilisez personalisation si un gabarit comporte des champs réservés pour des renseignements personnalisés comme le nom ou le numéro de référence, vous devez fournir leurs valeurs dans un dictionnaire avec des paires de valeurs clés. Par exemple :

"personalisation": {
  "first_name": "Amala",
  "application_date": "2018-01-01"
}

Vous pouvez ignorer cet argument si un gabarit ne comporte pas de champs réservés pour les renseignements personnalisés.

Référence (facultatif)

reference est un identificateur que vous pouvez créer au besoin. Cette référence identifie une seule notification ou un lot de notifications. Il ne doit contenir aucun renseignement personnel comme le nom ou l’adresse postale. Par exemple :

"reference": "STRING"

Vous pouvez ignorer cet argument si vous n’avez pas de référence.

ID de l’adresse courriel de réponse (facultatif)

email_reply_to_id est une adresse de courriel que vous avez indiquée pour recevoir les réponses de vos utilisateurs. Vous devez ajouter au moins une adresse de courriel de réponse avant que votre service puisse être activé.

Pour ajouter une adresse de courriel de réponse :

Connectez-vous à GC Notification (opens new window).
Accédez à la page Paramètres.
Dans la section Courriel, sélectionnez Configurer à la ligne Adresses courriel de réponse.
Sélectionnez Ajouter une adresse courriel de réponse.
Entrez l’adresse de courriel que vous souhaitez utiliser, puis sélectionnez Ajouter.

Par exemple :

"email_reply_to_id": "8e222534-7f05-4972-86e3-17c5d9f894e2"

Vous pouvez ignorer cet argument si votre service n’a qu’une seule adresse de courriel de réponse ou si vous voulez utiliser l’adresse de courriel par défaut.

Envoyer un fichier par courriel

Activer cette fonctionnalité

Cette fonctionnalité n’est disponible que par le biais de l’API. Pour activer cette fonctionnalité, connectez-vous à GC Notification (opens new window)et accédez à la section Paramètres.

Types de fichiers et prérequis de taille

Vous pouvez téléverser des fichiers PDF, CSV, .jpeg, .png, .odt, .txt, .rtf, et des fichiers Microsoft Excel et Microsoft Word. La taille de votre fichier et de votre courriel doit être inférieure à 10 Mo.

Si vous devez envoyer d’autres types de fichiers, communiquez avec nous (opens new window).

Méthodes d’envoi

Il est possible de téléverser des fichiers de deux manières sur GC Notification :

en tant que pièce jointe au courriel
en tant que lien unique pour télécharger du courriel

Choisir une méthode d’envoi

Il est plus commun de recevoir des pièces jointes plutôt que des liens uniques. Toutefois, il n’est pas rare que des pièces jointes soient bloquées par des règles de sécurité ou par certains fournisseurs de comptes de courriel. Utilisez la méthode d’envoi de lien unique pour éviter que vos pièces jointes soient bloquées. Les fichiers envoyés par le biais d’un lien unique seront supprimés un an après l’envoi du message.

Avant de choisir une méthode d’envoi, effectuez des tests pour vérifier la méthode la plus propice pour vous.

Téléverser votre fichier

Pour téléverser des fichiers, passez un dictionnaire de paramètres dans la clé personalisation. Renseignez ce paramètre dans la clé associée à votre champ réservé dans votre gabarit, ou utilisez un nom de votre choix.

Vous devrez renseigner :

file : convertissez votre fichier en chaîne de caractères encodée en base64. Exemple : Q2FuYWRh (Canada encodé en base64)
filename : le nom de votre fichier que vous envoyez. Exemple : nom_service_nom_personne.pdf
sending_method : la méthode d’envoi pour ce fichier. Indiquez soit attach pour la méthode d’envoi par pièce jointe ou link pour la méthode d’envoi par lien unique

Si vous envoyez des fichiers en tant que pièces jointes

Spécifiez attach en tant que sending_method.

Par exemple :

Gabarit

Bonjour ((nom)),

Nous avons reçu vos document le ((date)).

Vous trouverez votre demande en pièce jointe.

Paramètres HTTP

"personalisation": {
  "nom": "Amala",
  "date": "2018-01-01",
  "fichier": {
    "file": "fichier encodé en base64",
    "filename": "votre_nom_de_fichier.pdf",
    "sending_method": "attach"
  }
}

Si vous envoyez des fichiers en tant que liens uniques

Ajouter un espace réservé dans votre gabarit
Envoyez des requêtes HTTP, spécifiez link en tant que sending_method

Ajouter un espace réservé au gabarit

Connectez-vous à GC Notification (opens new window).
Accédez à la page Gabarits et sélectionnez le gabarit de courriel approprié.
Sélectionnez Modifier.
Ajoutez un espace réservé au gabarit de courriel à l’aide de parenthèses doubles. Par exemple : ((lien_vers_fichier))

Vous pouvez télécharger [votre document](((lien_vers_fichier))).

Par exemple :

Gabarit

Bonjour ((nom)),

Nous avons reçu vos document le ((date)).

Vous pouvez télécharger [votre document](((lien_vers_fichier))).

Paramètres HTTP

"personalisation": {
  "nom": "Amala",
  "date": "2018-01-01",
  "lien_vers_fichier": {
    "file": "fichier encodé en base64",
    "filename": "votre_nom_de_fichier.pdf",
    "sending_method": "link"
  }
}

Réponse

Si la demande au client est acceptée, le client renvoie un dict :

{
  "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
  "reference": "STRING",
  "content": {
    "subject": "TEXTE DE L’OBJET",
    "body" : "TEXTE DU MESSAGE",
    "from_email" : "ADRESSE DE COURRIEL DE L’EXPÉDITEUR"
  },
  "uri": "https://api.notification.canada.ca/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
  "template": {
    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
    "version": 1,
    "uri": "https://api.notification.canada.ca/v2/template/f33517ff-2a88-4f6e-b855-c550268ce08a"
  }
}

Codes d’erreur

Si la demande a été refusée, le corps de la réponse est json, consultez le tableau ci-dessous pour plus de détails.

status_code	message	Comment réparer
`400`	`[{` `"error": "BadRequestError",` `"message": "Can't send to this recipient using a team-only API key"` `}]`	Utiliser le bon type de clé API
`400`	`[{` `"error": "BadRequestError",` `"message": "Can't send to this recipient when service is in trial mode` `}]`	Votre service ne peut pas envoyer cette notification en mode d’essai. Activez votre service dans les paramètres.
`400`	`[{` `"error": "BadRequestError",` `"message": "Unsupported file type '(FILE TYPE)'. Supported types are: '(ALLOWED TYPES)"` `}]`	Mauvais type de fichier. Vous ne pouvez télécharger que des fichiers .pdf, .csv, .txt, .jpeg, .png, .doc, .docx, .xls, .xlsx, .rtf ou .odt
`400`	`[{` `"error": "BadRequestError",` `"message": "File did not pass the virus scan"` `}]`	Le fichier contient un virus
`400`	`[{` `"error": "ValidationError",` `"message": "sending_method is a required property"` `}]`	Indiquer soit `attach` pour une pièce jointe ou `link` pour un lien unique comme méthode d’envoi
`400`	`[{` `"error": "ValidationError",` `"message": "filename is a required property"` `}]`	Précisez le nom du fichier que vous envoyez
`400`	`[{` `"error": "ValidationError",` `"message": "personalisation (key) is not one of [attach, link]"` `}]`	La méthode d’envoi précisée doit être soit `attach` pour une pièce jointe ou `link` pour un lien unique
`400`	`[{` `"error": "ValidationError",` `"message": "(key) : Incorrect padding : Error decoding base64 field"` `}]`	Le fichier doit être converti en une chaîne de caractères encodée en base64
`400`	`[{` `"error": "ValidationError",` `"message": "filename is too short"` `}]`	Le nom du fichier doit comporter au moins 3 caractères
`400`	`[{` `"error": "ValidationError",` `"message": "filename is too long"` `}]`	Le nom du fichier doit comporter moins de 250 caractères
`403`	`[{` `"error": "AuthError",` `"message": "Error: Your system clock must be accurate to within 30 seconds"` `}]`	Vérifiez votre horloge système
`403`	`[{` `"error": "AuthError",` `"message": "Invalid token: API key not found"` `}]`	Utilisez la bonne clé API
`429`	`[{` `"error": "RateLimitError",` `"message": "Exceeded rate limit for key type TEAM/TEST/LIVE of 1000 requests per 60 seconds"` `}]`	Reportez-vous à Débits maximaux API pour plus de renseignements
`429`	`[{` `"error": "TooManyRequestsError",` `"message": "Exceeded send limits (LIMIT NUMBER) for today"` `}]`	Reportez-vous à limites du service pour le nombre maximal
`500`	`[{` `"error": "Exception",` `"message": "Internal server error"` `}]`	GC Notification n’a pas pu traiter la demande, renvoyez votre notification.

Envoyer un message texte

POST /v2/notifications/sms

Corps de la requête

{
  "phone_number": "+19021234567",
  "template_id": "f33517ff-2a88-4f6e-b855-c550268ce08a"
}

Paramètres

Numéro de téléphone (obligatoire)

phone_number est le numéro de téléphone du destinataire du message texte.

ID du gabarit (obligatoire)

Pour rechercher template_id (ID du gabarit) :

Connectez-vous à GC Notification (opens new window).
Accédez à la page Gabarits et sélectionnez le gabarit approprié.
Sélectionnez Copier template ID dans le presse-papier.

Personnalisation (facultatif)

"personalisation": {
  "first_name": "Amala",
  "application_date": "2018-01-01"
}

Vous pouvez ignorer cet argument si un gabarit ne comporte pas de champs réservés pour les renseignements personnalisés.

Référence (facultatif)

"reference": "STRING"

Vous pouvez ignorer cet argument si vous n’avez pas de référence.

Expéditeur du message texte (facultatif)

sms_sender_id est un identificateur unique de l’expéditeur de la notification par message texte.

Pour rechercher l’expéditeur du message texte :

Connectez-vous à GC Notification (opens new window).
Accédez à la page Paramètres.
Dans la section Messages texte, sélectionnez Configurer à la ligne Expéditeurs de messages texte.

Ensuite, vous pouvez soit :

copier l’ID de l’expéditeur que vous souhaitez utiliser et le coller dans la méthode
sélectionner Modifier pour modifier l’expéditeur par défaut que le service utilisera, et sélectionnez Enregistrer.

"sms_sender_id": "8e222534-7f05-4972-86e3-17c5d9f894e2"

Vous pouvez ignorer cet argument si votre service n’a qu’un seul expéditeur de message texte, ou si vous voulez utiliser l’expéditeur par défaut.

Réponse

Si la demande est acceptée, le corps de la réponse est json avec un code de statut de 201 :

{
  "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
  "reference": "STRING",
  "content": {
    "body" : "TEXTE DU MESSAGE",
    "from_number": "EXPÉDITEUR"
  },
  "uri": "https://api.notification.canada.ca/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
  "template": {
    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
    "version": 1,
    "uri": "https://api.notification.canada.ca/v2/template/ceb50d92-100d-4b8b-b559-14fa3b091cd"
  }
}

Si vous utilisez la clé API de test, tous vos messages reviendront avec le statut « livré ».

Tous les messages envoyés à l’aide des clés équipe et liste de confiance ou active apparaîtront dans votre tableau de bord.

Codes d’erreur

Si la demande a été refusée, le corps de la réponse est json, consultez le tableau ci-dessous pour plus de détails.

status_code	message	Comment réparer
`400`	`[{` `"error": "BadRequestError",` `"message": "Can't send to this recipient using a team-only API key"` `}]`	Utiliser le bon type de clé API
`400`	`[{` `"error": "BadRequestError",` `"message": "Can't send to this recipient when service is in trial mode"` `}]`	Votre service ne peut pas envoyer cette notification en mode d’essai. Activez votre service dans les paramètres.
`403`	`[{` `"error": "AuthError",` `"message": "Error: Your system clock must be accurate to within 30 seconds"` `}]`	Vérifiez votre horloge système
`403`	`[{` `"error": "AuthError",` `"message": "Jeton non valide : Clé API introuvable"` `}]`	Utilisez la bonne clé API.
`429`	`[{` `"error": "RateLimitError",` `"message": "Exceeded rate limit for key type TEAM/TEST/LIVE of 1000 requests per 60 seconds"` `}]`	Reportez-vous à Débits maximaux API pour plus de renseignements
`429`	`[{` `"error": "TooManyRequestsError",` `"message": "Exceeded send limits (LIMIT NUMBER) for today"` `}]`	Reportez-vous à limites du service pour le nombre maximal
`500`	`[{` `"error": "Exception",` `"message": "Internal server error"` `}]`	GC Notification n’a pas pu traiter la demande, renvoyez votre notification.

Envoyer des notifications de masse

POST /v2/notifications/bulk

Envoyer des notifications de masse, jusqu’à 50 000 destinataires à la fois, pour un gabarit unique. Vous pouvez programmer l’envoi de notifications jusqu’à 4 jours à l’avance.

Corps de la requête

{
  "name": "Nom de l'envoi de masse",
  "template_id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
  "rows": [
    ["email address", "nom"],
    ["alice@example.com", "Alice"],
    ["bob@example.com", "Bob"]
  ],
  "scheduled_for": "2021-06-08T15:15:00", # chaîne facultative
  "reply_to_id": "f025b1a9-63af-43e8-b969-627bfe544bba" # chaîne facultative
}

Paramètres

nom (obligatoire)

name est le nom de votre envoi de masse. Il est utilisé pour identifier votre envoi.

ID du gabarit (obligatoire)

Pour rechercher template_id (ID du gabarit) :

Connectez-vous à GC Notification (opens new window).
Accédez à la page Gabarits et sélectionnez le gabarit approprié.
Sélectionnez Copier template ID dans le presse-papier.

lignes (obligatoire)

rows est une liste de listes. La première ligne est l’en-tête et doit comprendre au moins email address si vous envoyez un gabarit de courriel ou phone number si vous envoyez un gabarit de message texte. Les autres colonnes doivent correspondre aux champs réservés pour des renseignements personnalisés de votre gabarit.

Les lignes suivantes doivent inclure les informations de vos destinataires et doivent correspondre à l’ordre des colonnes de l’en-tête. Vous pouvez avoir entre 1 et 50 000 destinataires.

Paramètres optionnels

envoi programmé (optionnel)

scheduled_for peut être renseigné si vous souhaitez envoyer des notifications dans le futur, vous pouvez spécifier une date et une heure jusqu’à 4 jours dans le futur au format ISO 8601 (opens new window). Par exemple : 2021-06-08T15:15:00 (heure UTC).

identifiant de l’expéditeur (optionnel)

reply_to_id peut être renseigné si vous souhaitez utiliser une adresse de courriel pour recevoir les réponses spécifiques, vous pouvez indiquer indiquer l’identifiant de l’adresse courriel de réponse.

Pour trouver l’identifiant de votre addresse courriel de réponse :

Connectez-vous à GC Notification (opens new window).
Allez dans la page Paramètres.
Dans la section Courriel, sélectionnez Adresses courriel de réponse
Copiez l’identifiant de l’adresse que vous souhaitez utiliser

Par défaut, GC Notification utilisera votre adresse de courriel de réponse par défaut si vous n’en spécifiez pas, ou aucune si vous n’avez pas configuré cette fonctionnalité.

csv (optionnel)

csv peut être renseigné si vous préférez passer le contenu d’un fichier CSV plutôt que des lignes dans le paramètre rows. Passez le contenu complet de votre fichier CSV dans une clé nommée csv. Ne passez pas le paramètre rows.

Par exemple :

{
  "name": "Nom de l'envoi de masse",
  "template_id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
  "csv": "email address,nom\nalice@example.com,Alice"
}

Réponse

Délai d’attente de la réponse

qu’il soit défini à 15 secondes. L’API GC Notification pourrait prendre quelques secondes pour valider votre requête et sauvegarder vos paramètres si votre envoi de masse comporte beaucoup de destinataires.

Si la demande est acceptée, le corps de la réponse est json avec un code de statut de 201 :

{
   "data":{
      "api_key":{
         "id":"de1fafa2-fb2a-49c5-9b9a-8400727ecd29",
         "key_type":"team",
         "name":"Clé test"
      },
      "archived":false,
      "created_at":"2021-06-10T17:14:15.341308+00:00",
      "created_by":{
         "id":"6af522d0-2915-4e52-83a3-3690455a5fe6",
         "name":"Notify service user"
      },
      "id":"0ea216ae-4b03-46b7-ab44-893ae85104f5",
      "job_status":"pending",
      "notification_count":3,
      "original_file_name":"Nom de l'envoi de masse",
      "processing_finished":null,
      "processing_started":null,
      "scheduled_for":null,
      "sender_id":"f025b1a9-63af-43e8-b969-627bfe544bba",
      "service":"afa2be3b-1250-430f-a70f-28a1a9d49dfa",
      "service_name":{
         "name":"Test service"
      },
      "template":"f33517ff-2a88-4f6e-b855-c550268ce08a",
      "template_version":4,
      "updated_at":null
   }
}

Vous pouvez suivre la progression de votre envoi de masse dans l’interface de GC Notification.

Si vous avez programmé votre envoi, vous pouvez l’annuler dans l’interface web.

Codes d’erreur

Si la demande a été refusée, le corps de la réponse est json, consultez le tableau ci-dessous pour plus de détails.

Code HTTP	message	Comment réparer
`400`	`[{` `"error": "BadRequestError",` `"message": "You should specify either rows or csv"` `}]`	Passez les données au moyen de `rows` ou `csv`
`400`	`[{` `"error": "ValidationError",` `"message": "name is a required property"` `}]`	Spécifiez le paramètre `name`
`400`	`[{` `"error": "ValidationError",` `"message": "scheduled_for 42 is not of type string, null"` `}]`	Vérifiez que vous passez une date au format ISO 8601(opens new window)
`400`	`[{` `"error": "ValidationError",` `"message": "scheduled_for datetime cannot be in the past"` `}]`	Vérifiez que vous passez une date future
`400`	`[{` `"error": "ValidationError",` `"message": "scheduled_for datetime can only be up to 96 hours in the future"` `}]`	Vérifiez que votre date est au plus 4 jours dans le futur
`400`	`[{` `"error": "ValidationError",` `"message": "scheduled_for datetime format is invalid. It must be a valid ISO8601 date time format, https://en.wikipedia.org/wiki/ISO_8601"` `}]`	Vérifiez que vous passez une date au format ISO 8601(opens new window)
`400`	`[{` `"error": "BadRequestError",` `"message": "Template not found"` `}]`	Mettez à jour l’identifiant de gabarit
`400`	`[{` `"error": "BadRequestError",` `"message": "Template has been deleted"` `}]`	Créez un nouveau gabarit et renseignez son identifiant
`400`	`[{` `"error": "BadRequestError",` `"message": "Service is not allowed to send emails"` `}]`	Activez l’envoi de courriels dans les Paramètres
`400`	`[{` `"error": "BadRequestError",` `"message": "Missing column headers: name"` `}]`	Ajoutez l’en-tête manquant
`400`	`[{` `"error": "BadRequestError",` `"message": "Duplicate column headers: name, NAME"` `}]`	Retirez l’en-tête en doublon
`400`	`[{` `"error": "BadRequestError",` `"message": "Too many rows. Maximum number of rows allowed is 50000"` `}]`	Renseignez moins de 50 000 lignes
`400`	`[{` `{"error": "BadRequestError",` `"message": "You cannot send to these recipients because you used a team and safelist API key."` `}]`	Demandez d’activer votre service dans les Paramètres ou utilisez une clé d’API active
`400`	`[{` `"error": "BadRequestError",` `"message": "You cannot send to these recipients because your service is in trial mode. You can only send to members of your team and your safelist."` `}]`	Ajoutez des membres à votre équipe, mettez à jour votre liste de confiance ou demandez d’activer votre service
`400`	`[{` `"error": "BadRequestError",` `"message": "You only have 50 remaining messages before you reach your daily limit. You've tried to send 75 messages."` `}]`	Retirez les lignes en surplus, essayez à nouveau demain ou demander une augmentation de limites
`400`	`[{` `"error": "BadRequestError",` `"message": "Some rows have errors. Row 1 - name: Missing. Row 2 - email address: invalid recipient. Row 3 - name: Missing. Row 4 - name: Missing."` `}]`	Assurez-vous que les lignes n’ont pas de valeurs manquantes
`500`	`[{` `"error": "Exception",` `"message": "Internal server error"` `}]`	GC Notification n’a pas pu traiter la demande. Renvoyez votre notification.

Language selection

Rechercher

Envoyer un message

Envoyer un courriel

Corps de la requête

Paramètres

Envoyer un fichier par courriel

Types de fichiers et prérequis de taille

Méthodes d’envoi

Téléverser votre fichier

Si vous envoyez des fichiers en tant que pièces jointes

Si vous envoyez des fichiers en tant que liens uniques

Réponse

Codes d’erreur

Envoyer un message texte

Corps de la requête

Paramètres

Réponse

Codes d’erreur

Envoyer des notifications de masse

Corps de la requête

Paramètres

Paramètres optionnels

Réponse

Délai d’attente de la réponse

Codes d’erreur