# Vue d'ensemble

> Intégrez les capacités de communication d'Allo dans vos applications

L'API Allo permet aux développeurs d'intégrer directement les capacités de communication d'Allo dans leurs applications. Créez des intégrations CRM, automatisez les workflows post-appel, synchronisez les données de conversation et alimentez des agents IA avec l'historique des appels et SMS de votre équipe.

## URL de base

Tous les endpoints vivent sous `https://api.withallo.com`. La version fait partie du chemin, pas d'un header.

| Préfixe | Utilisé par |
|---------|-------------|
| `/v2/api/...` | Tout sauf l'envoi de SMS : conversations, CRM, notes, fils de discussion, webhooks, numéros, utilisateurs, tags, templates de résumé, analytics, files du Power Dialer, réceptionniste IA, partenaires |
| `/v1/api/...` | L'envoi de SMS (`POST /v1/api/sms`) |

`POST /v2/api/sms` n'existe pas. Envoyer un SMS est un appel v1. Chemin complet et corps de requête : [Envoyer un SMS](/fr/docs/sms/send-sms).

## Commencez ici

Appelez `GET /v2/api/me` en premier. Cet endpoint renvoie les scopes de votre clé, la liste exacte des endpoints qu'elle peut atteindre, votre équipe et vos rate limits. Vous n'avez donc rien à deviner.

```bash
curl -X GET "https://api.withallo.com/v2/api/me" \
  -H "Authorization: Api-Key ak_live_your_key_here"
```

```json
{
  "data": {
    "api_key_id": "api-abc123def456",
    "scopes": ["CONVERSATIONS_READ", "PHONE_NUMBERS_READ", "TAGS_READ"],
    "endpoints": [
      { "method": "GET", "path": "/v2/api/conversations", "description": "List conversations grouped by contact number", "scope": "CONVERSATIONS_READ" }
    ],
    "team": { "id": "team-xyz789", "name": "Acme Sales" },
    "rate_limits": { "read_per_second": 20, "write_per_second": 5 }
  }
}
```

Toute API key valide peut appeler `/v2/api/me`. Aucun scope particulier n'est requis. Voir [Me](/fr/docs/users/me).

## Pour commencer

Avant d'utiliser l'API, assurez-vous d'avoir :

