> ## 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.

# Vue d'ensemble

> Lisez et modifiez le réceptionniste IA d'une ligne Allo : prompt, voix, horaires, règles de transfert, agendas et connaissances

Chaque ligne Allo a un réceptionniste IA. Ces endpoints lisent toute sa configuration en un appel et en modifient chaque partie : informations sur l'activité, voix et langue, prompt avec lequel il répond, ce qu'il a le droit de faire pendant un appel, horaires d'ouverture, règles de transfert, agendas sur lesquels il réserve, et ce qu'il sait de votre activité.

<Note>
  **Scopes requis :** `AGENTS_READ` pour lire, `AGENTS_WRITE` pour écrire. Créez une clé avec ces scopes dans [Paramètres > API](https://web.withallo.com/settings/api).
</Note>

<Card title="Laissez le MCP Allo le configurer pour vous" icon="https://mintcdn.com/themobilefirstcompany/I-AZGjY8JNMbLMCH/media/integrations/MCP.svg?fit=max&auto=format&n=I-AZGjY8JNMbLMCH&q=85&s=f1ec6f445ca7aa3bb3b4421b863fd105" href="/fr/integrations/mcp" width="24" height="24" data-path="media/integrations/MCP.svg">
  Connectez le MCP Allo à votre assistant IA : configurer un réceptionniste devient une conversation sur votre activité au lieu d'une série de requêtes à écrire. Ce sont les mêmes endpoints que cette page, avec une bien meilleure expérience.
</Card>

## Comment la configuration est organisée

`GET /v2/api/numbers/{number}/agent` répond à la question « comment ce réceptionniste est-il configuré ? » en une réponse, découpée en sept blocs.

| Bloc             | Ce qu'il contient                                                                                                                                                                  |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent`          | Qui est le réceptionniste : nom, informations sur l'activité, langue, voix, message d'accueil et de fin, ton, longueur des réponses. Ainsi que son `status`, en lecture seule ici. |
| `prompt`         | Ce qu'il cherche à obtenir et comment il se comporte, en six sections. Modifié par son propre endpoint.                                                                            |
| `capabilities`   | Ce qu'il a le droit de faire pendant un appel : `SCHEDULING`, `CALL_TRANSFER`, `WARM_TRANSFER`.                                                                                    |
| `business_hours` | Les horaires d'ouverture, jour par jour, dans le fuseau que vous définissez.                                                                                                       |
| `transfer_rules` | Les motifs pour lesquels il transfère un appel, et la destination de chacun.                                                                                                       |
| `scheduling`     | Les agendas sur lesquels il réserve, avec les types d'événement sélectionnés pour chacun.                                                                                          |
| `knowledge`      | Les informations à partir desquelles il répond : texte libre, sites web analysés, documents importés.                                                                              |

## Deux règles de fusion

`PATCH /v2/api/numbers/{number}/agent` applique deux règles différentes, et les confondre est la seule erreur qui fait perdre de la configuration :

* **Les valeurs simples sont fusionnées.** `name`, les informations sur l'activité, `language`, `voice_id`, `greeting_message`, `closing_message`, `tone_of_voice`, `answer_type` et `knowledge.text` gardent leur valeur actuelle si vous les omettez.
* **Les collections sont remplacées.** `capabilities`, `business_hours`, `transfer_rules` et `scheduling.calendars` sont des ensembles complets. Envoyez-en un et il remplace ce qui était configuré, omettez-le et il reste intact.

Ajouter une seule règle de transfert suppose donc de lire les règles existantes et de les renvoyer avec la nouvelle. Même chose pour les capacités : une capacité absente de la map est désactivée, pas conservée.

Un champ que l'API ne connaît pas est refusé avec `400 UNKNOWN_FIELD` plutôt qu'ignoré, pour qu'une faute de frappe ne réponde jamais `200 OK`.

## Écrire le prompt

Le prompt a son propre endpoint parce qu'il n'est valide qu'entier. `objective`, `personality` et `behaviors` sont obligatoires, et chaque écriture régénère le prompt avec lequel le réceptionniste répond : [Définir le prompt](/fr/v2/api-reference/agent/set-agent-prompt) remplace donc la liste complète des sections.

Les informations factuelles sur l'activité vont dans `knowledge`, pas dans le prompt. Tarifs, horaires, règles et questions fréquentes changent souvent et doivent se trouver là où le réceptionniste va les chercher.

## Ce que cette API ne fait pas

* **Importer des documents.** Les fichiers s'importent dans l'app Allo. Ici, vous les listez et les supprimez.
* **Connecter un agenda.** C'est un flux OAuth, réalisé dans l'app Allo. Ici, vous listez ce qui est connecté et choisissez sur quoi le réceptionniste réserve.
* **Créer un réceptionniste.** Une ligne en a un dès qu'elle existe.

## Endpoints

<CardGroup cols={2}>
  <Card title="Lire la configuration" href="/fr/v2/api-reference/agent/get-agent">
    Toute la configuration du réceptionniste d'une ligne, en un appel
  </Card>

  <Card title="Modifier la configuration" href="/fr/v2/api-reference/agent/update-agent">
    Informations, voix, capacités, horaires, règles de transfert, agendas, texte de connaissances
  </Card>

  <Card title="Définir le prompt" href="/fr/v2/api-reference/agent/set-agent-prompt">
    Remplacer les sections du prompt avec lequel le réceptionniste répond
  </Card>

  <Card title="Activer ou désactiver" href="/fr/v2/api-reference/agent/set-agent-status">
    Mettre le réceptionniste sur la ligne, ou renvoyer les appels vers votre téléphone professionnel
  </Card>

  <Card title="Ajouter un site web" href="/fr/v2/api-reference/agent/add-website-knowledge">
    Analyser une page pour que le réceptionniste puisse en tirer ses réponses
  </Card>

  <Card title="Activer ou désactiver un site" href="/fr/v2/api-reference/agent/update-website-knowledge">
    Désactiver une entrée sans perdre son contenu analysé
  </Card>

  <Card title="Supprimer un site web" href="/fr/v2/api-reference/agent/delete-website-knowledge">
    Retirer une page analysée des connaissances du réceptionniste
  </Card>

  <Card title="Supprimer un document" href="/fr/v2/api-reference/agent/delete-file-knowledge">
    Retirer un document importé des connaissances du réceptionniste
  </Card>

  <Card title="Lister les agendas" href="/fr/v2/api-reference/agent/list-calendars">
    Les agendas connectés à votre espace de travail
  </Card>

  <Card title="Lire un agenda" href="/fr/v2/api-reference/agent/get-calendar">
    Un agenda avec les types d'événement proposés par son fournisseur
  </Card>

  <Card title="Lister les voix" href="/fr/v2/api-reference/agent/list-voices">
    Les voix avec lesquelles un réceptionniste peut parler
  </Card>
</CardGroup>