Référence de l’API

Destinataires

Les coordonnées de chacun de vos utilisateurs, indexées par votre propre identifiant d’utilisateur.

get/v1/recipients

Lister les profils de destinataires

Permissionrecipients:rSDK Node.jshonkio.recipients.list()

Les profils sont tenus séparément pour chaque mode de clé : une clé de test ne lit et n’écrit que les profils de test, une clé de production ceux de production, et un profil de l’autre mode répond RECIPIENT_NOT_FOUND.

Nécessite recipients:r.

Paramètres

Paramètre	Type	Description
`limit`requête	string	De 1 à 100. Valeur par défaut : 50.
`cursor`requête	string	La valeur next_cursor de la page précédente.

Réponses

200Une page de profils dans le mode de la clé appelante, du plus récent au plus ancien.

Champ	Type	Description
`data[]`obligatoire	object[]
`object`obligatoire	string	Une valeur parmi : recipient
`user_id`obligatoire	string	Votre propre identifiant pour la personne.
`phone_number`obligatoire	string	E.164, ou null. Peut être null
`email`obligatoire	string	Une adresse courriel, ou null. Peut être null
`language`obligatoire	string	Une valeur parmi : en \| fr
`livemode`obligatoire	boolean	false pour un profil créé par une clé de test.
`devices`obligatoire	integer	Les appareils push actifs enregistrés sous ce user_id dans le même mode.
`created_at`obligatoire	string	Format : date-time
`updated_at`obligatoire	string	Format : date-time
`has_more`obligatoire	boolean
`next_cursor`obligatoire	string	Passez-le comme cursor pour la page suivante. Null sur la dernière page. Peut être null

401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
403La clé API ne dispose pas de la permission requise pour cette opération, ou le compte est suspendu ou fermé.Le corps d’erreur standard.
422VALIDATION_ERROR : limit n’est pas un entier positif.Le corps d’erreur standard.
429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { data, error } = await honkio.recipients.list({ limit: 50 })
if (error) throw new Error(error.message)
for (const recipient of data.data) console.log(recipient.user_id)

curl https://api.honkio.ca/v1/recipients \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

get/v1/recipients/{user_id}

Obtenir un profil de destinataire

Permissionrecipients:rSDK Node.jshonkio.recipients.get()

Nécessite recipients:r.

Paramètres

Paramètre	Type	Description
`user_id`obligatoirechemin	string	Votre propre identifiant pour la personne, jusqu’à 255 caractères : le user_id sous lequel ses appareils push sont enregistrés.

Réponses

200Le profil.

Champ	Type	Description
`object`obligatoire	string	Une valeur parmi : recipient
`user_id`obligatoire	string	Votre propre identifiant pour la personne.
`phone_number`obligatoire	string	E.164, ou null. Peut être null
`email`obligatoire	string	Une adresse courriel, ou null. Peut être null
`language`obligatoire	string	Une valeur parmi : en \| fr
`livemode`obligatoire	boolean	false pour un profil créé par une clé de test.
`devices`obligatoire	integer	Les appareils push actifs enregistrés sous ce user_id dans le même mode.
`created_at`obligatoire	string	Format : date-time
`updated_at`obligatoire	string	Format : date-time

401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
403La clé API ne dispose pas de la permission requise pour cette opération, ou le compte est suspendu ou fermé.Le corps d’erreur standard.
404RECIPIENT_NOT_FOUND : aucun profil pour ce user_id dans le mode de la clé appelante.Le corps d’erreur standard.
422VALIDATION_ERROR (details nomme les champs ; user_id doit compter de 1 à 255 caractères), INVALID_PHONE_NUMBER (phone_number n’est pas au format E.164) ou NON_CANADIAN_NUMBER (phone_number n’est pas un +1 avec un indicatif régional canadien).Le corps d’erreur standard.
429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { data: recipient, error } = await honkio.recipients.get('user_1042')
if (error) throw new Error(error.message)
console.log(recipient.language, recipient.devices)

curl https://api.honkio.ca/v1/recipients/USER_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

put/v1/recipients/{user_id}

Créer ou remplacer un profil de destinataire

Permissionrecipients:wSDK Node.jshonkio.recipients.upsert()

