API publique Beta

Trouver les conversations qui demandent de l'attention

Filtrez par awaitingReply, unread, unassigned, assigneeId, agentGroupId, snoozed, priority ou tagIds. awaitingReply ignore les notes internes ; unread est propre au collègue authentifié. unassigned signifie sans responsable individuel, même si une équipe est attribuée. Les étiquettes correspondent à n'importe lequel des identifiants fournis.

GET /api/v1/conversations?status=open&awaitingReply=true&compact=true&sort=waitingSince&direction=asc

Triez par waitingSince, lastMessageAt, createdAt ou priorité métier, avec la direction asc ou desc. Les identifiants départagent les égalités. Les filtres omis conservent compact=false et snoozed=any. En REST, tagIds accepte des identifiants séparés par des virgules ; MCP accepte aussi un tableau. waitingSince démarre au premier message entrant après la dernière réponse ; les relances et les notes internes ne le réinitialisent pas. Lancez cette analyse de la file d'attente de façon planifiée, même quand aucun webhook n'arrive, pour faire ressortir les anciens fils.

Rattraper son retard sans relire la boîte de réception

Utilisez GET /api/v1/sync avec conversations:read. Le flux durable inclut les changements de conversations, les étiquettes, les messages, les propriétés de contact, les souvenirs et les traces de suppression. Chaque charge utile exige aussi sa propre portée de lecture : le corps des messages nécessite messages:read et les souvenirs contact-memory:read. Les identifiants restreints ne reçoivent que les canaux autorisés.

1. Commencez sans curseur, suivez nextCursor jusqu'à ce que hasMore soit false, puis enregistrez ce curseur.
2. Lisez les listes actuelles de conversations et de contacts, ainsi que l'historique nécessaire à votre état initial.
3. Rejouez depuis le curseur enregistré pour récupérer les changements survenus pendant cette lecture. Traitez chaque page, puis enregistrez nextCursor.

Dédupliquez par id d'événement : la relecture garantit au moins une livraison, donc les actions en aval doivent avoir leur propre protection contre les doublons. Une requête sans curseur couvre la dernière heure, pas un instantané complet. Les événements sont conservés 30 jours ; un HTTP 410 resync_required signifie qu'il faut tout recharger. Rechargez aussi après avoir élargi les portées ou l'accès aux canaux. Utilisez limit jusqu'à 100 et maxBodyChars jusqu'à 10 000 (500 par défaut). Définissez compact=true pour obtenir les champs de message textPreview/textTruncated limités à 200 caractères au lieu de body/bodyTruncated. Les webhooks peuvent réveiller un agent ; le flux reste disponible sans abonnement aux webhooks ou lorsque la livraison des webhooks prend du retard.

Enregistrer une vérification une fois et partager le résultat

Avant de recommencer une investigation, lisez list_conversation_checks (GET /api/v1/conversations/{conversationId}/checks). Enregistrez un résultat avec record_conversation_check (PUT sur le même chemin), en fournissant key, result, checkedBy et une reference optionnelle pour l'identifiant ou l'URL de la carte. Par exemple : key=product-version, result=Shopstar Go verified, checkedBy=Engineer, reference=card-X. Sonny enregistre l'actorId authentifié et l'horodatage checkedAt. Réutiliser une key remplace uniquement cette vérification ; il s'agit d'un état actuel, pas d'un historique. Les lectures nécessitent conversations:read et les écritures conversations:write, toutes deux limitées au canal de la conversation. Ces appels n'envoient pas de réponse et ne marquent pas le vendeur comme ayant répondu.

Attribuer et mettre à jour le travail par lots

Découvrez les collègues et équipes actifs et attribuables avec GET /api/v1/members and /teams (members:read). Les réponses incluent la disponibilité et l'accès effectif aux canaux, sans les adresses e-mail. Utilisez conversations:write pour modifier status, priority, assigneeId, agentGroupId, snoozedUntil, snoozedUntilReply, addTagIds ou removeTagIds.

POST /api/v1/conversations/batch
{
  "conversationIds": ["conversation_1", "conversation_2"],
  "updates": { "agentGroupId": "team_1", "assignment": "round_robin" }
}

Le tourniquet choisit un membre d'équipe disponible qui a accès au canal de la conversation. Sans membre éligible, une mise à jour individuelle renvoie 409 et un élément de lot échoue. Chaque lot accepte jusqu'à 100 identifiants uniques et applique un correctif de façon atomique par conversation. Examinez chaque résultat { id, ok, error? } ; certains éléments peuvent échouer. Les lots utilisent la limite de débit actuelle par requête, sans décompte pondéré selon le nombre d'éléments.

