Toutes les requêtes API nécessitent une API key transmise dans le header Authorization.
Format du header
Authorization: Api-Key ak_live_your_key_here
Vous pouvez aussi envoyer la clé seule, sans préfixe :
Authorization: ak_live_your_key_here
Générer des API keys
- Allez dans Paramètres Allo > API
- Cliquez sur Create API Key
- Sélectionnez les scopes dont votre intégration a besoin
- Copiez la clé, elle ne sera plus affichée
Scopes des API keys
Chaque API key possède des scopes spécifiques qui déterminent les opérations qu'elle peut effectuer.
| Scope | Description |
|---|---|
CONVERSATIONS_READ | Lire les appels, SMS et l'historique des conversations |
CONVERSATIONS_WRITE | Modifier les résumés d'appel, archiver et marquer les conversations |
CRM_READ | Obtenir et rechercher des personnes, entreprises et deals, et lister les champs personnalisés |
CRM_WRITE | Créer et mettre à jour des personnes et des entreprises, et créer des champs personnalisés |
CRM_DELETE | Supprimer des attributs personnalisés des personnes et des entreprises |
SMS_SEND | Envoyer des SMS et des MMS |
FAX_SEND | Envoyer des fax |
WEBHOOKS_READ_WRITE | Créer et gérer les configurations de webhooks |
PHONE_NUMBERS_READ | Lister les numéros de téléphone et leurs capacités |
PHONE_NUMBERS_WRITE | Enregistrer et publier les call flows |
USERS_READ | Lister les membres de l'équipe et leurs rôles |
TAGS_READ | Lister les tags disponibles |
TAGS_WRITE | Créer et supprimer des tags, les ajouter et les retirer sur les éléments de conversation |
NOTES_READ | Lire les notes de conversation et les notes de personne |
NOTES_WRITE | Créer, modifier et supprimer des notes |
THREADS_READ | Lire les fils de discussion et leurs commentaires |
THREADS_WRITE | Créer des fils et des commentaires, modifier des commentaires, résoudre des fils |
SUMMARY_TEMPLATES_READ | Lire les templates de résumé d'appel de l'équipe |
SUMMARY_TEMPLATES_WRITE | Créer, modifier et supprimer des templates, et définir celui par défaut d'un numéro |
BILLING | Accéder aux informations de facturation et d'abonnement |
DIALING_QUEUE_READ_WRITE | Gérer les files du Power Dialer |
AGENTS_READ | Lire la configuration du réceptionniste IA, les agendas connectés et les voix |
AGENTS_WRITE | Configurer le réceptionniste IA, son prompt, ses connaissances, et l'activer ou le désactiver |
INBOXES_READ | Lister vos boîtes de réception et celles de vos coéquipiers, les suggestions de boîtes et les options du menu téléphonique d'une ligne |
INBOXES_WRITE | Créer, modifier et supprimer des boîtes de réception, et couper leurs notifications |
PARTNER | Créer et gérer des comptes Allo en tant que revendeur. Accordé manuellement aux revendeurs approuvés, il ne peut pas s'auto-générer |
GET /v2/api/me ne demande aucun scope. Toute clé valide peut l'appeler, et son tableau endpoints fait foi sur ce que votre clé peut atteindre.
Correspondance scopes-endpoints
Chaque endpoint documenté et le scope dont il a besoin. Si un appel renvoie 403 avec le code API_KEY_INSUFFICIENT_SCOPE, la clé est valide mais il lui manque le scope indiqué ici.
Découverte
| Endpoint | Méthode | Scope requis |
|---|---|---|
/v2/api/me | GET | aucun |
Conversations
| Endpoint | Méthode | Scope requis |
|---|---|---|
/v2/api/conversations | GET | CONVERSATIONS_READ |
/v2/api/conversations/items/batch | POST | CONVERSATIONS_READ |
/v2/api/conversations/items/search | POST | CONVERSATIONS_READ |
/v2/api/conversations/items/{id} | GET | CONVERSATIONS_READ |
/v2/api/conversations/items/{id}/recording | GET | CONVERSATIONS_READ |
/v2/api/conversations/items/{id}/summary | PATCH | CONVERSATIONS_WRITE |
/v2/api/conversations/items/{id}/tags | POST | TAGS_WRITE |
/v2/api/conversations/items/{id}/tags/{tag} | DELETE | TAGS_WRITE |
/v2/api/conversations/notes/{id} | DELETE | NOTES_WRITE |
/v2/api/conversations/notes/{id} | GET | NOTES_READ |
/v2/api/conversations/notes/{id} | PATCH | NOTES_WRITE |
/v2/api/conversations/{contact_number}/action | PUT | CONVERSATIONS_WRITE |
/v2/api/conversations/{contact_number}/notes | GET | NOTES_READ |
/v2/api/conversations/{contact_number}/notes | POST | NOTES_WRITE |
/v2/api/conversations/{contact_number}/pin | DELETE | CONVERSATIONS_WRITE |
/v2/api/conversations/{contact_number}/pin | PUT | CONVERSATIONS_WRITE |
CRM
| Endpoint | Méthode | Scope requis |
|---|---|---|
/v2/api/crm/attributes | GET | CRM_READ |
/v2/api/crm/attributes | POST | CRM_WRITE |
/v2/api/crm/attributes/{key} | DELETE | CRM_DELETE |
/v2/api/crm/attributes/{key} | PATCH | CRM_WRITE |
/v2/api/crm/companies/attributes | GET | CRM_READ |
/v2/api/crm/companies/attributes | POST | CRM_WRITE |
/v2/api/crm/companies/attributes/{key} | DELETE | CRM_DELETE |
/v2/api/crm/companies/attributes/{key} | PATCH | CRM_WRITE |
/v2/api/crm/companies | POST | CRM_WRITE |
/v2/api/crm/companies/search | POST | CRM_READ |
/v2/api/crm/companies/{id} | GET | CRM_READ |
/v2/api/crm/companies/{id} | PUT | CRM_WRITE |
/v2/api/crm/deals/search | POST | CRM_READ |
/v2/api/crm/deals/{id} | GET | CRM_READ |
/v2/api/crm/people | POST | CRM_WRITE |
/v2/api/crm/people/search | POST | CRM_READ |
/v2/api/crm/people/{id} | GET | CRM_READ |
/v2/api/crm/people/{id} | PUT | CRM_WRITE |
/v2/api/crm/people/{person_id}/notes | GET | NOTES_READ |
/v2/api/crm/people/{person_id}/notes | POST | NOTES_WRITE |
/v2/api/crm/people/{person_id}/notes/{note_id} | DELETE | NOTES_WRITE |
/v2/api/crm/people/{person_id}/notes/{note_id} | PATCH | NOTES_WRITE |
Fils de discussion
| Endpoint | Méthode | Scope requis |
|---|---|---|
/v2/api/threads | GET | THREADS_READ |
/v2/api/threads | POST | THREADS_WRITE |
/v2/api/threads/comments/{comment_id} | PATCH | THREADS_WRITE |
/v2/api/threads/{id} | GET | THREADS_READ |
/v2/api/threads/{id}/comments | POST | THREADS_WRITE |
/v2/api/threads/{id}/resolve | POST | THREADS_WRITE |
/v2/api/threads/{id}/unresolve | POST | THREADS_WRITE |
Boîtes de réception
| Endpoint | Méthode | Scope requis |
|---|---|---|
/v2/api/inboxes | GET | INBOXES_READ |
/v2/api/inboxes | POST | INBOXES_WRITE |
/v2/api/inboxes/suggestions | GET | INBOXES_READ |
/v2/api/inboxes/{inbox_id} | DELETE | INBOXES_WRITE |
/v2/api/inboxes/{inbox_id} | PATCH | INBOXES_WRITE |
/v2/api/numbers/{number}/menu_options | GET | INBOXES_READ |
SMS
| Endpoint | Méthode | Scope requis |
|---|---|---|
/v1/api/sms | POST | SMS_SEND |
/v1/api/sms#france | POST | SMS_SEND |
/v2/api/faxes | POST | FAX_SEND |
Numéros et call flows
| Endpoint | Méthode | Scope requis |
|---|---|---|
/v2/api/numbers | GET | PHONE_NUMBERS_READ |
/v2/api/numbers/{number}/agent | GET | AGENTS_READ |
/v2/api/numbers/{number}/agent | PATCH | AGENTS_WRITE |
/v2/api/numbers/{number}/agent/knowledge/files/{id} | DELETE | AGENTS_WRITE |
/v2/api/numbers/{number}/agent/knowledge/websites | POST | AGENTS_WRITE |
/v2/api/numbers/{number}/agent/knowledge/websites/{id} | DELETE | AGENTS_WRITE |
/v2/api/numbers/{number}/agent/knowledge/websites/{id} | PATCH | AGENTS_WRITE |
/v2/api/numbers/{number}/agent/prompt | PUT | AGENTS_WRITE |
/v2/api/numbers/{number}/agent/status | PUT | AGENTS_WRITE |
/v2/api/numbers/{number}/call_flow | GET | PHONE_NUMBERS_READ |
/v2/api/numbers/{number}/call_flow/draft | GET | PHONE_NUMBERS_READ |
/v2/api/numbers/{number}/call_flow/draft | PUT | PHONE_NUMBERS_WRITE |
/v2/api/numbers/{number}/call_flow/publish | POST | PHONE_NUMBERS_WRITE |
/v2/api/numbers/{number}/default_summary_template | PUT | SUMMARY_TEMPLATES_WRITE |
Réceptionniste IA
| Endpoint | Méthode | Scope requis |
|---|---|---|
/v2/api/calendars | GET | AGENTS_READ |
/v2/api/calendars/{id} | GET | AGENTS_READ |
/v2/api/voices | GET | AGENTS_READ |
Templates de résumé
| Endpoint | Méthode | Scope requis |
|---|---|---|
/v2/api/summary_templates | GET | SUMMARY_TEMPLATES_READ |
/v2/api/summary_templates | POST | SUMMARY_TEMPLATES_WRITE |
/v2/api/summary_templates/{id} | DELETE | SUMMARY_TEMPLATES_WRITE |
/v2/api/summary_templates/{id} | GET | SUMMARY_TEMPLATES_READ |
/v2/api/summary_templates/{id} | PUT | SUMMARY_TEMPLATES_WRITE |
Tags
| Endpoint | Méthode | Scope requis |
|---|---|---|
/v2/api/tags | GET | TAGS_READ |
/v2/api/tags | POST | TAGS_WRITE |
/v2/api/tags/{id} | DELETE | TAGS_WRITE |
Utilisateurs
| Endpoint | Méthode | Scope requis |
|---|---|---|
/v2/api/users | GET | USERS_READ |
/v2/api/users/{id} | GET | USERS_READ |
Webhooks
| Endpoint | Méthode | Scope requis |
|---|---|---|
/v2/api/webhooks | GET | WEBHOOKS_READ_WRITE |
/v2/api/webhooks | POST | WEBHOOKS_READ_WRITE |
/v2/api/webhooks/event_types | GET | WEBHOOKS_READ_WRITE |
/v2/api/webhooks/{webhook_id} | DELETE | WEBHOOKS_READ_WRITE |
/v2/api/webhooks/{webhook_id} | GET | WEBHOOKS_READ_WRITE |
/v2/api/webhooks/{webhook_id} | PUT | WEBHOOKS_READ_WRITE |
Analytics
| Endpoint | Méthode | Scope requis |
|---|---|---|
/v2/api/analytics/outbound | POST | CONVERSATIONS_READ |
/v2/api/analytics/overview | POST | CONVERSATIONS_READ |
Files du Power Dialer
| Endpoint | Méthode | Scope requis |
|---|---|---|
/v2/api/dialing-queues/current | GET | DIALING_QUEUE_READ_WRITE |
/v2/api/dialing-queues/current | PATCH | DIALING_QUEUE_READ_WRITE |
/v2/api/dialing-queues/current | POST | DIALING_QUEUE_READ_WRITE |
/v2/api/dialing-queues/current/numbers | DELETE | DIALING_QUEUE_READ_WRITE |
/v2/api/dialing-queues/current/numbers | POST | DIALING_QUEUE_READ_WRITE |
Partenaires
| Endpoint | Méthode | Scope requis |
|---|---|---|
/v2/api/partner/accounts | POST | PARTNER |
/v2/api/partner/accounts/price | GET | PARTNER |
/v2/api/partner/accounts/{id} | DELETE | PARTNER |
/v2/api/partner/accounts/{id} | GET | PARTNER |
/v2/api/partner/credit | GET | PARTNER |
Marque blanche
| Endpoint | Méthode | Scope requis |
|---|---|---|
/v2/api/partner/accounts/{account_id}/esims | POST | PARTNER |
/v2/api/partner/accounts/{account_id}/esims/offer | GET | PARTNER |
/v2/api/partner/accounts/{account_id}/sender_ids | GET | PARTNER |
/v2/api/partner/accounts/{account_id}/sender_ids | POST | PARTNER |
/v2/api/partner/accounts/{account_id}/sender_ids/{id} | GET | PARTNER |
/v2/api/partner/accounts/{id}/members | GET | PARTNER |
/v2/api/partner/accounts/{id}/members | POST | PARTNER |
/v2/api/partner/accounts/{id}/members/{member_id} | DELETE | PARTNER |
/v2/api/partner/accounts/{id}/numbers | POST | PARTNER |
/v2/api/partner/accounts/{id}/numbers/price | GET | PARTNER |
/v2/api/partner/accounts/{id}/resume | POST | PARTNER |
/v2/api/partner/accounts/{id}/suspend | POST | PARTNER |
/v2/api/partner/esims/{id} | GET | PARTNER |
/v2/api/partner/esims/{id}/activation_code | GET | PARTNER |
/v2/api/partner/esims/{id}/revoke | POST | PARTNER |
/v2/api/partner/esims/{id}/tier | PUT | PARTNER |
/v2/api/partner/esims/{id}/topups | POST | PARTNER |
Exemple de requête
curl -X GET "https://api.withallo.com/v2/api/conversations" \
-H "Authorization: Api-Key ak_live_abc123def456"
Réponses d'erreur
Clé invalide ou manquante (401)
{
"error": {
"type": "authentication_error",
"code": "API_KEY_INVALID",
"message": "The API key provided is invalid or has been revoked.",
"retryable": false,
"request_id": "req_a1b2c3d4e5f6",
"doc_url": "https://www.withallo.com/docs/guides/error-codes#api_key_invalid"
}
}
Scope insuffisant (403)
{
"error": {
"type": "permission_error",
"code": "API_KEY_INSUFFICIENT_SCOPE",
"message": "This API key lacks the 'CONVERSATIONS_READ' scope required for this endpoint.",
"retryable": false,
"request_id": "req_a1b2c3d4e5f6",
"suggestion": "Create a new API key with the required scope at https://web.withallo.com/settings/api"
}
}
Sécurité
- Les API keys sont limitées à une seule équipe
- Les clés peuvent être révoquées à tout moment depuis les paramètres
- N'exposez jamais les clés dans du code côté client ou des dépôts publics
- Utilisez des variables d'environnement pour stocker les clés dans votre application