> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Lister les conversations

> Listez toutes les conversations de l'utilisateur authentifié avec filtrage et pagination par curseur

<Warning>
  **API Famulor 1.0 (héritée).** Cette page concerne uniquement Famulor 1.0 (`app.famulor.de`) et est conservée pour la compatibilité. Pour la plateforme actuelle, consultez la [référence API Famulor 2.0](/fr/api-reference/introduction).
</Warning>

Ce point de terminaison retourne une liste paginée par curseur des conversations appartenant aux assistants de l'utilisateur authentifié. Utilisez-le pour consulter l'historique des conversations, filtrer par type, ou intégrer avec votre CRM.

<Note>
  Ce point de terminaison utilise une pagination par curseur pour de meilleures performances avec de gros volumes de données. Utilisez `next_cursor` et `prev_cursor` pour naviguer entre les pages.
</Note>

### Paramètres de requête

<ParamField query="type" type="string" optional>
  Filtre les conversations par type. Valeurs possibles : `test`, `widget`, `whatsapp`, `api`
</ParamField>

<ParamField query="assistant_id" type="integer" optional>
  Filtre les conversations par ID d'assistant (doit appartenir à l'utilisateur authentifié)
</ParamField>

<ParamField query="customer_phone" type="string" optional>
  Filtre les conversations par numéro de téléphone du client (correspondance exacte). Utile pour retrouver toutes les conversations avec un client spécifique.
</ParamField>

<ParamField query="whatsapp_sender_phone" type="string" optional>
  Filtre les conversations par numéro de téléphone de l'expéditeur WhatsApp (correspondance exacte). Utile pour retrouver toutes les conversations d'un numéro WhatsApp Business spécifique.
</ParamField>

<ParamField query="external_identifier" type="string" optional>
  Filtre les conversations par identifiant externe. Utile pour retrouver les conversations liées à des enregistrements de votre système externe.
</ParamField>

<ParamField query="per_page" type="integer" optional>
  Nombre de conversations par page (1-100, par défaut : 15)
</ParamField>

<ParamField query="cursor" type="string" optional>
  Curseur de pagination. Utilisez `next_cursor` ou `prev_cursor` d'une réponse précédente.
</ParamField>

### Champs de réponse

