Concepts clés
Personnelle - une boîte de réception appartient à un seul utilisateur. L’API agit sur les boîtes de l’appelant. La boîte d’un autre utilisateur retourne une erreur404 avec le code INBOX_NOT_FOUND.
Boîtes d’un coéquipier - les admins et managers peuvent agir sur les boîtes d’un coéquipier avec user_id : dans le corps JSON pour créer ou modifier, en paramètre de requête pour lister ou supprimer. La boîte appartient au coéquipier et apparaît dans son sélecteur. Chaque ligne source doit être accessible au coéquipier. Sans droits d’admin ou de manager, la requête retourne une erreur 403 avec le code FORBIDDEN.
Avec user_id, un admin ou manager n’atteint que ce qui se trouve dans un espace de travail qu’il gère. La liste ne montre que les boîtes du coéquipier ayant au moins une source dans un tel espace, et seulement ces sources. Une boîte hors de cet espace retourne une erreur 404 à la modification ou à la suppression. Remplacer sources conserve les lignes du coéquipier dans d’autres espaces de travail. Supprimer une boîte qui contient aussi des lignes d’un autre espace retourne une erreur 403 avec le code FORBIDDEN. Une boîte de coéquipier doit garder au moins une ligne de l’espace de l’admin, sinon la requête retourne une erreur 400 avec le code INVALID_INBOX_SOURCE.
Sources - chaque source est une ligne Allo (allo_number) avec des conditions facultatives. Une source avec une liste conditions vide couvre toutes les conversations de la ligne. Une condition MENU_BRANCH correspond à des chemins dans les menus téléphoniques de la ligne. Une condition MENU_OPTION correspond à des touches d’un seul menu.
Plusieurs options sur une ligne - chaque ligne apparaît une seule fois dans sources. Pour couvrir plusieurs options de menu d’une même ligne, mettez tous leurs chemins dans les branches d’une seule condition MENU_BRANCH. Deux sources avec le même allo_number retournent une erreur 400 avec le code INVALID_INBOX_SOURCE.
Les conditions de menu demandent une ligne routée par le moteur - une condition de menu n’est acceptée que sur une ligne dont la liste d’options de menu n’est pas vide, et seulement avec des chemins de cette liste. Sur toute autre ligne, utilisez une source sur toute la ligne, avec des conditions vides.
Juste après la création - lister les conversations d’une boîte créée à l’instant peut brièvement retourner une erreur 404 avec le code INBOX_NOT_FOUND et retryable: true. Réessayez une fois. Une erreur 404 à la modification ou à la suppression n’est pas à réessayer.
Suggestions d’abord - Obtenir les suggestions de boîtes retourne des sources classées d’après les appels et SMS récents de l’appelant. Chaque suggestion contient une source à mettre telle quelle dans sources : vous n’avez jamais besoin des identifiants de nœuds du menu. Utilisez Lister les options de menu seulement pour construire une branche sur mesure : chaque option contient une condition prête à l’emploi.
Lister les conversations - passez inbox_id à Lister les conversations à la place de allo_number. Les résultats contiennent des conversations de plusieurs lignes, chacune avec son propre allo_number. Les sources et filtres enregistrés de la boîte s’appliquent, mais pas les onglets À traiter et Les miennes de l’app. “Non lues uniquement” n’est pas enregistré sur une boîte : passez le paramètre de requête unread à Lister les conversations.
Limites - jusqu’à 50 boîtes de réception par utilisateur, 100 sources par boîte, 10 conditions par source et 60 étapes de menu par boîte. Une MENU_BRANCH prend de 1 à 20 branches de 1 à 6 étapes. Créer une 51e boîte retourne une erreur 400 avec le code INBOX_LIMIT_REACHED. Un nom de plus de 80 caractères, un emoji de plus de 16, ou plus de 100 sources ou de 10 conditions par source retourne une erreur 400 avec le code INVALID_REQUEST_BODY, et field_errors nomme chaque champ.
Scopes - la lecture demande INBOXES_READ, l’écriture INBOXES_WRITE. Une clé sans le scope reçoit une erreur 403 avec le code API_KEY_INSUFFICIENT_SCOPE.
Endpoints
Lister les boîtes de réception
Vos boîtes, ou celles d’un coéquipier
Obtenir les suggestions de boîtes
Des sources prêtes à l’emploi, classées d’après l’activité récente
Lister les options de menu
Les options du menu téléphonique d’une ligne, à plat
Créer une boîte de réception
Créer une boîte pour vous ou pour un coéquipier
Modifier une boîte de réception
Renommer, changer les sources ou les filtres, couper ou réactiver les notifications
Supprimer une boîte de réception
Supprimer une boîte