Gérer une conversation avec l'API Intercom
Ferme, met en attente, rouvre ou assigne une conversation. close exige type admin ; snoozed exige snoozed_until ; assignment exige type et assignee_id, et une conversation peut avoir un admin et une équipe assignés en même temps. Assigner une conversation fermée la rouvre, sauf si skip_reopen est true.
- Identifiant
- intercom_manage_conversation
L'appel
POST https://connect.reportei.com/api/tools/intercom_manage_conversation/execute
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Content-Type: application/json
Accept: application/json
{
"customer_toolkit": "<connection UUID>",
"arguments": {
"conversation_id": "<conversation_id>",
"message_type": "close",
"admin_id": "<admin_id>"
}
}Votre système envoie l'id de la connexion de votre client et les arguments de la tool. Les headers sont les mêmes que pour toute l'API Connect : le token de votre produit et celui de votre client.
Paramètres
Les descriptions des paramètres suivent la documentation officielle de l'app, en anglais.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| conversation_id | string | Oui | Id of the conversation, from List conversations or Search conversations. |
| message_type | string | Oui | close, snoozed (reopens at snoozed_until), open (reopens a closed or snoozed conversation) or assignment.Valeurs : close, snoozed, open, assignment |
| admin_id | string | Oui | Id of the teammate performing the action, from List admins. |
| type | string | Non | admin with close. With assignment, admin or team, saying what assignee_id is.Valeurs : admin, team |
| assignee_id | string | Non | With assignment: id of the teammate, from List admins, or of the team, from List teams, matching type. 0 leaves the conversation unassigned. |
| snoozed_until | integer | Non | With snoozed: when the conversation reopens, as a Unix timestamp in seconds. |
| body | string | Non | Optional message left in the conversation with close or assignment. |
| skip_reopen | boolean | Non | With assignment: true keeps a closed conversation closed. |
Connexions possibles
Votre client connecte son compte Intercom une seule fois, avec l'un des modes ci-dessous. La même connexion sert à toutes les tools du toolkit.
OAuth avec l'app de votre produit
Vous enregistrez une fois l'app OAuth de votre produit, avec POST /api/merchants/credentials/intercom, et votre client autorise le compte sur un écran de consentement. Connect renouvelle le token avant son expiration.
La réponse
En cas de succès, Connect conserve le statut et le corps de la réponse de l'app. Les erreurs HTTP renvoyées par l'app utilisent l'objet {error, api_error} ; l'authentification ou la validation peuvent échouer avant l'exécution. Le header X-Toolkit-Execution-Id identifie l'exécution enregistrée, consultable avec GET /api/tools/executions/{uuid}.
Prête pour les agents IA
L'input de cette tool est un JSON Schema, disponible via GET /api/tools/intercom_manage_conversation. Il devient la définition de tool de votre agent sans conversion.
Autres tools Intercom
- Lister les contactsGETListe les contacts du workspace, utilisateurs et leads, 10 par page par défaut. La page suivante vient de pages.next.starting_after dans la réponse ; sans lui, c'est la dernière page. Les contacts fusionnés n'apparaissent pas.
- Rechercher des contactsPOSTRecherche des contacts par leurs attributs, par exemple par email, role ou un attribut personnalisé. Les timestamps sont en secondes Unix UTC. Renvoie total_count et data, 50 par page par défaut, et la page suivante vient de pages.next.starting_after. Un contact créé ces dernières minutes peut ne pas encore apparaître.
- Obtenir un contactGETRenvoie un contact avec role, email, téléphone, nom, owner_id, custom_attributes, tags, entreprises et localisation. Un contact fusionné dans un autre renvoie 410.
- Créer un contactPOSTCrée un contact, utilisateur ou lead. Envoyez au moins un parmi email, external_id ou role. Chaque attribut personnalisé envoyé doit déjà exister dans le workspace, sinon Intercom refuse le contact.
- Mettre à jour un contactPUTMet à jour un contact : envoyez seulement les champs à modifier. Un utilisateur ne peut pas devenir lead. Chaque attribut personnalisé envoyé doit déjà exister dans le workspace.
- Lister les conversationsGETListe les conversations du workspace, 20 par page par défaut. La page suivante vient de pages.next.starting_after dans la réponse ; sans lui, c'est la dernière page. Obtenir une conversation renvoie toutes les parties d'une conversation.
- Rechercher des conversationsPOSTRecherche des conversations par leurs attributs, par exemple les ouvertes assignées à un membre de l'équipe ou à une équipe. Les timestamps sont en secondes Unix. Renvoie total_count et conversations, 20 par page par défaut, et la page suivante vient de pages.next.starting_after.
- Obtenir une conversationGETRenvoie une conversation avec ses parties (messages, notes et actions), jusqu'aux 500 plus récentes, plus state, assignés, contacts et tags.
Toolkits de la même catégorie
Voir les 100 toolkitsVoyez Connect appliqué à votre produit.
Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.
