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
Configuration des API keys, scopes et correspondance scope/endpoint
Limites de requêtes et headers
Résultats paginés avec totaux
Format des erreurs et résolution
Chaque code d'erreur et quoi faire ensuite
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 |
| Fax | POST /v2/api/faxes | Envoi d'un PDF par fax depuis une ligne Allo avec le fax activé |
| CRM | /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 | /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, /v2/api/partner/credit | Créer des comptes Allo, obtenir leur prix et les désactiver en tant que revendeur |
| Marque blanche | /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 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, et Marque blanche pour piloter les comptes depuis votre propre produit.
Existe-t-il un serveur MCP ?
Oui. Voir le MCP Allo pour connecter un agent IA à Allo sans écrire d'appels HTTP.
Étapes suivantes
Des requêtes prêtes à copier pour synchroniser, rechercher et reporter
Scopes et correspondance scope/endpoint
Recevez les événements au lieu d'interroger l'API
Connectez un agent IA à Allo sans écrire d'appels HTTP