For AI assistants: this page as plain markdown is at https://docs.voicelogica.ai/raw/fr/outbound-calls/api.md, and https://docs.voicelogica.ai/llms.txt lists the docs by topic, one file each, small enough to read whole. Read those rather than this HTML page.
API
Un appel sortant depuis votre système — un événement CRM, un formulaire, un rappel d’appel manqué. Une liste selon un calendrier est Campaigns, pas ce point de terminaison.
Les paramètres Outgoing de l’agent s’appliquent toujours. Cette requête choisit le numéro, l’agent et le contexte supplémentaire facultatif pour cet appel.
Avant d’appeler
Section intitulée « Avant d’appeler »- Le plan inclut Allow Outbound Calls.
- Clé API avec le groupe Calls.
- Un trunk (ou téléphone VoIP) pour appeler depuis — Votre propre opérateur / Numéros Voice Logica.
- L’id de l’agent — depuis l’URL de l’agent sur My Agents, ou Copy sur une ligne de campagne.
Première configuration — un appel, puis Calls
Section intitulée « Première configuration — un appel, puis Calls »POST https://api.voicelogica.ai/api/v1/phones/calls/initiate-callx-api-key: YOUR_API_KEYContent-Type: application/jsonRevendeurs : x-company-id facultatif pour agir sur une filiale. Sans lui, la propre entreprise de la clé est utilisée.
Envoyez destinationNumber et agentId. Envoyez sipTrunkId ou voipPhoneId sauf si l’entreprise a déjà une route sortante / un trunk par défaut qui peut porter l’appel — si aucun n’est envoyé et qu’aucun trunk ne peut être résolu, l’API retourne qu’aucun trunk SIP actif ou téléphone VoIP n’a été spécifié.
Trunk (habituel) :
curl -X POST https://api.voicelogica.ai/api/v1/phones/calls/initiate-call \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sipTrunkId": "your_sip_trunk_id", "destinationNumber": "+14155552671", "agentId": "your_agent_id" }'VoIP phone id fonctionne toujours — le serveur le résout en trunk.
Le succès est { "callId": "..." }. Si la destination est en dehors de 09h00–21h00 heure locale, vous pouvez obtenir "scheduled": true plus scheduleTime et reason. Ouvrez Calls et écoutez.
destinationNumber en E.164 (+14155552671).
Ce que vous pouvez envoyer
Section intitulée « Ce que vous pouvez envoyer »Requis pour un appel sortant IA
| Champ | Ce qu’il fait |
|---|---|
destinationNumber | Numéro à appeler. |
agentId | Agent qui parle. Requis pour les appels sortants IA ; facultatif uniquement pour isInternalCall. |
Source de l’appel — envoyez-en un, ou comptez sur le défaut sortant de l’entreprise
| Champ | Ce qu’il fait |
|---|---|
sipTrunkId | Trunk depuis Telephony → Trunks. Préférez celui-ci. |
voipPhoneId | Id de ligne hérité. Résolu en trunk. |
callerId | E.164 ou URI SIP montré au destinataire. Doit être un numéro que ce trunk est autorisé à présenter. |
Cet appel uniquement
| Champ | Ce qu’il fait |
|---|---|
contextForAi | Ajouté au prompt système pour cet appel. |
dynamicVariables | Paires clé/valeur de chaînes que le prompt peut utiliser ({{customer_name}}). |
superVariables | Valeurs typées : { placeholder, value, type } — text / number / boolean / date / time. |
metadata | Votre suivi. Stocké sur l’appel. Les clés commençant par scenario_ sont supprimées. |
emailAddress | Où envoyer le résumé / l’enregistrement. |
welcomeMessageOverride | Énoncé à la place du message d’accueil de l’agent. |
isWelcomeMessageAIGenerated | L’IA écrit le message d’accueil pour cet appel. |
scheduledAt | Date ISO. Appeler plus tard au lieu de maintenant. |
maxRetries | Appels au total, le premier compris : 1–3, défaut 3. 3 = le premier appel plus jusqu’à 2 nouvelles tentatives ; 0 ou 1 = aucune nouvelle tentative. Nouvelle tentative si la ligne est occupée, sans réponse, sur messagerie vocale ou en échec. |
retryDelayMinutes | Minutes entre ces appels : 30–1440, défaut 30. |
additionalPhoneNumbers | Numéros supplémentaires sur la même requête. |
N’envoyez pas fromNumber. Le contrat public est sipTrunkId / voipPhoneId.
Protections (sortant uniquement)
Section intitulée « Protections (sortant uniquement) »L’entrant n’est jamais restreint.
- Time (activé) — 09h00–21h00 à l’heure du pays de votre entreprise. En dehors, l’appel est programmé pour la prochaine heure autorisée. Contournement :
overrideTimeRestriction: true. - Day (activé) — les week-ends / jours fériés peuvent être bloqués par le pays de destination. Contournement :
overrideDayRestriction: true. - Anti-harcèlement (activé sauf si vous envoyez
useAntiHarassmentProtection: false) — par numéro et par jour : max 3 appels aboutis et 3 échecs, 1 heure entre les appels aboutis, pas d’appel actif/programmé en double. Le jour repart à minuit UTC. Allowed test numbers de la campagne contourne cela. Toutes les règles : Call limits.
Contourner les règles de temps ou de jour peut enfreindre la loi locale. Gardez l’anti-harcèlement activé pour toute personne qui n’a pas demandé les appels.
Si cela échoue
Section intitulée « Si cela échoue »Le corps est { "error": "<code>", "reason": "<message>" }.
| Code | Signification |
|---|---|
call_already_in_progress | Un appel en direct ou programmé vers ce numéro existe déjà. |
agent_not_found / voip_phone_not_found | Mauvais id. |
daily_call_limit_reached | 3 appels réussis vers ce numéro aujourd’hui (anti-harcèlement). |
failed_call_limit_reached | 3 tentatives échouées aujourd’hui. |
cooldown_period_active | Attendez 1 heure après un appel réussi vers ce numéro. |
call_already_scheduled / failed_to_schedule_call | Conflit de calendrier. |
callee_opted_out | Ce numéro a demandé à ne plus être appelé. |
insufficient_credits / no_seconds_available / no_channels_available / no_concurrent_calls_available | Plan / crédits. |
maximum_authentication_attempts_exceeded | Téléphone désactivé après des échecs d’authentification répétés. |
402 est facturation. 400 est une mauvaise requête ou une protection. 500 est le serveur d’appels — réessayez plus tard.
const response = await fetch('https://api.voicelogica.ai/api/v1/phones/calls/initiate-call', { method: 'POST', headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ destinationNumber: '+14155552671', agentId: 'your_agent_id', sipTrunkId: 'your_sip_trunk_id', contextForAi: 'Le client a posé une question sur la commande ORD123', dynamicVariables: { customer_name: 'Ada', order_id: 'ORD123' }, useAntiHarassmentProtection: true, }),});const result = await response.json();if (result.callId) console.log(result.callId);else console.error(result.error, result.reason);Calendrier + tentatives :
{ "destinationNumber": "+14155552671", "agentId": "your_agent_id", "sipTrunkId": "your_sip_trunk_id", "scheduledAt": "2026-09-16T14:30:00Z", "maxRetries": 2, "retryDelayMinutes": 120}scheduledAt est converti dans le fuseau du pays de destination. Les protections s’appliquent toujours sauf si vous les contournez.
À quoi ressemble “cassé”
Section intitulée « À quoi ressemble “cassé” »- 400 “no active SIP trunk” — envoyez
sipTrunkId, ou ajoutez un trunk avec des numéros et un défaut sortant. scheduled: truequand vous attendiez maintenant — l’heure locale de la destination est en dehors de 09h00–21h00.- L’agent parle par-dessus “bonjour” — Outgoing Who speaks first, pas cette charge utile.
- Appel manquant sur Calls — mauvaise entreprise (
x-company-id), ou la requête n’a jamais retourné decallId.
Dépannage
Section intitulée « Dépannage »Pourquoi fromNumber ne fonctionne-t-il plus dans l'API d'appels sortants ?
Le corps public de la requête utilise sipTrunkId ou voipPhoneId. Envoyez l’id du trunk indiqué dans Telephony → Trunks.
J'ai lancé un appel par l'API pour maintenant, pourquoi la réponse indique-t-elle scheduled: true ?
Une restriction d’heure ou de jour s’applique. Attendez la fenêtre autorisée, ou définissez overrideTimeRestriction / overrideDayRestriction seulement si vous êtes autorisé à le faire.
Vous construisez quelque chose ?
Section intitulée « Vous construisez quelque chose ? »Écrivez à developers@voicelogica.ai — crédits de test supplémentaires et aide sur l’intégration.
