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

# Cas d'utilisation courants

> Exemples d'utilisation de l'API Allo pour repondre a des questions business et automatiser des workflows

## Pour commencer

<AccordionGroup>
  <Accordion title="Decouvrir ce que votre API key peut faire">
    Commencez toujours par appeler l'endpoint de capacites :

    ```bash theme={null}
    GET /v2/api/me
    ```

    La reponse liste vos scopes, les endpoints disponibles, votre equipe et les rate limits. Utilisez le tableau `endpoints` pour savoir quels appels API vous pouvez effectuer.
  </Accordion>
</AccordionGroup>

## Synchronisation des donnees

<AccordionGroup>
  <Accordion title="Synchronisation CRM (incrementale)">
    Recuperez uniquement les nouvelles activites depuis votre derniere synchronisation — pas besoin de tout re-telecharger.

    ```bash theme={null}
    GET /v2/api/conversations?allo_number=%2B14155550100&last_activity_since=2026-04-20T10:00:00Z
    ```

    Stockez le timestamp `last_activity` de la reponse et utilisez-le comme `last_activity_since` lors de la prochaine synchronisation.
  </Accordion>

  <Accordion title="Exporter tous les appels sortants de ce trimestre">
    Parcourez tous les resultats page par page :

    ```bash theme={null}
    POST /v2/api/conversations/items/search
    {
      "date": { "from": "2026-01-01", "to": "2026-03-31" },
      "direction": "OUTBOUND",
      "type": "CALL",
      "page": 1,
      "size": 100
    }
    ```

    Incrementez `page` jusqu'a ce que `pagination.has_more` soit `false`.
  </Accordion>
</AccordionGroup>

## Recherche dans les conversations

<AccordionGroup>
  <Accordion title="Trouver les appels ou les clients ont mentionne des problemes de facturation">
    Recherche par mots-cles dans toutes les transcriptions et resumes d'appels :

    ```bash theme={null}
    POST /v2/api/conversations/items/search
    {
      "search": "billing issues",
      "type": "CALL",
      "sort": "RELEVANCE"
    }
    ```

    Les termes de recherche sont combines avec AND et utilisent la correspondance par prefixe — `"bill"` correspond a "billing", "billed", etc.
  </Accordion>

  <Accordion title="Rechercher ce que nous avons discute des remboursements avec un contact">
    ```bash theme={null}
    POST /v2/api/conversations/items/search
    {
      "contact_number": "+14155551234",
      "search": "refunds",
      "sort": "RELEVANCE"
    }
    ```
  </Accordion>

  <Accordion title="Afficher toutes les interactions avec un contact">
    ```bash theme={null}
    POST /v2/api/conversations/items/search
    {
      "contact_number": "+14155551234"
    }
    ```

    Retourne la timeline complete des appels et SMS avec un contact, incluant les contacts associes, l'entreprise et les deals.
  </Accordion>

  <Accordion title="Obtenir le contexte complet d'un appel specifique">
    ```bash theme={null}
    GET /v2/api/conversations/items/cll-abc123?extend=transcript
    ```

    Retourne l'appel avec le resume, les tags, l'URL d'enregistrement et la transcription complete. `transcript` est la seule valeur extend supportee.
  </Accordion>

  <Accordion title="Combien d'appels ont ete manques la semaine derniere ?">
    Utilisez l'endpoint de recherche avec `size=1` pour obtenir uniquement le total :

    ```bash theme={null}
    POST /v2/api/conversations/items/search
    {
      "date": { "from": "2026-04-14", "to": "2026-04-21" },
      "result": "VOICEMAIL",
      "type": "CALL",
      "size": 1
    }
    ```

    Lisez `pagination.total_count` dans la reponse — pas besoin de recuperer tous les resultats.
  </Accordion>

  <Accordion title="Afficher les leads qualifies des appels a froid ce mois-ci">
    D'abord, verifiez quels tags existent :

    ```bash theme={null}
    GET /v2/api/tags
    ```

    Puis filtrez les conversations par tag :

    ```bash theme={null}
    POST /v2/api/conversations/items/search
    {
      "date": { "from": "2026-04-01", "to": "2026-04-21" },
      "tags": ["qualified"],
      "direction": "OUTBOUND"
    }
    ```
  </Accordion>

  <Accordion title="Trouver toutes les conversations non lues sur une ligne">
    ```bash theme={null}
    GET /v2/api/conversations?allo_number=%2B14155550100&unread=true
    ```

    Le parametre `allo_number` est requis. Listez vos numeros avec `GET /v2/api/numbers` pour trouver le bon.
  </Accordion>
</AccordionGroup>

## Actions