<ResponseField name="data" type="array">
  <Expandable title="Propriétés">
    <ResponseField name="id" type="string">
      L'UUID unique de la conversation
    </ResponseField>

    <ResponseField name="assistant_id" type="string">
      L'UUID de l'assistant gérant cette conversation
    </ResponseField>

    <ResponseField name="assistant_name" type="string">
      Le nom de l'assistant gérant cette conversation
    </ResponseField>

    <ResponseField name="type" type="string">
      Le type de conversation : `test`, `widget`, `whatsapp` ou `api`
    </ResponseField>

    <ResponseField name="variables" type="object">
      Variables personnalisées associées à la conversation (paires clé-valeur)
    </ResponseField>

    <ResponseField name="external_identifier" type="string">
      L'identifiant de votre système externe pour cette conversation. Présent uniquement pour les conversations de type `api` si un identifiant externe a été défini.
    </ResponseField>

    <ResponseField name="message_count" type="integer">
      Nombre total de messages dans la conversation
    </ResponseField>

    <ResponseField name="total_cost" type="number">
      Le coût total de la conversation en USD
    </ResponseField>

    <ResponseField name="ai_enabled" type="boolean">
      Indique si les réponses IA sont activées pour cette conversation
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Date et heure de création de la conversation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Date et heure de dernière mise à jour de la conversation
    </ResponseField>

    <ResponseField name="whatsapp_sender" type="object">
      Informations sur l'expéditeur WhatsApp Business. Présent uniquement pour les conversations de type `whatsapp`.

      <Expandable title="Propriétés de whatsapp_sender">
        <ResponseField name="name" type="string">
          Nom d'affichage de l'expéditeur WhatsApp (nom de l'entreprise)
        </ResponseField>

        <ResponseField name="phone" type="string">
          Numéro de téléphone de l'expéditeur WhatsApp
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="customer" type="object">
      Informations sur le client. Présent uniquement pour les conversations de type `whatsapp`.

      <Expandable title="Propriétés de customer">
        <ResponseField name="name" type="string">
          Nom du client (si disponible)
        </ResponseField>

        <ResponseField name="phone" type="string">
          Numéro de téléphone du client
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="next_cursor" type="string">
  Curseur pour récupérer la page de résultats suivante. Transmettez-le comme paramètre `cursor` dans votre prochaine requête. `null` s'il n'y a pas d'autres résultats.
</ResponseField>

<ResponseField name="prev_cursor" type="string">
  Curseur pour récupérer la page de résultats précédente. `null` s'il s'agit de la première page.
</ResponseField>

<ResponseField name="per_page" type="integer">
  Nombre d'éléments par page
</ResponseField>

<RequestExample>
  ```bash cURL theme={null} theme={null}
  curl -X GET "https://app.famulor.de/api/user/conversations?type=whatsapp&per_page=10" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash Filter by customer phone theme={null} theme={null}
  curl -X GET "https://app.famulor.de/api/user/conversations?customer_phone=+49123456789" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash Filter by WhatsApp sender phone theme={null} theme={null}
  curl -X GET "https://app.famulor.de/api/user/conversations?whatsapp_sender_phone=+49987654321" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null} theme={null}
  const response = await fetch(
    'https://app.famulor.de/api/user/conversations?type=whatsapp&per_page=10',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();

  // Fetch next page using cursor
  if (data.next_cursor) {
    const nextPage = await fetch(
      `https://app.famulor.de/api/user/conversations?cursor=${data.next_cursor}`,
      { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
    );
  }
  ```

  ```python Python theme={null} theme={null}
  import requests

  response = requests.get(
      'https://app.famulor.de/api/user/conversations',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={
          'type': 'whatsapp',
          'per_page': 10
      }
  )

  data = response.json()

  # Fetch next page using cursor
  if data.get('next_cursor'):
      next_response = requests.get(
          'https://app.famulor.de/api/user/conversations',
          headers={'Authorization': 'Bearer YOUR_API_KEY'},
          params={'cursor': data['next_cursor']}
      )
  ```
</RequestExample>

<ResponseExample>
  ```json 200 response theme={null} theme={null}
  {
    "data": [
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "assistant_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
        "assistant_name": "Support Assistant",
        "type": "widget",
        "variables": {
          "user_name": "Jane Smith",
          "plan": "premium"
        },
        "message_count": 12,
        "total_cost": 0.0045,
        "ai_enabled": true,
        "created_at": "2025-01-25 14:30:00",
        "updated_at": "2025-01-25 14:45:22"
      },
      {
        "id": "8d0f7780-8536-51ef-055c-f18fd2g01bf8",
        "assistant_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
        "assistant_name": "Support Assistant",
        "type": "whatsapp",
        "variables": null,
        "message_count": 8,
        "total_cost": 0.0032,
        "ai_enabled": true,
        "created_at": "2025-01-25 10:15:00",
        "updated_at": "2025-01-25 10:28:45",
        "whatsapp_sender": {
          "name": "Acme Corp Support",
          "phone": "+14155551234"
        },
        "customer": {
          "name": "John Doe",
          "phone": "+14155559876"
        }
      },
      {
        "id": "9e1g8891-9647-62fg-166d-g29ge3h12cg9",
        "assistant_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
        "assistant_name": "Support Assistant",
        "type": "api",
        "variables": {
          "lead_id": "12345",
          "source": "website"
        },
        "external_identifier": "crm-lead-12345",
        "message_count": 5,
        "total_cost": 0.0021,
        "ai_enabled": true,
        "created_at": "2025-01-25 09:00:00",
        "updated_at": "2025-01-25 09:15:30"
      }
    ],
    "path": "https://app.famulor.de/api/user/conversations",
    "per_page": 15,
    "next_cursor": "eyJpZCI6MTAwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
    "prev_cursor": null
  }
  ```
</ResponseExample>

## Types de conversation

| Type       | Description                                                                 |
| ---------- | --------------------------------------------------------------------------- |
| `test`     | Conversations de test internes issues de l'interface de test de l'assistant |
| `widget`   | Conversations issues du widget de chat web                                  |
| `whatsapp` | Conversations WhatsApp Business                                             |
| `api`      | Conversations créées via l'API                                              |

## Paramètres de filtrage

Tous les paramètres de filtrage utilisent des colonnes indexées pour une exécution efficace des requêtes :

| Paramètre               | Description                               | Cas d'usage                                                  |
| ----------------------- | ----------------------------------------- | ------------------------------------------------------------ |
| `type`                  | Filtrer par type de conversation          | Récupérer uniquement les conversations WhatsApp ou Widget    |
| `assistant_id`          | Filtrer par assistant spécifique          | Afficher les conversations d'un seul assistant               |
| `customer_phone`        | Filtrer par numéro de téléphone du client | Retrouver toutes les conversations avec un client spécifique |
| `whatsapp_sender_phone` | Filtrer par numéro d'expéditeur WhatsApp  | Retrouver toutes les conversations d'un numéro professionnel |
| `external_identifier`   | Filtrer par votre ID externe              | Lier les conversations à vos enregistrements CRM             |

## Détails des conversations WhatsApp

Pour les conversations WhatsApp, la réponse inclut des champs supplémentaires :

* **whatsapp\_sender** : le numéro WhatsApp Business qui a mené la conversation (nom et numéro de téléphone de votre expéditeur WhatsApp)
* **customer** : le client qui a initié ou reçu la conversation (son nom et son numéro de téléphone)

Ces champs sont présents uniquement pour les conversations de type `whatsapp` et permettent d'identifier les parties impliquées lors de l'intégration avec votre CRM ou vos systèmes de support.

## Détails des conversations API

Pour les conversations créées via l'API, vous pouvez définir un `external_identifier` lors de la création de la conversation. Cet identifiant est retourné dans la réponse et peut être utilisé pour :

* Lier les conversations à vos leads ou contacts CRM
* Suivre les conversations à travers vos systèmes internes
* Filtrer les conversations par votre référence externe

## Cas d'usage

* **Tableau de bord analytique** : afficher les métriques et tendances des conversations
* **Intégration CRM** : synchroniser les données de conversation avec votre base clients via `external_identifier`
* **Recherche client** : retrouver toutes les conversations avec un client particulier via `customer_phone`
* **Contrôle qualité** : examiner le volume de conversations par type et par assistant
* **Audit de facturation** : suivre les coûts de conversation au sein de votre organisation

<Tip>
  Voir aussi : [Introduction](/fr/api-v1/introduction) et [Guide d'authentification](/fr/api-v1/authentication), et [Exemples d'intégration API](/fr/api-v1/introduction).
</Tip>