Crée le profil de user_id, ou remplace tous les champs du profil existant. Un compte contient au plus 1 000 000 de profils en mode production et 1 000 en mode test : en créer un au-delà donne 409 RECIPIENT_LIMIT_REACHED (details.limit) ; en remplacer un ne le donne jamais. Les profils sont tenus séparément pour chaque mode de clé : une clé de test ne lit et n’écrit que les profils de test, une clé de production ceux de production, et un profil de l’autre mode répond RECIPIENT_NOT_FOUND.

Nécessite recipients:w.

Paramètres

Paramètre	Type	Description
`user_id`obligatoirechemin	string	Votre propre identifiant pour la personne, jusqu’à 255 caractères : le user_id sous lequel ses appareils push sont enregistrés.

Corps de la requête

Le profil complet. Un champ omis est effacé (language revient à en).

Champ	Type	Description
`phone_number`	string	E.164, un numéro canadien (+1 avec un indicatif régional canadien), comme l’accepte /v1/messages. null l’efface. Au plus 32 caractères Peut être null
`email`	string	Une adresse courriel, vérifiée comme /v1/emails vérifie un destinataire. null l’efface. Format : email Au plus 254 caractères Peut être null
`language`	string	en ou fr : la langue de ce qui est envoyé à cette personne. en par défaut. Une valeur parmi : en \| fr

Réponses

200Le profil, créé ou remplacé.

Champ	Type	Description
`object`obligatoire	string	Une valeur parmi : recipient
`user_id`obligatoire	string	Votre propre identifiant pour la personne.
`phone_number`obligatoire	string	E.164, ou null. Peut être null
`email`obligatoire	string	Une adresse courriel, ou null. Peut être null
`language`obligatoire	string	Une valeur parmi : en \| fr
`livemode`obligatoire	boolean	false pour un profil créé par une clé de test.
`devices`obligatoire	integer	Les appareils push actifs enregistrés sous ce user_id dans le même mode.
`created_at`obligatoire	string	Format : date-time
`updated_at`obligatoire	string	Format : date-time

401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
403FORBIDDEN : la clé n’a pas la permission d’écriture recipients, ou un profil existe pour user_id et le remplacer exige la permission de modification recipients, que la clé n’a pas (details.reason recipient_exists_modify_permission_required).Le corps d’erreur standard.
409RECIPIENT_LIMIT_REACHED : créer le profil ferait dépasser au compte son nombre de profils dans ce mode (1 000 000 en production, 1 000 en test ; details.limit, details.livemode). Le remplacement d’un profil existant n’est jamais refusé pour cette raison.Le corps d’erreur standard.
422VALIDATION_ERROR (details nomme les champs ; user_id doit compter de 1 à 255 caractères), INVALID_PHONE_NUMBER (phone_number n’est pas au format E.164) ou NON_CANADIAN_NUMBER (phone_number n’est pas un +1 avec un indicatif régional canadien).Le corps d’erreur standard.
429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { data: recipient, error } = await honkio.recipients.upsert('user_1042', {
  phoneNumber: '+1416XXXXXXX',
  email: 'pat@example.com',
  language: 'fr',
})
if (error) throw new Error(error.message)
console.log(recipient.user_id, recipient.devices)

curl -X PUT https://api.honkio.ca/v1/recipients/USER_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+1416XXXXXXX",
    "email": "pat@example.com",
    "language": "fr"
  }'

patch/v1/recipients/{user_id}

Mettre à jour un profil de destinataire

Permissionrecipients:mSDK Node.jshonkio.recipients.update()

Modifie seulement les champs fournis. Les profils sont tenus séparément pour chaque mode de clé : une clé de test ne lit et n’écrit que les profils de test, une clé de production ceux de production, et un profil de l’autre mode répond RECIPIENT_NOT_FOUND.

Nécessite recipients:m.

Paramètres

Paramètre	Type	Description
`user_id`obligatoirechemin	string	Votre propre identifiant pour la personne, jusqu’à 255 caractères : le user_id sous lequel ses appareils push sont enregistrés.

Corps de la requête

Les champs à modifier. Un champ omis est conservé ; null l’efface.

Champ	Type	Description
`phone_number`	string	E.164, un numéro canadien (+1 avec un indicatif régional canadien), comme l’accepte /v1/messages. null l’efface. Au plus 32 caractères Peut être null
`email`	string	Une adresse courriel, vérifiée comme /v1/emails vérifie un destinataire. null l’efface. Format : email Au plus 254 caractères Peut être null
`language`	string	en ou fr : la langue de ce qui est envoyé à cette personne. en par défaut. Une valeur parmi : en \| fr

