Groupes de contacts

Lister les groupes de contacts

Paramètres

Réponses

• 200Une page de groupes, du plus récent au plus ancien, chacun avec ses membres.›

  Champ	Type	Description
  totalobligatoire	integer	Nombre total d’enregistrements correspondants.
  limitobligatoire	integer
  offsetobligatoire	integer
  data[]obligatoire	object[]
  idobligatoire	string
  nameobligatoire	string
  descriptionobligatoire	string	Peut être null
  member_countobligatoire	integer
  members[]obligatoire	object[]
  idobligatoire	string	L’identifiant du contact.
  phone_numberobligatoire	string	Peut être null
  nameobligatoire	string	Peut être null
  created_atobligatoire	string	Format : date-time
  updated_atobligatoire	string	Format : date-time
  livemodeobligatoire	boolean	false pour un enregistrement fait ou lu avec une clé de test (un enregistrement en mode test), true pour un enregistrement de production.
• 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 : la requête n’a pas passé la validation ; details indique les champs en cause.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

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

Créer un groupe de contacts

Corps de la requête

Réponses

• 201Le groupe.›

  Champ	Type	Description
  idobligatoire	string
  nameobligatoire	string
  descriptionobligatoire	string	Peut être null
  member_countobligatoire	integer
  members[]obligatoire	object[]
  idobligatoire	string	L’identifiant du contact.
  phone_numberobligatoire	string	Peut être null
  nameobligatoire	string	Peut être null
  created_atobligatoire	string	Format : date-time
  updated_atobligatoire	string	Format : date-time
  livemodeobligatoire	boolean	false pour un enregistrement fait ou lu avec une clé de test (un enregistrement en mode test), true pour un enregistrement de production.
• 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.
• 409CONTACT_GROUP_ALREADY_EXISTS : ce nom est déjà utilisé.Le corps d’erreur standard.
• 422VALIDATION_ERROR : la requête n’a pas passé la validation ; details indique les champs en cause.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

curl -X POST https://api.honkio.ca/v1/contact-groups \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "..."
  }'

Obtenir un groupe de contacts avec ses membres

Paramètres

Réponses

• 200Le groupe, avec ses membres.›

  Champ	Type	Description
  idobligatoire	string
  nameobligatoire	string
  descriptionobligatoire	string	Peut être null
  member_countobligatoire	integer
  members[]obligatoire	object[]
  idobligatoire	string	L’identifiant du contact.
  phone_numberobligatoire	string	Peut être null
  nameobligatoire	string	Peut être null
  created_atobligatoire	string	Format : date-time
  updated_atobligatoire	string	Format : date-time
  livemodeobligatoire	boolean	false pour un enregistrement fait ou lu avec une clé de test (un enregistrement en mode test), true pour un enregistrement de production.
• 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.
• 404CONTACT_GROUP_NOT_FOUND.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

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

Mettre à jour un groupe de contacts

Paramètres

Corps de la requête

Réponses

• 200Le groupe mis à jour.›

  Champ	Type	Description
  idobligatoire	string
  nameobligatoire	string
  descriptionobligatoire	string	Peut être null
  member_countobligatoire	integer
  members[]obligatoire	object[]
  idobligatoire	string	L’identifiant du contact.
  phone_numberobligatoire	string	Peut être null
  nameobligatoire	string	Peut être null
  created_atobligatoire	string	Format : date-time
  updated_atobligatoire	string	Format : date-time
  livemodeobligatoire	boolean	false pour un enregistrement fait ou lu avec une clé de test (un enregistrement en mode test), true pour un enregistrement de production.
• 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.
• 403LIVE_KEY_REQUIRED lorsqu’une clé de test tente de modifier un élément référencé par la liste d’autorisation ou de blocage d’une clé de production (les contacts, groupes et listes sont tenus séparément pour chaque mode de clé : une clé de test n’atteint donc que ceux de test, qu’aucune clé de production n’utilise). Aussi FORBIDDEN lorsque la clé ne dispose pas de la permission requise.Le corps d’erreur standard.
• 404CONTACT_GROUP_NOT_FOUND.Le corps d’erreur standard.
• 409CONTACT_GROUP_ALREADY_EXISTS : ce nom est déjà utilisé.Le corps d’erreur standard.
• 422VALIDATION_ERROR : la requête n’a pas passé la validation ; details indique les champs en cause.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

curl -X PATCH https://api.honkio.ca/v1/contact-groups/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Patients due for a recall visit"
  }'

Supprimer un groupe de contacts

Paramètres

Réponses

• 204Supprimé. Ses contacts sont conservé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.
• 403LIVE_KEY_REQUIRED lorsqu’une clé de test tente de modifier un élément référencé par la liste d’autorisation ou de blocage d’une clé de production (les contacts, groupes et listes sont tenus séparément pour chaque mode de clé : une clé de test n’atteint donc que ceux de test, qu’aucune clé de production n’utilise) ; KEY_FENCED lorsque la modification assouplirait les restrictions d’autorisation et de blocage de la clé appelante elle-même. Aussi FORBIDDEN lorsque la clé ne dispose pas de la permission requise.Le corps d’erreur standard.
• 404CONTACT_GROUP_NOT_FOUND.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

curl -X DELETE https://api.honkio.ca/v1/contact-groups/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Ajouter un membre à un groupe de contacts

Paramètres

Corps de la requête

Réponses

