Profils de destinataires

Le profil

Un profil est identifié par votre propre identifiant d'utilisateur, le même user_id sous lequel vos appareils push sont enregistrés. Il ne contient que des coordonnées : phone_number (E.164, un numéro canadien), email et language (en ou fr, en par défaut). Il ne contient aucune préférence de canal : l'ordre de votre envoi décide qui est joint par quoi.

Un profil répond avec object, user_id, phone_number, email, language, livemode, devices (les appareils push actifs de la personne : téléphones et navigateurs) et ses horodatages.

Écrire un numéro de téléphone ou une adresse courriel ici n'est pas un consentement. Notify vérifie le consentement, les désabonnements, les suppressions et les limites d'envoi exactement comme les API de SMS et de courriel.

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

from honkio import Honkio

client = Honkio()  # reads HONKIO_API_KEY

recipient = client.recipients.upsert(
    "user_1042",
    phone_number="+1416XXXXXXX",
    email="pat@example.com",
    language="en",
)
print(recipient["user_id"], recipient["devices"])

<?php

use Honkio\Honkio;

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

$recipient = $honkio->recipients->upsert('user_1042', [
    'phone_number' => '+1416XXXXXXX',
    'email' => 'pat@example.com',
    'language' => 'en',
]);
echo $recipient['user_id'], ' ', $recipient['devices'], PHP_EOL;

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

Gérer les profils

PUT /v1/recipients/:user_id crée le profil ou remplace tous ses champs : un champ omis est effacé et la langue revient à en. PATCH ne change que les champs envoyés, et null en efface un. GET en lit un ou les liste par curseur, et DELETE en supprime un.

Supprimer un profil désenregistre aussi les appareils push de cet utilisateur dans le même mode, donc la clé doit aussi avoir la permission de suppression push_devices (celle que demande DELETE /v1/push/devices). Sans elle, l'appel est refusé avec 403 FORBIDDEN (raison push_devices_permission_required) tant que l'utilisateur a des appareils actifs, et rien ne change. La suppression efface aussi le texte des notifications de cet utilisateur dans le mode, et une notification encore en attente n'envoie plus rien.

La clé a besoin de la permission recipients : r pour lire, w pour créer, m pour remplacer ou modifier et d pour supprimer. Une clé avec w mais sans m peut créer un profil, pas en remplacer un qui existe.

Supprimer un profil n'efface que cela : le profil, les appareils et le texte des notifications. Les messages, courriels et push envoyés par ces notifications gardent leur texte et le numéro ou l'adresse où ils sont allés jusqu'à ce que la rétention les efface, et le user_id d'un profil reste sur les notifications et les push passés. Pour effacer un numéro de téléphone partout, utilisez POST /v1/compliance/erasure. N'utilisez pas une adresse courriel ni un numéro de téléphone comme user_id si vous comptez sur la suppression d'un profil pour effacer.

Un compte garde jusqu'à 1 000 000 de profils en mode direct et 1 000 en mode test. En créer un au-delà est refusé avec 409 RECIPIENT_LIMIT_REACHED ; remplacer ou modifier un profil existant fonctionne toujours.

En direct et en test

Les profils sont gardés par mode de clé, comme les consentements : une clé de test lit et écrit des profils de test, une clé live des profils live, et un profil de l'autre mode répond 404 RECIPIENT_NOT_FOUND. La page Destinataires du tableau de bord suit de la même façon son interrupteur En direct et Test.