For AI assistants: this page as plain markdown is at https://docs.voicelogica.ai/raw/de/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
Ein ausgehender Anruf aus Ihrem System — ein CRM-Event, ein Formular, ein Rückruf bei verpasstem Anruf. Eine Liste nach Zeitplan ist Campaigns, nicht dieser Endpunkt.
Die Outgoing-Einstellungen des Agents gelten weiterhin. Diese Anfrage wählt die Nummer, den Agent und optionalen zusätzlichen Kontext für diesen Anruf.
Bevor Sie anrufen
Abschnitt betitelt „Bevor Sie anrufen“- Der Plan enthält Allow Outbound Calls.
- API-Schlüssel mit der Calls-Gruppe.
- Ein Trunk (oder VoIP-Telefon) zum Rauswählen — Ihr eigener Carrier / Voice Logica-Nummern.
- Die Agent-ID — aus der Agent-URL unter My Agents, oder Copy auf einer Kampagnenzeile.
Erste Einrichtung — ein Anruf, dann Calls
Abschnitt betitelt „Erste Einrichtung — ein Anruf, dann Calls“POST https://api.voicelogica.ai/api/v1/phones/calls/initiate-callx-api-key: YOUR_API_KEYContent-Type: application/jsonReseller: optionaler x-company-id zum Handeln für eine Tochtergesellschaft. Ohne ihn wird das eigene Unternehmen des Schlüssels verwendet.
Senden Sie destinationNumber und agentId. Senden Sie sipTrunkId oder voipPhoneId, es sei denn, das Unternehmen hat bereits eine ausgehende Route / Standard-Trunk, der den Anruf tragen kann — wenn keines gesendet wird und kein Trunk aufgelöst werden kann, gibt die API zurück, dass kein aktiver SIP-Trunk oder VoIP-Telefon angegeben wurde.
Trunk (üblich):
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-Telefon-ID funktioniert weiterhin — der Server löst sie zu einem Trunk auf.
Erfolg ist { "callId": "..." }. Wenn das Ziel außerhalb von 09:00–21:00 Uhr Ortszeit liegt, erhalten Sie möglicherweise "scheduled": true plus scheduleTime und reason. Öffnen Sie Calls und hören Sie zu.
destinationNumber in E.164 (+14155552671).
Was Sie senden können
Abschnitt betitelt „Was Sie senden können“Erforderlich für einen KI-Ausgehendanruf
| Feld | Was es macht |
|---|---|
destinationNumber | Anzurufende Nummer. |
agentId | Agent, der spricht. Erforderlich für KI-Ausgehend; optional nur für isInternalCall. |
Anrufquelle — senden Sie eine oder verlassen Sie sich auf die Standard-Ausgehend des Unternehmens
| Feld | Was es macht |
|---|---|
sipTrunkId | Trunk von Telephony → Trunks. Bevorzugen Sie dies. |
voipPhoneId | Legacy-Leitungs-ID. Wird zu einem Trunk aufgelöst. |
callerId | E.164 oder SIP-URI, die dem Empfänger angezeigt wird. Muss eine Nummer sein, die der Trunk präsentieren darf. |
Nur dieser Anruf
| Feld | Was es macht |
|---|---|
contextForAi | Wird für diesen Anruf an den System-Prompt angehängt. |
dynamicVariables | Zeichenketten-Schlüssel/Wert-Paare, die der Prompt verwenden kann ({{customer_name}}). |
superVariables | Typisierte Werte: { placeholder, value, type } — text / number / boolean / date / time. |
metadata | Ihr Tracking. Auf dem Anruf gespeichert. Schlüssel, die mit scenario_ beginnen, werden entfernt. |
emailAddress | Wohin Zusammenfassung / Aufzeichnung gesendet werden. |
welcomeMessageOverride | Wird anstelle der Agent-Begrüßung gesprochen. |
isWelcomeMessageAIGenerated | KI schreibt die Begrüßung für diesen Anruf. |
scheduledAt | ISO-Datum. Später anrufen statt jetzt. |
maxRetries | Anrufe insgesamt, der erste eingeschlossen: 1–3, Standard 3. 3 = der erste Anruf plus bis zu 2 Wiederholungen; 0 oder 1 = keine Wiederholung. Wiederholt wird bei besetzt, keiner Antwort, Mailbox oder fehlgeschlagenem Anruf. |
retryDelayMinutes | Minuten zwischen diesen Anrufen: 30–1440, Standard 30. |
additionalPhoneNumbers | Zusätzliche Nummern auf derselben Anfrage. |
Senden Sie nicht fromNumber. Der öffentliche Vertrag ist sipTrunkId / voipPhoneId.
Schutzmaßnahmen (nur ausgehend)
Abschnitt betitelt „Schutzmaßnahmen (nur ausgehend)“Eingehend ist nie eingeschränkt.
- Zeit (an) — 09:00–21:00 Uhr in der Zeit des Landes Ihres Unternehmens. Außerhalb dessen wird der Anruf für die nächste erlaubte Zeit geplant. Umgehen:
overrideTimeRestriction: true. - Tag (an) — Wochenenden / Feiertage können je nach Zielland blockiert sein. Umgehung:
overrideDayRestriction: true. - Anti-Belästigung (an, es sei denn, Sie senden
useAntiHarassmentProtection: false) — pro Nummer pro Tag: max. 3 zustande gekommene und 3 fehlgeschlagene Anrufe, 1 Stunde zwischen zustande gekommenen Anrufen, kein doppelter aktiver/geplanter Anruf. Der Tag beginnt um Mitternacht UTC. Kampagnen-Allowed test numbers umgehen dies. Alle Regeln: Call limits.
Das Umgehen von Zeit- oder Tagesregeln kann lokale Gesetze brechen. Lassen Sie Anti-Belästigung für alle an, die die Anrufe nicht angefragt haben.
Wenn es fehlschlägt
Abschnitt betitelt „Wenn es fehlschlägt“Der Body ist { "error": "<code>", "reason": "<message>" }.
| Code | Bedeutung |
|---|---|
call_already_in_progress | Ein aktiver oder geplanter Anruf an diese Nummer existiert bereits. |
agent_not_found / voip_phone_not_found | Schlechte ID. |
daily_call_limit_reached | 3 erfolgreiche Anrufe an diese Nummer heute (Anti-Belästigung). |
failed_call_limit_reached | 3 fehlgeschlagene Versuche heute. |
cooldown_period_active | 1 Stunde nach einem erfolgreichen Anruf an diese Nummer warten. |
call_already_scheduled / failed_to_schedule_call | Planungskonflikt. |
callee_opted_out | Diese Nummer hat gebeten, nicht mehr angerufen zu werden. |
insufficient_credits / no_seconds_available / no_channels_available / no_concurrent_calls_available | Plan / Guthaben. |
maximum_authentication_attempts_exceeded | Telefon nach wiederholten Auth-Fehlern deaktiviert. |
402 ist Abrechnung. 400 ist eine fehlerhafte Anfrage oder ein Schutz. 500 ist der Anrufserver — später erneut versuchen.
Beispiel
Abschnitt betitelt „Beispiel“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: 'Kunde hat nach Bestellung ORD123 gefragt', 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);Planung + Wiederholungen:
{ "destinationNumber": "+14155552671", "agentId": "your_agent_id", "sipTrunkId": "your_sip_trunk_id", "scheduledAt": "2026-09-16T14:30:00Z", "maxRetries": 2, "retryDelayMinutes": 120}scheduledAt wird in die Zone des Ziellandes konvertiert. Schutzmaßnahmen gelten weiterhin, es sei denn, Sie überschreiben sie.
Wie “kaputt” aussieht
Abschnitt betitelt „Wie “kaputt” aussieht“- 400 “no active SIP trunk” — senden Sie
sipTrunkId, oder fügen Sie einen Trunk mit Nummern und einem ausgehenden Standard hinzu. scheduled: true, wenn Sie jetzt erwartet haben — Ortszeit des Ziels liegt außerhalb von 09:00–21:00 Uhr.- Agent spricht über “Hallo” — Outgoing Who speaks first, nicht diese Payload.
- Anruf fehlt unter Calls — falsches Unternehmen (
x-company-id), oder die Anfrage hat nie einecallIdzurückgegeben.
Fehlerbehebung
Abschnitt betitelt „Fehlerbehebung“Warum funktioniert fromNumber beim API-Aufruf initiate-call nicht mehr?
Der öffentliche Request-Body erwartet sipTrunkId oder voipPhoneId. Senden Sie die Trunk-ID aus Telephony → Trunks.
Ich wollte über die API sofort anrufen – warum bekomme ich scheduled: true zurück?
Eine Zeit- oder Tagesbeschränkung greift, deshalb wurde der Anruf eingeplant. Warten Sie auf das Zeitfenster, oder setzen Sie overrideTimeRestriction / overrideDayRestriction, aber nur, wenn Sie dazu berechtigt sind.
Bauen Sie etwas?
Abschnitt betitelt „Bauen Sie etwas?“Schreiben Sie an developers@voicelogica.ai — zusätzliche Testguthaben und Hilfe bei der Integration.
