Passer des appels IA et gérer Astra via l'API
L'API peut configurer et publier Astra (votre agent IA), y connecter un numéro et lui faire passer des appels sortants : POST /v1/api/calls fait composer un numéro par votre agent publié, maintient la conversation et enregistre l'appel — avec enregistrement, transcription et résumé — sur la chronologie du contact dans votre boîte de réception, facturé en crédits IA exactement comme un appel entrant répondu par l'IA.
Avant de commencer
- Votre clé API nécessite les bonnes autorisations — les puces dans Paramètres → API Développeur : Gérer l'agent IA (
agent:manage) pour la configuration de l'agent et le routage des numéros, et Passer des appels IA (calls:place) pour les appels sortants. Les clés à accès complet incluent les deux. Voir Obtenir votre clé API Ody. - Les appels sortants nécessitent un forfait actif, un agent publié et activé, et au moins un numéro actif dans votre espace de travail.
- Les crédits fonctionnent exactement comme d'habitude : 100 crédits par appel répondu par l'IA, appels de moins de 15 secondes gratuits, et chaque forfait inclut 1 000 crédits par mois. Voir Crédits et utilisation d'Astra.
Configurer et publier votre agent
GET /v1/api/agent renvoie la configuration de l'agent ainsi que votre utilisation de crédits pour le cycle actuel — pratique pour vérifier le budget avant un lot d'appels. PATCH /v1/api/agent la met à jour : name, greeting, tone, voice, language, timezone, inHoursAction/offHoursAction (agent, voicemail, app, ou forward), enabled, et jobs. Seuls les champs que vous envoyez sont modifiés, à l'exception de jobs, qui est entièrement remplacé lorsqu'il est fourni :
curl -X PATCH https://api.ody.co/v1/api/agent \
-H "Authorization: Bearer ody_live_…" \
-H "Content-Type: application/json" \
-d '{
"name": "Front Desk",
"greeting": "Thanks for calling Acme Plumbing!",
"tone": "Friendly",
"jobs": [{"name": "Take a message", "instructions": "Collect the name, number, and reason for calling."}]
}'
Les modifications sont enregistrées comme un brouillon — le même brouillon que vous verriez sur l'écran de l'agent IA dans l'application. Mettez-le en ligne avec :
curl -X POST https://api.ody.co/v1/api/agent/publish \
-H "Authorization: Bearer ody_live_…"
Connecter un numéro à l'agent
POST /v1/api/numbers/{number}/connect achemine l'un de vos numéros vers l'agent afin qu'il réponde aux appels entrants (encodez l'URL du + en %2B) :
curl -X POST "https://api.ody.co/v1/api/numbers/%2B15125550123/connect" \
-H "Authorization: Bearer ody_live_…"
Pour le réacheminer vers votre équipe, utilisez …/disconnect avec un mode de app (faire sonner votre équipe — par défaut), voicemail, ou forward (avec un numéro forwardTo) :
curl -X POST "https://api.ody.co/v1/api/numbers/%2B15125550123/disconnect" \
-H "Authorization: Bearer ody_live_…" \
-H "Content-Type: application/json" \
-d '{"mode":"app"}'
Passer un appel IA sortant
POST /v1/api/calls fait composer un numéro par votre agent publié et maintient la conversation :
curl https://api.ody.co/v1/api/calls \
-H "Authorization: Bearer ody_live_…" \
-H "Content-Type: application/json" \
-d '{"to":"+15125550199"}'
toest obligatoire (E.164).fromest facultatif — Ody préfère votre numéro connecté à l'agent, puis votre premier numéro actif ; passezfrompour choisir une ligne spécifique que vous possédez.- Les destinations internationales suivent les règles d'appels internationaux habituelles de votre espace de travail — voir Appels internationaux et limites.
- Lorsque l'appel se termine, il apparaît sur la chronologie du contact dans votre boîte de réception avec un enregistrement, une transcription et un résumé — la même carte "L'agent IA a géré cet appel" qu'un appel IA entrant.
- Facturation : 100 crédits lorsque l'appel est répondu, gratuit pour les appels de moins de 15 secondes — et un appel qui n'est jamais répondu est toujours gratuit.
Vous pouvez prendre le relais à tout moment
Tout ce qui est fait via l'API correspond à l'état réel de votre compte — pas à un bac à sable de développeur séparé. L'agent que votre code publie est celui de l'écran Agent IA ; le numéro qu'il connecte se trouve dans Paramètres → Numéros ; les appels qu'il passe arrivent dans votre boîte de réception partagée. Cela signifie que vous pouvez intervenir quand vous le souhaitez : modifier le message d'accueil dans l'application, répondre vous-même dans une conversation, ou cliquer sur les puces de routage d'un numéro pour renvoyer les appels à votre équipe — sans API.
Depuis un assistant IA (MCP)
Les assistants IA connectés obtiennent les mêmes pouvoirs que les outils MCP : get_agent, configure_agent (passez publish: true pour mettre en ligne en une seule étape), connect_agent_to_number, et place_call. Voir Connecter les outils IA avec MCP.
Mode test
Avec une clé ody_test_…, POST /calls renvoie un appel simulé (un ID sim_…, rien n'est composé, aucun crédit n'est utilisé) et POST /agent/publish est simulé (votre configuration reste un brouillon). Les enregistrements de brouillons via PATCH /agent sont réels pour les deux types de clés. Voir Développer en toute sécurité avec le mode test.
Articles connexes
Questions fréquemment posées
Combien coûtent les appels IA sortants ?
Le même prix que les appels entrants répondus par l'IA : 100 crédits IA par appel répondu, et les appels de moins de 15 secondes sont gratuits. Un appel qui n'est jamais répondu ne coûte rien.
Qu'est-ce qui est requis avant de pouvoir passer un appel ?
Un forfait actif, un agent IA publié et activé, et au moins un numéro actif. Ody compose à partir de votre numéro connecté à l'agent, sauf si vous spécifiez un numéro d'expéditeur que vous possédez.
Puis-je prendre le relais de l'agent ?
À tout moment. Tout ce que l'API modifie correspond au même agent, aux mêmes numéros et aux mêmes conversations que vous voyez dans l'application — ouvrez-la pour modifier l'agent, répondre dans une conversation ou réacheminer le numéro vers votre équipe.