Allo

Authentification

Authentifier les requêtes API avec des API keys

Mis à jour le

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

  1. Allez dans Paramètres Allo > API
  2. Cliquez sur Create API Key
  3. Sélectionnez les scopes dont votre intégration a besoin
  4. 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.

ScopeDescription
CONVERSATIONS_READLire les appels, SMS et l'historique des conversations
CONVERSATIONS_WRITEModifier les résumés d'appel, archiver et marquer les conversations
CRM_READObtenir et rechercher des personnes, entreprises et deals, et lister les champs personnalisés
CRM_WRITECréer et mettre à jour des personnes et des entreprises, et créer des champs personnalisés
CRM_DELETESupprimer des attributs personnalisés des personnes et des entreprises
SMS_SENDEnvoyer des SMS et des MMS
FAX_SENDEnvoyer des fax
WEBHOOKS_READ_WRITECréer et gérer les configurations de webhooks
PHONE_NUMBERS_READLister les numéros de téléphone et leurs capacités
PHONE_NUMBERS_WRITEEnregistrer et publier les call flows
USERS_READLister les membres de l'équipe et leurs rôles
TAGS_READLister les tags disponibles
TAGS_WRITECréer et supprimer des tags, les ajouter et les retirer sur les éléments de conversation
NOTES_READLire les notes de conversation et les notes de personne
NOTES_WRITECréer, modifier et supprimer des notes
THREADS_READLire les fils de discussion et leurs commentaires
THREADS_WRITECréer des fils et des commentaires, modifier des commentaires, résoudre des fils
SUMMARY_TEMPLATES_READLire les templates de résumé d'appel de l'équipe
SUMMARY_TEMPLATES_WRITECréer, modifier et supprimer des templates, et définir celui par défaut d'un numéro
BILLINGAccéder aux informations de facturation et d'abonnement
DIALING_QUEUE_READ_WRITEGérer les files du Power Dialer
AGENTS_READLire la configuration du réceptionniste IA, les agendas connectés et les voix
AGENTS_WRITEConfigurer le réceptionniste IA, son prompt, ses connaissances, et l'activer ou le désactiver
INBOXES_READLister 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_WRITECréer, modifier et supprimer des boîtes de réception, et couper leurs notifications
PARTNERCré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

EndpointMéthodeScope requis
/v2/api/meGETaucun

Conversations

EndpointMéthodeScope requis
/v2/api/conversationsGETCONVERSATIONS_READ
/v2/api/conversations/items/batchPOSTCONVERSATIONS_READ
/v2/api/conversations/items/searchPOSTCONVERSATIONS_READ
/v2/api/conversations/items/{id}GETCONVERSATIONS_READ
/v2/api/conversations/items/{id}/recordingGETCONVERSATIONS_READ
/v2/api/conversations/items/{id}/summaryPATCHCONVERSATIONS_WRITE
/v2/api/conversations/items/{id}/tagsPOSTTAGS_WRITE
/v2/api/conversations/items/{id}/tags/{tag}DELETETAGS_WRITE
/v2/api/conversations/notes/{id}DELETENOTES_WRITE
/v2/api/conversations/notes/{id}GETNOTES_READ
/v2/api/conversations/notes/{id}PATCHNOTES_WRITE
/v2/api/conversations/{contact_number}/actionPUTCONVERSATIONS_WRITE
/v2/api/conversations/{contact_number}/notesGETNOTES_READ
/v2/api/conversations/{contact_number}/notesPOSTNOTES_WRITE
/v2/api/conversations/{contact_number}/pinDELETECONVERSATIONS_WRITE
/v2/api/conversations/{contact_number}/pinPUTCONVERSATIONS_WRITE

CRM