- Un abonnement Allo actif
- Les permissions Admin ou Manager sur votre workspace
- Une API key générée depuis [Paramètres > API](https://web.withallo.com/settings/api)

## Authentification

Les API keys sont générées depuis les paramètres de votre workspace. Incluez la clé dans le header `Authorization` de chaque requête :

```bash
curl -X GET "https://api.withallo.com/v2/api/conversations" \
  -H "Authorization: Api-Key ak_live_your_key_here"
```

Le schéma est `Api-Key`, pas `Bearer`. Stockez votre API key de manière sécurisée. Ne l'exposez pas dans du code côté client ou des dépôts publics.

## Guides

<CardGroup cols={2}>
  <Card title="Authentification" href="/fr/docs/guides/authentication">
    Configuration des API keys, scopes et correspondance scope/endpoint
  </Card>
  <Card title="Rate limits" href="/fr/docs/guides/rate-limits">
    Limites de requêtes et headers
  </Card>
  <Card title="Pagination" href="/fr/docs/guides/pagination">
    Résultats paginés avec totaux
  </Card>
  <Card title="Gestion des erreurs" href="/fr/docs/guides/error-handling">
    Format des erreurs et résolution
  </Card>
  <Card title="Codes d'erreur" href="/fr/docs/guides/error-codes">
    Chaque code d'erreur et quoi faire ensuite
  </Card>
  <Card title="Cas d'usage courants" href="/fr/docs/guides/common-use-cases">
    Des requêtes prêtes à l'emploi pour les tâches habituelles
  </Card>
</CardGroup>

## Ressources

| Ressource | Chemins principaux | Ce que ça couvre |
|-----------|--------------------|------------------|
| [Conversations](/fr/docs/conversations/overview) | `GET /v2/api/conversations`, `POST /v2/api/conversations/items/search` | Timeline unifiée appels et SMS, recherche par mots-clés dans les transcriptions et le contenu des messages |
| [SMS](/fr/docs/sms/overview) | `POST /v1/api/sms` | Envoi de SMS et MMS depuis vos numéros Allo ou vos sender IDs |
| [Fax](/fr/docs/fax/overview) | `POST /v2/api/faxes` | Envoi d'un PDF par fax depuis une ligne Allo avec le fax activé |
| [CRM](/fr/docs/crm/people-overview) | `/v2/api/crm/people`, `/v2/api/crm/companies`, `/v2/api/crm/deals`, `/v2/api/crm/attributes`, `/v2/api/crm/companies/attributes` | Créer, lire, modifier et rechercher des personnes, entreprises et deals, et gérer les champs personnalisés des contacts et les attributs d'entreprise |
| [Notes](/fr/docs/notes/overview) | `/v2/api/conversations/{contact_number}/notes`, `/v2/api/crm/people/{person_id}/notes` | Notes internes d'équipe sur les conversations et les fiches de personnes, avec @mentions |
| [Fils de discussion](/fr/docs/threads/overview) | `/v2/api/threads` | Fils de discussion d'équipe sur les appels, SMS et notes de conversation |
| [Webhooks](/fr/docs/webhooks/overview) | `/v2/api/webhooks` | Notifications d'événements en temps réel avec signatures HMAC et tentatives automatiques |
| [Numéros de téléphone](/fr/docs/phone-numbers/overview) | `GET /v2/api/numbers`, `/v2/api/numbers/{number}/call_flow` | Vos numéros Allo avec leurs capacités et les accès des membres, plus le routage des appels entrants |
| [Utilisateurs](/fr/docs/users/overview) | `GET /v2/api/users`, `GET /v2/api/me` | Liste de l'équipe avec rôles et numéros assignés, et capacités de l'API key |
| [Tags](/fr/docs/tags/overview) | `/v2/api/tags`, `/v2/api/conversations/items/{id}/tags` | Créer et lister les tags d'appels, les ajouter et les retirer sur les appels et SMS |
| [Templates de résumé](/fr/docs/summary-templates/overview) | `/v2/api/summary_templates` | Les templates qui structurent les résumés d'appel générés par l'IA |
| [Analytics](/fr/docs/analytics/overview) | `POST /v2/api/analytics/overview`, `POST /v2/api/analytics/outbound` | KPI d'équipe avec comparaison période sur période et détail par utilisateur |
| [Files du Power Dialer](/fr/docs/dialing-queues/overview) | `/v2/api/dialing-queues/current` | Consulter et remplir la file du Power Dialer |
| [Réceptionniste IA](/fr/docs/agent/overview) | `/v2/api/numbers/{number}/agent` | Configurer la réceptionniste, son prompt, ses connaissances et son statut on/off |
| [Partenaires](/fr/docs/partner/overview) | `/v2/api/partner/accounts`, `/v2/api/partner/credit` | Créer des comptes Allo, obtenir leur prix et les désactiver en tant que revendeur |
| [Marque blanche](/fr/docs/white-label/overview) | `/v2/api/partner/accounts/{id}/...`, `/v2/api/partner/esims` | Gérer les membres, les numéros, les eSIM, les suspensions et les Sender ID de vos comptes depuis votre propre produit |

## Rate limiting

Les rate limits varient selon le type de requête et s'appliquent par API key :

| Opération | Limite |
|-----------|--------|
| Requêtes de lecture (GET) | 20 requêtes/seconde |
| Requêtes d'écriture (POST, PUT, PATCH, DELETE) | 5 requêtes/seconde |

Chaque réponse inclut les headers `X-RateLimit-Limit`, `X-RateLimit-Remaining` et `X-RateLimit-Reset` pour que vous puissiez surveiller votre utilisation. Voir [Rate limits](/fr/docs/guides/rate-limits) pour les détails.

## Exemple rapide

Obtenez vos conversations récentes :

```bash
curl -X GET "https://api.withallo.com/v2/api/conversations?size=5" \
  -H "Authorization: Api-Key ak_live_your_key_here"
```

```json
{
  "data": [
    {
      "contact_number": "+14155551234",
      "contacts": [{ "id": "cnt-abc", "name": "Sarah Johnson", "company": { "name": "Acme Corp" } }],
      "last_activity": "2026-04-21T14:30:00Z",
      "last_item": { "id": "cll-abc123", "type": "CALL", "direction": "INBOUND", "result": "ANSWERED", "summary": "Customer called about upgrading their plan.", "duration": 145 }
    }
  ],
  "pagination": { "page": 1, "size": 5, "total_count": 156, "has_more": true }
}
```

## FAQ

<AccordionGroup>
  <Accordion title="Quelle est l'URL de base et comment l'API est-elle versionnée ?">
    L'hôte est toujours `https://api.withallo.com`. La version est le premier segment du chemin. Presque tout est en `/v2/api/...`. L'envoi de SMS est en `/v1/api/sms`. Il n'y a ni header de version, ni header `Accept` à définir.
  </Accordion>

  <Accordion title="Comment s'authentifier ?">
    Envoyez `Authorization: Api-Key ak_live_your_key_here` sur chaque requête. Le schéma est `Api-Key`, pas `Bearer`. Générez vos clés depuis [Paramètres > API](https://web.withallo.com/settings/api) avec les permissions Admin ou Manager. Une clé est liée à une seule équipe et ne s'affiche qu'une fois. Voir [Authentification](/fr/docs/guides/authentication).
  </Accordion>

  <Accordion title="Quel scope faut-il pour un endpoint ?">
    Appelez `GET /v2/api/me`. Son tableau `endpoints` liste chaque chemin que votre clé peut atteindre avec le scope nécessaire. Le tableau complet est aussi dans [Authentification](/fr/docs/guides/authentication#scope-to-endpoint-mapping). Un `403` avec le code `API_KEY_INSUFFICIENT_SCOPE` signifie que la clé est valide mais qu'il lui manque un scope : créez une nouvelle clé avec ce scope.
  </Accordion>

  <Accordion title="Comment envoyer un SMS ?">
    `POST /v1/api/sms` depuis un numéro Allo américain, et `POST /v1/api/sms` avec un sender ID vérifié pour la France. Le scope est `SMS_SEND` et les numéros sont au format E.164 (`+14155551234`). Voir [Envoyer un SMS](/fr/docs/sms/send-sms) et [Envoyer un SMS (France)](/fr/docs/sms/send-sms-france).
  </Accordion>

  <Accordion title="Comment retrouver un appel ou un message précis ?">
    Utilisez `POST /v2/api/conversations/items/search` avec des filtres comme `date`, `direction`, `type` et une chaîne `search` qui porte sur les transcriptions et le contenu des messages. `GET /v2/api/conversations` regroupe plutôt l'activité par numéro de contact. Pour récupérer des IDs connus en lot, utilisez `POST /v2/api/conversations/items/batch`. Voir [Conversations](/fr/docs/conversations/overview).
  </Accordion>

  <Accordion title="Comment fonctionne la pagination ?">
    Les endpoints paginés acceptent `page` et `size` et renvoient un objet `pagination` avec `page`, `size`, `total_count`, `total_pages` et `has_more`. Incrémentez `page` tant que `has_more` vaut `true`. Pour compter des résultats sans les récupérer, demandez `size=1` et lisez `pagination.total_count`. Voir [Pagination](/fr/docs/guides/pagination).
  </Accordion>

  <Accordion title="À quoi ressemble une erreur et peut-on la réessayer ?">
    Chaque erreur renvoie un objet `error` avec `type`, `code`, `message`, `retryable`, `request_id`, et souvent `param`, `suggestion` et `doc_url`. Ne réessayez que si `retryable` vaut `true`. Sur un `429`, attendez `retry_after_seconds` avant de réessayer. Voir [Gestion des erreurs](/fr/docs/guides/error-handling) et [Codes d'erreur](/fr/docs/guides/error-codes).
  </Accordion>

  <Accordion title="Quelles sont les rate limits ?">
    20 requêtes GET par seconde et 5 requêtes d'écriture par seconde, par API key. Lisez `X-RateLimit-Remaining` et `X-RateLimit-Reset` sur chaque réponse. Voir [Rate limits](/fr/docs/guides/rate-limits).
  </Accordion>

  <Accordion title="Quel format pour les numéros de téléphone ?">
    E.164, avec le `+` et l'indicatif pays, par exemple `+14155551234`. Quand un numéro passe dans une query string, encodez le `+` en `%2B`.
  </Accordion>

  <Accordion title="Comment être notifié à la fin d'un appel plutôt que d'interroger l'API ?">
    Créez un webhook avec `POST /v2/api/webhooks` et abonnez-vous aux événements dont vous avez besoin. Les payloads sont signés en HMAC et réessayés automatiquement. Listez les événements disponibles avec `GET /v2/api/webhooks/event_types`. Voir [Webhooks](/fr/docs/webhooks/overview).
  </Accordion>

  <Accordion title="Peut-on créer des comptes Allo pour ses propres clients ?">
    Oui, avec le scope `PARTNER`. `POST /v2/api/partner/accounts` crée un compte, provisionne un numéro et renvoie une API key liée à ce compte. Le scope `PARTNER` est accordé manuellement aux revendeurs approuvés et ne peut pas s'auto-générer. Voir [Partenaires](/fr/docs/partner/overview), et [Marque blanche](/fr/docs/white-label/overview) pour piloter les comptes depuis votre propre produit.
  </Accordion>

  <Accordion title="Existe-t-il un serveur MCP ?">
    Oui. Voir [le MCP Allo](/fr/help/integrations/mcp) pour connecter un agent IA à Allo sans écrire d'appels HTTP.
  </Accordion>
</AccordionGroup>

## Étapes suivantes

<CardGroup cols={2}>
  <Card title="Cas d'usage courants" href="/fr/docs/guides/common-use-cases">
    Des requêtes prêtes à copier pour synchroniser, rechercher et reporter
  </Card>
  <Card title="Authentification" href="/fr/docs/guides/authentication">
    Scopes et correspondance scope/endpoint
  </Card>
  <Card title="Webhooks" href="/fr/docs/webhooks/overview">
    Recevez les événements au lieu d'interroger l'API
  </Card>
  <Card title="Le MCP Allo" href="/fr/help/integrations/mcp">
    Connectez un agent IA à Allo sans écrire d'appels HTTP
  </Card>
</CardGroup>