• 201Le membre ajouté.›

  Champ	Type	Description
  idobligatoire	string	L’identifiant du contact.
  phone_numberobligatoire	string
  nameobligatoire	string	Peut être null
  added_atobligatoire	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.
• 403LIVE_KEY_REQUIRED lorsqu’une clé de test tente de modifier un élément référencé par la liste d’autorisation ou de blocage d’une clé de production (les contacts, groupes et listes sont tenus séparément pour chaque mode de clé : une clé de test n’atteint donc que ceux de test, qu’aucune clé de production n’utilise) ; KEY_FENCED lorsque la modification assouplirait les restrictions d’autorisation et de blocage de la clé appelante elle-même. Aussi FORBIDDEN lorsque la clé ne dispose pas de la permission requise.Le corps d’erreur standard.
• 404CONTACT_GROUP_NOT_FOUND ou CONTACT_NOT_FOUND.Le corps d’erreur standard.
• 409CONTACT_GROUP_MEMBER_EXISTS.Le corps d’erreur standard.
• 422VALIDATION_ERROR (ni contact_id ni phone_number), INVALID_PHONE_NUMBER ou CONTACT_HAS_NO_PHONE (le contact n’a pas de numéro de téléphone).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

curl -X POST https://api.honkio.ca/v1/contact-groups/ID/members \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "CONTACT_ID"
  }'

Retirer un membre d’un groupe de contacts

Paramètres

Réponses

• 204Retiré du groupe. Le contact est conservé.
• 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.
• 403LIVE_KEY_REQUIRED lorsqu’une clé de test tente de modifier un élément référencé par la liste d’autorisation ou de blocage d’une clé de production (les contacts, groupes et listes sont tenus séparément pour chaque mode de clé : une clé de test n’atteint donc que ceux de test, qu’aucune clé de production n’utilise) ; KEY_FENCED lorsque la modification assouplirait les restrictions d’autorisation et de blocage de la clé appelante elle-même. Aussi FORBIDDEN lorsque la clé ne dispose pas de la permission requise.Le corps d’erreur standard.
• 404CONTACT_GROUP_NOT_FOUND ou CONTACT_GROUP_MEMBER_NOT_FOUND.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

curl -X DELETE https://api.honkio.ca/v1/contact-groups/ID/members/CONTACT_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Envoyer un SMS à tous les membres d’un groupe de contacts

Paramètres

Corps de la requête

Réponses

• 207Toujours 207 : vérifiez chaque résultat, pas le statut. Une diffusion réelle répétée avec la même Idempotency-Key dans les 24 heures renvoie le résultat enregistré de la première tentative.›

  Champ	Type	Description
  group_idobligatoire	string
  sent_toobligatoire	integer	Membres qui n’ont pas échoué.
  failedobligatoire	integer
  results[]obligatoire	object[]
  toobligatoire	string	Le numéro du membre.
  statusobligatoire	string	En minuscules : le statut du message (queued, sent, delivered, etc.), ou failed.
  message_id	string	Absent lorsque l’envoi au membre a échoué avant qu’un message soit créé.
  error	string	Un code d’erreur : la raison de l’échec pour ce membre, ou le error_code du message lui-même.
  estimated_completion_at	string	Une estimation du moment où l’opérateur aura envoyé au dernier membre, d’après la file du numéro d’envoi. Null en mode test. Absent d’une réponse rejouée pour une diffusion envoyée avant son ajout. Format : date-time Peut être null
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402INSUFFICIENT_BALANCE : le solde ne couvre pas l’envoi. RENT_OWED : un loyer est dû pour un numéro libéré pendant sa suspension; rechargez d’abord pour le payer. Aussi PAYMENT_REQUIRED lorsqu’une clé de production est utilisée avant la première recharge.Le corps d’erreur standard.
• 403FORBIDDEN (skip_consent_check avec une clé de production, ou la clé n’a pas l’autorisation messages:w), ACCOUNT_NOT_VERIFIED, SENDING_PAUSED, ou TOLL_FREE_NOT_VERIFIED (un numéro from sans frais dont la vérification sans frais n’est pas approuvée ; clés de test comprises). Un membre en production sans double consentement confirmé échoue seul dans les résultats avec DOUBLE_OPT_IN_REQUIRED.Le corps d’erreur standard.
• 404CONTACT_GROUP_NOT_FOUND.Le corps d’erreur standard.
• 422VALIDATION_ERROR, BROADCAST_TOO_LARGE, MESSAGE_TOO_LONG ou LINK_SHORTENER_BLOCKED.Le corps d’erreur standard.
• 429BROADCAST_LIMIT_REACHED, DAILY_LIMIT_REACHED, FANOUT_LIMIT_REACHED, NUMBER_QUEUE_FULL (les segments de message de la diffusion dépasseraient la file d’attente de l’opérateur pour le numéro d’envoi; Retry-After est fourni quand attendre libérerait de la place) ou RECIPIENT_RATE_LIMITED, ou RATE_LIMITED au-delà de 100 requêtes par seconde. SCHEDULED_LIMIT_REACHED (avec scheduled_at) : un message programmé par membre ferait dépasser au compte 10 000 messages réels programmés, ou 1 000 messages de test programmés ; la diffusion est refusée en entier, avant que tout membre soit programmé ou facturé (details contient mode, limit, scheduled et requested).Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

curl -X POST https://api.honkio.ca/v1/contact-groups/ID/messages \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+1416XXXXXXX"
  }'