EndpointMéthodeScope requis
/v2/api/crm/attributesGETCRM_READ
/v2/api/crm/attributesPOSTCRM_WRITE
/v2/api/crm/attributes/{key}DELETECRM_DELETE
/v2/api/crm/attributes/{key}PATCHCRM_WRITE
/v2/api/crm/companies/attributesGETCRM_READ
/v2/api/crm/companies/attributesPOSTCRM_WRITE
/v2/api/crm/companies/attributes/{key}DELETECRM_DELETE
/v2/api/crm/companies/attributes/{key}PATCHCRM_WRITE
/v2/api/crm/companiesPOSTCRM_WRITE
/v2/api/crm/companies/searchPOSTCRM_READ
/v2/api/crm/companies/{id}GETCRM_READ
/v2/api/crm/companies/{id}PUTCRM_WRITE
/v2/api/crm/deals/searchPOSTCRM_READ
/v2/api/crm/deals/{id}GETCRM_READ
/v2/api/crm/peoplePOSTCRM_WRITE
/v2/api/crm/people/searchPOSTCRM_READ
/v2/api/crm/people/{id}GETCRM_READ
/v2/api/crm/people/{id}PUTCRM_WRITE
/v2/api/crm/people/{person_id}/notesGETNOTES_READ
/v2/api/crm/people/{person_id}/notesPOSTNOTES_WRITE
/v2/api/crm/people/{person_id}/notes/{note_id}DELETENOTES_WRITE
/v2/api/crm/people/{person_id}/notes/{note_id}PATCHNOTES_WRITE

Fils de discussion

EndpointMéthodeScope requis
/v2/api/threadsGETTHREADS_READ
/v2/api/threadsPOSTTHREADS_WRITE
/v2/api/threads/comments/{comment_id}PATCHTHREADS_WRITE
/v2/api/threads/{id}GETTHREADS_READ
/v2/api/threads/{id}/commentsPOSTTHREADS_WRITE
/v2/api/threads/{id}/resolvePOSTTHREADS_WRITE
/v2/api/threads/{id}/unresolvePOSTTHREADS_WRITE

Boîtes de réception

EndpointMéthodeScope requis
/v2/api/inboxesGETINBOXES_READ
/v2/api/inboxesPOSTINBOXES_WRITE
/v2/api/inboxes/suggestionsGETINBOXES_READ
/v2/api/inboxes/{inbox_id}DELETEINBOXES_WRITE
/v2/api/inboxes/{inbox_id}PATCHINBOXES_WRITE
/v2/api/numbers/{number}/menu_optionsGETINBOXES_READ

SMS

EndpointMéthodeScope requis
/v1/api/smsPOSTSMS_SEND
/v1/api/sms#francePOSTSMS_SEND
/v2/api/faxesPOSTFAX_SEND

Numéros et call flows

EndpointMéthodeScope requis
/v2/api/numbersGETPHONE_NUMBERS_READ
/v2/api/numbers/{number}/agentGETAGENTS_READ
/v2/api/numbers/{number}/agentPATCHAGENTS_WRITE
/v2/api/numbers/{number}/agent/knowledge/files/{id}DELETEAGENTS_WRITE
/v2/api/numbers/{number}/agent/knowledge/websitesPOSTAGENTS_WRITE
/v2/api/numbers/{number}/agent/knowledge/websites/{id}DELETEAGENTS_WRITE
/v2/api/numbers/{number}/agent/knowledge/websites/{id}PATCHAGENTS_WRITE
/v2/api/numbers/{number}/agent/promptPUTAGENTS_WRITE
/v2/api/numbers/{number}/agent/statusPUTAGENTS_WRITE
/v2/api/numbers/{number}/call_flowGETPHONE_NUMBERS_READ
/v2/api/numbers/{number}/call_flow/draftGETPHONE_NUMBERS_READ
/v2/api/numbers/{number}/call_flow/draftPUTPHONE_NUMBERS_WRITE
/v2/api/numbers/{number}/call_flow/publishPOSTPHONE_NUMBERS_WRITE
/v2/api/numbers/{number}/default_summary_templatePUTSUMMARY_TEMPLATES_WRITE

Réceptionniste IA

