Aller au contenu
FR
Ouvrir l’app

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

6 min de lecture
Copier en Markdown
Voir en MarkdownOuvrir le fichier .md brut.md

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.

  1. Le plan inclut Allow Outbound Calls.
  2. Clé API avec le groupe Calls.
  3. Un trunk (ou téléphone VoIP) pour appeler depuis — Votre propre opérateur / Numéros Voice Logica.
  4. L’id de l’agent — depuis l’URL de l’agent sur My Agents, ou Copy sur une ligne de campagne.
POST https://api.voicelogica.ai/api/v1/phones/calls/initiate-call
x-api-key: YOUR_API_KEY
Content-Type: application/json

Revendeurs : 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) :

Fenêtre de terminal
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).

Requis pour un appel sortant IA

ChampCe qu’il fait
destinationNumberNuméro à appeler.
agentIdAgent 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

ChampCe qu’il fait
sipTrunkIdTrunk depuis Telephony → Trunks. Préférez celui-ci.
voipPhoneIdId de ligne hérité. Résolu en trunk.
callerIdE.164 ou URI SIP montré au destinataire. Doit être un numéro que ce trunk est autorisé à présenter.

Cet appel uniquement

ChampCe qu’il fait
contextForAiAjouté au prompt système pour cet appel.
dynamicVariablesPaires clé/valeur de chaînes que le prompt peut utiliser ({{customer_name}}).
superVariablesValeurs typées : { placeholder, value, type } — text / number / boolean / date / time.
metadataVotre suivi. Stocké sur l’appel. Les clés commençant par scenario_ sont supprimées.
emailAddressOù envoyer le résumé / l’enregistrement.
welcomeMessageOverrideÉnoncé à la place du message d’accueil de l’agent.
isWelcomeMessageAIGeneratedL’IA écrit le message d’accueil pour cet appel.
scheduledAtDate ISO. Appeler plus tard au lieu de maintenant.
maxRetriesAppels 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.
retryDelayMinutesMinutes entre ces appels : 30–1440, défaut 30.
additionalPhoneNumbersNuméros supplémentaires sur la même requête.

N’envoyez pas fromNumber. Le contrat public est sipTrunkId / voipPhoneId.

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.

Le corps est { "error": "<code>", "reason": "<message>" }.

CodeSignification
call_already_in_progressUn appel en direct ou programmé vers ce numéro existe déjà.
agent_not_found / voip_phone_not_foundMauvais id.
daily_call_limit_reached3 appels réussis vers ce numéro aujourd’hui (anti-harcèlement).
failed_call_limit_reached3 tentatives échouées aujourd’hui.
cooldown_period_activeAttendez 1 heure après un appel réussi vers ce numéro.
call_already_scheduled / failed_to_schedule_callConflit de calendrier.
callee_opted_outCe numéro a demandé à ne plus être appelé.
insufficient_credits / no_seconds_available / no_channels_available / no_concurrent_calls_availablePlan / crédits.
maximum_authentication_attempts_exceededTé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.

  • 400 “no active SIP trunk” — envoyez sipTrunkId, ou ajoutez un trunk avec des numéros et un défaut sortant.
  • scheduled: true quand 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é de callId.
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.

Écrivez à developers@voicelogica.ai — crédits de test supplémentaires et aide sur l’intégration.