Réponses

200Le profil mis à jour.

Champ	Type	Description
`object`obligatoire	string	Une valeur parmi : recipient
`user_id`obligatoire	string	Votre propre identifiant pour la personne.
`phone_number`obligatoire	string	E.164, ou null. Peut être null
`email`obligatoire	string	Une adresse courriel, ou null. Peut être null
`language`obligatoire	string	Une valeur parmi : en \| fr
`livemode`obligatoire	boolean	false pour un profil créé par une clé de test.
`devices`obligatoire	integer	Les appareils push actifs enregistrés sous ce user_id dans le même mode.
`created_at`obligatoire	string	Format : date-time
`updated_at`obligatoire	string	Format : date-time

401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
403La clé API ne dispose pas de la permission requise pour cette opération, ou le compte est suspendu ou fermé.Le corps d’erreur standard.
404RECIPIENT_NOT_FOUND : aucun profil pour ce user_id dans le mode de la clé appelante.Le corps d’erreur standard.
422VALIDATION_ERROR (details nomme les champs ; user_id doit compter de 1 à 255 caractères), INVALID_PHONE_NUMBER (phone_number n’est pas au format E.164) ou NON_CANADIAN_NUMBER (phone_number n’est pas un +1 avec un indicatif régional canadien).Le corps d’erreur standard.
429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { error } = await honkio.recipients.update('user_1042', { email: 'pat@example.com' })
if (error) throw new Error(error.message)

curl -X PATCH https://api.honkio.ca/v1/recipients/USER_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "pat@example.com"
  }'

delete/v1/recipients/{user_id}

Supprimer un profil de destinataire

Permissionrecipients:dSDK Node.jshonkio.recipients.delete()

Supprime le profil et désinscrit les appareils push enregistrés sous ce user_id dans le même mode, qu’il y ait un profil ou non, et efface le texte des notifications de cet utilisateur dans ce mode (une notification en attente n’envoie plus rien). Les messages, courriels et notifications push envoyés par ces notifications conservent leur texte et le numéro ou l’adresse de destination jusqu’à ce que la politique de conservation les efface ; POST /v1/compliance/erasure efface un numéro de téléphone partout. La désinscription des appareils exige aussi la permission de suppression push_devices (OAuth : la portée push:devices) ; une clé qui ne l’a pas est refusée (403, details.reason push_devices_permission_required) tant que l’utilisateur a des appareils actifs, et rien ne change. Un appareil enregistré après la suppression n’est pas touché. Les profils sont tenus séparément pour chaque mode de clé : une clé de test ne lit et n’écrit que les profils de test, une clé de production ceux de production, et un profil de l’autre mode répond RECIPIENT_NOT_FOUND.

Nécessite recipients:d.

Paramètres

Paramètre	Type	Description
`user_id`obligatoirechemin	string	Votre propre identifiant pour la personne, jusqu’à 255 caractères : le user_id sous lequel ses appareils push sont enregistrés.

Réponses

204Le profil supprimé, les appareils actifs de l’utilisateur dans ce mode désinscrits (l’un ou l’autre a pu être absent), et le texte des notifications de l’utilisateur dans ce mode effacé. Les messages, courriels et notifications push qu’elles ont envoyés ne sont pas modifiés.
401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
403FORBIDDEN : la clé n’a pas la permission de suppression recipients, ou l’utilisateur a des appareils push actifs dans ce mode et la clé n’a pas la permission de suppression push_devices (details.reason push_devices_permission_required) ; rien n’a changé.Le corps d’erreur standard.
404RECIPIENT_NOT_FOUND : ni profil ni appareil push actif pour ce user_id dans le mode de la clé appelante.Le corps d’erreur standard.
422VALIDATION_ERROR (details nomme les champs ; user_id doit compter de 1 à 255 caractères), INVALID_PHONE_NUMBER (phone_number n’est pas au format E.164) ou NON_CANADIAN_NUMBER (phone_number n’est pas un +1 avec un indicatif régional canadien).Le corps d’erreur standard.
429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { error } = await honkio.recipients.delete('user_1042')
if (error) throw new Error(error.message)

curl -X DELETE https://api.honkio.ca/v1/recipients/USER_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"