Authentification

Toutes les requetes API necessitent une API key transmise dans le header Authorization.

Format du header

Authorization: Api-Key ak_live_your_key_here

Generer des API keys

Allez dans Parametres Allo > API
Cliquez sur Create API Key
Selectionnez les scopes dont votre integration a besoin
Copiez la cle — elle ne sera plus affichee

Scopes des API keys

Chaque API key possede des scopes specifiques qui determinent les operations qu’elle peut effectuer.

Scope	Description
`CONVERSATIONS_READ`	Lire les appels, SMS et l’historique des conversations
`CONTACTS_READ`	Lire les informations de contact
`CONTACTS_READ_WRITE`	Lire et modifier les informations de contact
`SMS_SEND`	Envoyer des SMS et MMS
`WEBHOOKS_READ_WRITE`	Creer et gerer les configurations de webhooks
`PHONE_NUMBERS_READ`	Lister les numeros de telephone et leurs capacites
`USERS_READ`	Lister les membres de l’equipe et leurs roles
`TAGS_READ`	Lister les tags disponibles
`TAGS_WRITE`	Ajouter et supprimer des tags sur les elements 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
`BILLING`	Acceder aux informations de facturation et d’abonnement
`DIALING_QUEUE_READ_WRITE`	Gerer les files d’attente de composition
`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

Correspondance scopes-endpoints

Endpoint	Methode	Scope requis
`/v2/api/conversations`	GET	`CONVERSATIONS_READ`
`/v2/api/conversations/items/search`	POST	`CONVERSATIONS_READ`
`/v2/api/conversations/items/{id}`	GET	`CONVERSATIONS_READ`
`/v2/api/conversations/items/batch`	POST	`CONVERSATIONS_READ`
`/v2/api/conversations/{contact_number}/action`	PUT	`CONVERSATIONS_READ`
`/v2/api/conversations/items/{id}/tags`	POST	`TAGS_WRITE`
`/v2/api/conversations/items/{id}/tags/{tag}`	DELETE	`TAGS_WRITE`
`/v2/api/users`	GET	`USERS_READ`
`/v2/api/users/{id}`	GET	`USERS_READ`
`/v2/api/tags`	GET	`TAGS_READ`
`/v2/api/numbers`	GET	`PHONE_NUMBERS_READ`
`/v2/api/conversations/{contact_number}/notes`	GET	`NOTES_READ`
`/v2/api/conversations/{contact_number}/notes`	POST	`NOTES_WRITE`
`/v2/api/conversations/notes/{id}`	GET	`NOTES_READ`
`/v2/api/conversations/notes/{id}`	PATCH	`NOTES_WRITE`
`/v2/api/conversations/notes/{id}`	DELETE	`NOTES_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}`	PATCH	`NOTES_WRITE`
`/v2/api/crm/people/{person_id}/notes/{note_id}`	DELETE	`NOTES_WRITE`
`/v2/api/threads`	GET	`THREADS_READ`
`/v2/api/threads`	POST	`THREADS_WRITE`
`/v2/api/threads/{id}`	GET	`THREADS_READ`
`/v2/api/threads/{id}/comments`	POST	`THREADS_WRITE`
`/v2/api/threads/comments/{comment_id}`	PATCH	`THREADS_WRITE`
`/v2/api/threads/{id}/resolve`	POST	`THREADS_WRITE`
`/v2/api/threads/{id}/unresolve`	POST	`THREADS_WRITE`

Exemple de requete

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

Reponses d’erreur

Cle 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"
  }
}

Securite

Les API keys sont limitees a une seule equipe
Les cles peuvent etre revoquees a tout moment depuis les parametres
N’exposez jamais les cles dans du code cote client ou des depots publics
Utilisez des variables d’environnement pour stocker les cles dans votre application

API

Webhooks

Conversations

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

Generer des API keys

Scopes des API keys

Correspondance scopes-endpoints

Exemple de requete

Reponses d’erreur

Securite

​Format du header

​Generer des API keys

​Scopes des API keys

​Correspondance scopes-endpoints

​Exemple de requete

​Reponses d’erreur

​Securite

Format du header

Generer des API keys

Scopes des API keys

Correspondance scopes-endpoints

Exemple de requete

Reponses d’erreur

Securite