Vue d'ensemble

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.

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.

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

{
  "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.

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

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 :

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

Authentification

Configuration des API keys, scopes et correspondance scope/endpoint

Rate limits

Limites de requêtes et headers

Pagination

Résultats paginés avec totaux

Gestion des erreurs

Format des erreurs et résolution

Codes d'erreur

Chaque code d’erreur et quoi faire ensuite

Cas d'usage courants

Des requêtes prêtes à l’emploi pour les tâches habituelles

Ressources

Ressource	Chemins principaux	Ce que ça couvre
Conversations	`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	`POST /v1/api/sms`	Envoi de SMS et MMS depuis vos numéros Allo ou vos sender IDs
CRM	`/v2/api/crm/people`, `/v2/api/crm/companies`, `/v2/api/crm/deals`	Créer, lire, modifier et rechercher des personnes, entreprises et deals
Notes	`/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	`/v2/api/threads`	Fils de discussion d’équipe sur les appels, SMS et notes de conversation
Webhooks	`/v2/api/webhooks`	Notifications d’événements en temps réel avec signatures HMAC et tentatives automatiques
Numéros de téléphone	`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	`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	`/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é	`/v2/api/summary_templates`	Les templates qui structurent les résumés d’appel générés par l’IA
Analytics	`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	`/v2/api/dialing-queues/current`	Consulter et remplir la file du Power Dialer
Réceptionniste IA	`/v2/api/numbers/{number}/agent`	Configurer la réceptionniste, son prompt, ses connaissances et son statut on/off
Partenaires	`/v2/api/partner/accounts`	Créer et gérer des comptes Allo en tant que revendeur white-label

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 pour les détails.

Exemple rapide

Obtenez vos conversations récentes :

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

{
  "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

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.

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 avec les permissions Admin ou Manager. Une clé est liée à une seule équipe et ne s’affiche qu’une fois. Voir Authentification.

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

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 et Envoyer un SMS (France).

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.

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.

À 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 et Codes d’erreur.

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.

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.

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.

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.

Existe-t-il un serveur MCP ?

Oui. Voir le MCP Allo pour connecter un agent IA à Allo sans écrire d’appels HTTP.

Étapes suivantes

Cas d'usage courants

Des requêtes prêtes à copier pour synchroniser, rechercher et reporter

Authentification

Scopes et correspondance scope/endpoint

Webhooks

Recevez les événements au lieu d’interroger l’API

Le MCP Allo

Connectez un agent IA à Allo sans écrire d’appels HTTP

API

Webhooks

Conversations

CRM

Personnes

Entreprises

Deals

Notes

Fils de discussion

Numéros de téléphone

Réceptionniste IA

Tags

Modèles de résumé

Utilisateurs

SMS

Analytiques

Power Dialer

Partner

URL de base

Commencez ici

Pour commencer

Authentification

Guides

Authentification

Rate limits

Pagination

Gestion des erreurs

Codes d'erreur

Cas d'usage courants

Ressources

Rate limiting

Exemple rapide

FAQ

Étapes suivantes

Cas d'usage courants

Authentification

Webhooks

Le MCP Allo

​URL de base

​Commencez ici

​Pour commencer

​Authentification

​Guides

Authentification

Rate limits

Pagination

Gestion des erreurs

Codes d'erreur

Cas d'usage courants

​Ressources

​Rate limiting

​Exemple rapide

​FAQ

​Étapes suivantes

Cas d'usage courants

Authentification

Webhooks

Le MCP Allo

URL de base

Commencez ici

Pour commencer

Authentification

Guides

Ressources

Rate limiting

Exemple rapide

FAQ

Étapes suivantes