Authentification

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

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
`CRM_WRITE`	Créer et mettre à jour des personnes et des entreprises
`SMS_SEND`	Envoyer des SMS et MMS
`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
`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}/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`

CRM

Endpoint	Méthode	Scope requis
`/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`

SMS

Endpoint	Méthode	Scope requis
`/v1/api/sms`	POST	`SMS_SEND`
`/v1/api/sms#france`	POST	`SMS_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/{id}`	DELETE	`PARTNER`
`/v2/api/partner/accounts/{id}`	GET	`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://help.withallo.com/en/v2/api-reference/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

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

Format du header

Générer des API keys

Scopes des API keys

Correspondance scopes-endpoints

Exemple de requête

Réponses d’erreur

Sécurité

​Format du header

​Générer des API keys

​Scopes des API keys

​Correspondance scopes-endpoints

​Exemple de requête

​Réponses d’erreur

​Sécurité

Format du header

Générer des API keys

Scopes des API keys

Correspondance scopes-endpoints

Exemple de requête

Réponses d’erreur

Sécurité