EndpointMéthodeScope requis
/v2/api/calendarsGETAGENTS_READ
/v2/api/calendars/{id}GETAGENTS_READ
/v2/api/voicesGETAGENTS_READ

Templates de résumé

EndpointMéthodeScope requis
/v2/api/summary_templatesGETSUMMARY_TEMPLATES_READ
/v2/api/summary_templatesPOSTSUMMARY_TEMPLATES_WRITE
/v2/api/summary_templates/{id}DELETESUMMARY_TEMPLATES_WRITE
/v2/api/summary_templates/{id}GETSUMMARY_TEMPLATES_READ
/v2/api/summary_templates/{id}PUTSUMMARY_TEMPLATES_WRITE

Tags

EndpointMéthodeScope requis
/v2/api/tagsGETTAGS_READ
/v2/api/tagsPOSTTAGS_WRITE
/v2/api/tags/{id}DELETETAGS_WRITE

Utilisateurs

EndpointMéthodeScope requis
/v2/api/usersGETUSERS_READ
/v2/api/users/{id}GETUSERS_READ

Webhooks

EndpointMéthodeScope requis
/v2/api/webhooksGETWEBHOOKS_READ_WRITE
/v2/api/webhooksPOSTWEBHOOKS_READ_WRITE
/v2/api/webhooks/event_typesGETWEBHOOKS_READ_WRITE
/v2/api/webhooks/{webhook_id}DELETEWEBHOOKS_READ_WRITE
/v2/api/webhooks/{webhook_id}GETWEBHOOKS_READ_WRITE
/v2/api/webhooks/{webhook_id}PUTWEBHOOKS_READ_WRITE

Analytics

EndpointMéthodeScope requis
/v2/api/analytics/outboundPOSTCONVERSATIONS_READ
/v2/api/analytics/overviewPOSTCONVERSATIONS_READ

Files du Power Dialer

EndpointMéthodeScope requis
/v2/api/dialing-queues/currentGETDIALING_QUEUE_READ_WRITE
/v2/api/dialing-queues/currentPATCHDIALING_QUEUE_READ_WRITE
/v2/api/dialing-queues/currentPOSTDIALING_QUEUE_READ_WRITE
/v2/api/dialing-queues/current/numbersDELETEDIALING_QUEUE_READ_WRITE
/v2/api/dialing-queues/current/numbersPOSTDIALING_QUEUE_READ_WRITE

Partenaires

EndpointMéthodeScope requis
/v2/api/partner/accountsPOSTPARTNER
/v2/api/partner/accounts/priceGETPARTNER
/v2/api/partner/accounts/{id}DELETEPARTNER
/v2/api/partner/accounts/{id}GETPARTNER
/v2/api/partner/creditGETPARTNER

Marque blanche

EndpointMéthodeScope requis
/v2/api/partner/accounts/{account_id}/esimsPOSTPARTNER
/v2/api/partner/accounts/{account_id}/esims/offerGETPARTNER
/v2/api/partner/accounts/{account_id}/sender_idsGETPARTNER
/v2/api/partner/accounts/{account_id}/sender_idsPOSTPARTNER
/v2/api/partner/accounts/{account_id}/sender_ids/{id}GETPARTNER
/v2/api/partner/accounts/{id}/membersGETPARTNER
/v2/api/partner/accounts/{id}/membersPOSTPARTNER
/v2/api/partner/accounts/{id}/members/{member_id}DELETEPARTNER
/v2/api/partner/accounts/{id}/numbersPOSTPARTNER
/v2/api/partner/accounts/{id}/numbers/priceGETPARTNER
/v2/api/partner/accounts/{id}/resumePOSTPARTNER
/v2/api/partner/accounts/{id}/suspendPOSTPARTNER
/v2/api/partner/esims/{id}GETPARTNER
/v2/api/partner/esims/{id}/activation_codeGETPARTNER
/v2/api/partner/esims/{id}/revokePOSTPARTNER
/v2/api/partner/esims/{id}/tierPUTPARTNER
/v2/api/partner/esims/{id}/topupsPOSTPARTNER

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