<AccordionGroup>
  <Accordion title="Taguer un appel puis trouver tous les appels avec ce tag">
    ```bash theme={null}
    # 1. Taguer l'appel
    POST /v2/api/conversations/items/cll-abc123/tags
    { "tags": ["qualified"] }

    # 2. Trouver tous les appels avec ce tag
    POST /v2/api/conversations/items/search
    { "tags": ["qualified"] }
    ```

    Ajouter un tag qui existe deja retourne `409 TAG_ALREADY_EXISTS` — aucun doublon n'est cree.
  </Accordion>

  <Accordion title="Marquer une conversation comme lue">
    ```bash theme={null}
    PUT /v2/api/conversations/%2B14155551234/action
    { "action": "READ" }
    ```

    Pour cibler un numero Allo specifique :

    ```bash theme={null}
    PUT /v2/api/conversations/%2B14155551234/action
    { "action": "READ", "allo_number": "+14155550100" }
    ```

    Toutes les actions sont idempotentes — appeler `READ` sur une conversation deja lue est sans effet.
  </Accordion>

  <Accordion title="Archiver une conversation">
    ```bash theme={null}
    PUT /v2/api/conversations/%2B14155551234/action
    { "action": "ARCHIVE" }
    ```

    Cela archive le contact et marque tous les elements comme lus.
  </Accordion>

  <Accordion title="Envoyer un SMS de suivi">
    L'envoi de SMS utilise l'endpoint de l'API v1 :

    ```bash theme={null}
    POST /v1/api/sms
    {
      "to": "+14155551234",
      "allo_number": "+14155550100",
      "content": "Thanks for your call! Let me know if you have any other questions."
    }
    ```

    Necessite le scope `SMS_SEND`. Voir [Envoyer un SMS](/fr/v2/api-reference/sms/send-sms) pour les details.
  </Accordion>
</AccordionGroup>

## Analytique et reporting

<AccordionGroup>
  <Accordion title="Quelle est ma performance en appels a froid cette semaine par rapport a la semaine derniere ?">
    ```bash theme={null}
    # 1. Obtenir le funnel sortant avec comparaison semaine par semaine
    POST /v2/api/analytics/outbound
    {
      "date": { "from": "2026-04-14", "to": "2026-04-21" },
      "compare_date": { "from": "2026-04-07", "to": "2026-04-14" },
      "tags": ["meeting_booked"],
      "granularity": "DAY"
    }
    ```

    La reponse inclut le funnel complet (appels, connectes, conversations, conversions) avec l'evolution par rapport a la semaine precedente, la serie temporelle quotidienne, la heatmap et le classement.

    ```bash theme={null}
    # 2. Explorer les appels convertis (utiliser extend=items)
    POST /v2/api/analytics/outbound
    {
      "date": { "from": "2026-04-14", "to": "2026-04-21" },
      "tags": ["meeting_booked"],
      "granularity": "DAY",
      "extend": "items",
      "stage": "CONVERSION"
    }

    # 3. Obtenir les details complets (resume, transcription, tags)
    POST /v2/api/conversations/items/batch
    { "ids": ["cll-abc123", "cll-def456"] }
    ```
  </Accordion>

  <Accordion title="Obtenir la performance de l'equipe du mois dernier">
    ```bash theme={null}
    POST /v2/api/analytics/overview
    {
      "date": { "from": "2026-03-01", "to": "2026-03-31" },
      "compare_date": { "from": "2026-02-01", "to": "2026-02-28" }
    }
    ```

    Retourne le total des appels, le temps de conversation, le taux de reponse et le detail par utilisateur — le tout avec l'evolution par rapport a la periode de comparaison.
  </Accordion>

  <Accordion title="Comparer la performance de deux commerciaux">
    ```bash theme={null}
    POST /v2/api/analytics/overview
    {
      "date": { "from": "2026-04-01", "to": "2026-04-21" },
      "compare_date": { "from": "2026-03-01", "to": "2026-03-31" },
      "user_ids": ["usr-abc123", "usr-def456"]
    }
    ```

    Le detail dans la reponse inclut les deux utilisateurs avec leurs metriques individuelles et l'evolution par rapport a la periode de comparaison.
  </Accordion>

  <Accordion title="Performance des appels a froid pour une ligne specifique">
    ```bash theme={null}
    POST /v2/api/analytics/outbound
    {
      "date": { "from": "2026-04-01", "to": "2026-04-21" },
      "allo_numbers": ["+14155550100"],
      "tags": ["meeting_booked"],
      "granularity": "WEEK"
    }
    ```
  </Accordion>
</AccordionGroup>

## Equipe et configuration

<AccordionGroup>
  <Accordion title="Resoudre le nom d'un membre de l'equipe pour filtrer les conversations">
    ```bash theme={null}
    # 1. Trouver l'utilisateur
    GET /v2/api/users

    # 2. Utiliser son ID pour filtrer
    POST /v2/api/conversations/items/search
    { "user_id": "usr-abc123", "type": "CALL" }
    ```
  </Accordion>

  <Accordion title="Trouver quel numero Allo utiliser pour un pays">
    ```bash theme={null}
    GET /v2/api/numbers
    ```

    Filtrez la reponse par `country` et verifiez `capabilities` pour trouver un numero qui supporte le canal dont vous avez besoin (VOICE, SMS, MMS).
  </Accordion>

  <Accordion title="Lister tous les tags disponibles avant de creer un rapport">
    ```bash theme={null}
    GET /v2/api/tags
    ```

    Utilisez les noms de tags dans les filtres de recherche de conversations ou comme tags de conversion dans les analytiques.
  </Accordion>
</AccordionGroup>