Partager le contexte client avec Sonny AI

Listez, enregistrez et supprimez les souvenirs de contact avec contact-memory:read/write. Fournissez à la fois contactId et un sourceId accessible ; le contact doit avoir une conversation sur cette source. Les faits enregistrés suivent la même validation, la même gestion des doublons et les mêmes limites que l'application, et sont enregistrés comme souvenirs manuels.

Lisez les définitions de propriétés sur /api/v1/properties et lisez ou définissez les valeurs sur /api/v1/contacts/{contactId}/properties. MCP expose list_properties, get_contact_properties et set_contact_property. Ils nécessitent contacts:read/write et l'accès à tous les canaux. Définissez exactement un propertyId ou un propertyName, avec une valeur texte ou null pour l'effacer. Les valeurs texte, nombre, URL, date et liste sont validées par rapport à la définition du champ.

PUT /api/v1/contacts/contact_1/properties
{ "propertyName": "Plan", "value": "Pro" }

GET /api/v1/contacts?property[Plan]=Pro

Les filtres de propriétés correspondent aux chaînes stockées exactes ; plusieurs propriétés doivent toutes correspondre. Les valeurs écrites via l'API sont signalées comme données API dans Co-Pilot et le répondeur automatique. Les règles existantes sur les clients vérifiés et les sources s'appliquent toujours. Les valeurs de champs internes saisies manuellement restent exclues de ce contexte IA.

Lire les mêmes rapports que votre équipe

Avec reporting:read, appelez GET /api/v1/reporting/{kind}. Les types sont overview, volume, response-times, agents, sources, tags, csat, ai, knowledge, leads et online-hours. overview combine les totaux, les temps de réponse et le CSAT. Les filtres sont period (1 à 365 jours, 30 par défaut), les dates from/to appariées (to est exclusif), granularity (day/month), source, assigneeId et tagId. source accepte all, all-chat, all-email, website:{id} ou email:{id}.

Les rapports utilisent les requêtes du tableau de bord et les contrôles d'accès actuels. knowledge utilise les dates et les canaux autorisés, indépendamment de la source, du responsable ou de l'étiquette sélectionnés. online-hours mesure la présence des collègues accessibles dans l'espace de travail ; ses totaux de conversations restent limités aux canaux. Les points de terminaison /csat existants conservent leur portée distincte csat:read et peuvent décrire une population différente.

Envoyer des fichiers avec des réponses ou des notes internes

Accordez attachments:write et importez un fichier de 25 Mo maximum pour une conversation. POST /api/v1/attachments prend les champs multipart file et conversationId. La réponse contient un id et expiresAt. Passez jusqu'à 10 attachmentIds à une réponse ou une note dans l'heure. Chaque fichier importé est lié à votre utilisateur et à la conversation et ne peut être utilisé qu'une seule fois. Les fichiers inutilisés sont nettoyés après expiration.

POST /api/v1/conversations/conversation_1/reply
{ "attachmentIds": ["upload_1"] }

Les réponses nécessitent messages:send ; les notes internes nécessitent messages:write et n'atteignent jamais les clients. Les messages contenant uniquement des pièces jointes sont pris en charge. Les réponses par e-mail incluent les fichiers dans la limite de taille de l'e-mail et des liens de téléchargement pour le reste ; les e-mails de chat hors ligne incluent des liens vers les fichiers. Les liens envoyés par e-mail restent utilisables tant que la pièce jointe existe, pour que les destinataires puissent les ouvrir plus tard. Transférer l'e-mail partage l'accès à ces fichiers. Consultez emailDeliveryStatus pour les échecs de livraison.

Les lectures de messages autorisées incluent downloadUrl, downloadExpiresAt, aiStatus, aiDescription et aiExtractedText, ainsi que videoTranscripts pour les vidéos liées (Loom, Vimeo et autres). Les liens de téléchargement durent 15 minutes ; relisez le message pour obtenir des liens frais. Les nouveaux fichiers importés via l'API/MCP sont stockés en privé. Les anciennes pièces jointes restent publiques et sont marquées access=legacy_public : leur URL d'origine n'expire pas. Lire un message lance la lecture de ses images lorsque l'espace de travail dispose de Sonny AI. Les lectures d'images et les transcriptions vidéo se terminent peu après l'arrivée d'un message : tant qu'elles sont en cours, la réponse commence par readsInProgress, dont nextStep indique l'appel exact à effectuer. Passez waitSeconds (jusqu'à 30) pour les attendre en une seule requête. Les messages du widget destinés aux clients et les messages en temps réel n'incluent jamais d'extraction ni de transcription.