# Rechercher des éléments de conversation

> Cet endpoint est paginé. Utilisez page et size dans le corps de la requête pour contrôler les résultats. Voir Pagination.

`POST /v2/api/conversations/items/search`

<Note>
**Scope requis :** `CONVERSATIONS_READ`
</Note>

Cet endpoint est paginé. Utilisez `page` et `size` dans le corps de la requête pour contrôler les résultats. Voir [Pagination](/fr/docs/guides/pagination).

## Appels sortants tombés sur une messagerie

Quand un appel sortant est décroché par le répondeur du contact, `result` reste `ANSWERED`, car l'opérateur considère qu'un répondeur qui décroche est une réponse. Deux champs portent l'information à la place :

| Champ | Signification |
|-------|---------------|
| `detected_outbound_voicemail` | Un répondeur a décroché (détection automatique ou transcription) |
| `voicemail_left` | Un message a effectivement été laissé après le bip |

Les deux sont indépendants : `detected_outbound_voicemail: true` avec `voicemail_left: false` signifie que l'appel est tombé sur une messagerie et que l'appelant a raccroché sans laisser de message. L'un ou l'autre peut valoir `null` quand le signal n'a jamais été déterminé. `null` n'est pas équivalent à `false`.

<Note>
Filtrer sur `result: "VOICEMAIL"` ne renvoie que les messageries **entrantes**. Pour trouver les appels sortants tombés sur une messagerie, cherchez avec `direction: "OUTBOUND"` puis filtrez les éléments renvoyés sur `detected_outbound_voicemail`. Il n'existe pas de filtre de requête pour ce champ.
</Note>

## Comportement de la recherche

Le champ `search` est une **recherche par mots-clés**, pas une requête en langage naturel. Extrayez les mots-clés de la question de l'utilisateur avant de les transmettre.

| L'utilisateur demande | Valeur de `search` |
|-----------|---------------|
| "Trouver les appels où les clients se sont plaints de la facturation" | `"billing complaint"` |
| "Qu'avons-nous discuté à propos de la politique de remboursement ?" | `"refund policy"` |
| "Montrer les conversations mentionnant la tarification entreprise" | `"enterprise pricing"` |

**Fonctionnement de la correspondance :**

- Les termes sont combinés avec **AND** : `"billing refund"` correspond aux éléments contenant **les deux** mots
- La **correspondance par préfixe** est utilisée : `"bill"` correspond à "billing", "billed", etc.
- La recherche porte sur : les transcriptions d'appels, les résumés d'appels et le contenu des messages SMS
- Utilisez `sort=RELEVANCE` pour classer les résultats par qualité de correspondance plutôt que par date

## Filtrer par type

| `type` | Renvoie |
|--------|---------|
| `ALL` (par défaut) | Les appels et les messages |
| `CALL` | Uniquement les appels |
| `SMS` | Les messages, fax inclus |
| `FAX` | Uniquement les fax |

Un fax est renvoyé comme un élément de `type` `SMS` avec `message_type` `FAX`. Voir [Fax](/fr/docs/conversations/get-item#fax).

## Notes sur les champs

| Champ | Null quand |
|-------|-----------|
| `summary` | Éléments SMS, ou appels dont le résumé IA n'est pas encore disponible |
| `duration` | Éléments SMS (s'applique uniquement aux appels) |
| `result` | Éléments SMS (s'applique uniquement aux appels) |
| `detected_outbound_voicemail` | Appels entrants, éléments SMS, ou appels sortants sans détection |
| `voicemail_left` | Appels entrants, éléments SMS, ou appels sortants pour lesquels ce n'est pas déterminé |
| `recording_url` | Enregistrement désactivé, appel sans réponse, éléments SMS, ou comptes vendus sous la marque d'un partenaire en marque blanche |
| `recording_download_url` | Comptes qui n'ont pas été créés par un partenaire, appels d'une équipe HIPAA, appels sans enregistrement, utilisateur de la clé qui ne peut pas écouter l'enregistrement, ou éléments SMS |
| `recording_download_expires_at` | Mêmes cas que `recording_download_url` |
| `recording_duration` | Enregistrement désactivé, appel sans réponse, ou éléments SMS |
| `transcript` | Non demandé via `extend=transcript`, ou éléments SMS |
| `content` | Éléments d'appel (s'applique uniquement aux SMS) |
| `status` | Éléments d'appel (s'applique uniquement aux SMS) |
| `attachments` | Éléments d'appel. Un SMS sans photo ni fichier renvoie un tableau vide. |
| `page_count` | Appels, messages qui ne sont pas des fax, ou fax dont le nombre de pages n'est pas encore connu |
| `tags` | Éléments SMS (les tags s'appliquent uniquement aux appels) |

`duration` est la durée totale de l'appel en secondes, sonnerie incluse. `recording_duration` est la durée de conversation, celle affichée dans l'application Allo pour les appels enregistrés. Pour les appels sans enregistrement, l'application utilise `duration`.

`recording_download_url` télécharge le fichier de l'enregistrement sans connexion à Allo, pendant 48 heures. Il n'est renvoyé que sur les lignes des comptes créés par un partenaire, jamais pour un appel HIPAA. Voir [Liens vers l'enregistrement](/fr/docs/conversations/get-item#liens-vers-lenregistrement).

`attachments` liste les photos et autres fichiers d'un MMS, chacun avec un `download_url` valable 30 minutes. Voir [Fichiers joints aux MMS](/fr/docs/conversations/get-item#fichiers-joints-aux-mms).

### Paramètre extend

| Valeur | Effet |
|-------|--------|
| `transcript` | Inclure les transcriptions complètes des appels sur chaque élément |

Passer une valeur non prise en charge renvoie une erreur `400` avec le code `UNSUPPORTED_EXTEND_VALUE`.
