Zum Inhalt springen
DE
App öffnen

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

5 Min. Lesezeit
Als Markdown kopieren
Als Markdown ansehenDie rohe .md-Datei öffnen.md

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.

  1. Der Plan enthält Allow Outbound Calls.
  2. API-Schlüssel mit der Calls-Gruppe.
  3. Ein Trunk (oder VoIP-Telefon) zum Rauswählen — Ihr eigener Carrier / Voice Logica-Nummern.
  4. Die Agent-ID — aus der Agent-URL unter My Agents, oder Copy auf einer Kampagnenzeile.
POST https://api.voicelogica.ai/api/v1/phones/calls/initiate-call
x-api-key: YOUR_API_KEY
Content-Type: application/json

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

Terminal-Fenster
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).

Erforderlich für einen KI-Ausgehendanruf

FeldWas es macht
destinationNumberAnzurufende Nummer.
agentIdAgent, 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

FeldWas es macht
sipTrunkIdTrunk von Telephony → Trunks. Bevorzugen Sie dies.
voipPhoneIdLegacy-Leitungs-ID. Wird zu einem Trunk aufgelöst.
callerIdE.164 oder SIP-URI, die dem Empfänger angezeigt wird. Muss eine Nummer sein, die der Trunk präsentieren darf.

Nur dieser Anruf

FeldWas es macht
contextForAiWird für diesen Anruf an den System-Prompt angehängt.
dynamicVariablesZeichenketten-Schlüssel/Wert-Paare, die der Prompt verwenden kann ({{customer_name}}).
superVariablesTypisierte Werte: { placeholder, value, type } — text / number / boolean / date / time.
metadataIhr Tracking. Auf dem Anruf gespeichert. Schlüssel, die mit scenario_ beginnen, werden entfernt.
emailAddressWohin Zusammenfassung / Aufzeichnung gesendet werden.
welcomeMessageOverrideWird anstelle der Agent-Begrüßung gesprochen.
isWelcomeMessageAIGeneratedKI schreibt die Begrüßung für diesen Anruf.
scheduledAtISO-Datum. Später anrufen statt jetzt.
maxRetriesAnrufe 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.
retryDelayMinutesMinuten zwischen diesen Anrufen: 30–1440, Standard 30.
additionalPhoneNumbersZusätzliche Nummern auf derselben Anfrage.

Senden Sie nicht fromNumber. Der öffentliche Vertrag ist sipTrunkId / voipPhoneId.

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.

Der Body ist { "error": "<code>", "reason": "<message>" }.

CodeBedeutung
call_already_in_progressEin aktiver oder geplanter Anruf an diese Nummer existiert bereits.
agent_not_found / voip_phone_not_foundSchlechte ID.
daily_call_limit_reached3 erfolgreiche Anrufe an diese Nummer heute (Anti-Belästigung).
failed_call_limit_reached3 fehlgeschlagene Versuche heute.
cooldown_period_active1 Stunde nach einem erfolgreichen Anruf an diese Nummer warten.
call_already_scheduled / failed_to_schedule_callPlanungskonflikt.
callee_opted_outDiese Nummer hat gebeten, nicht mehr angerufen zu werden.
insufficient_credits / no_seconds_available / no_channels_available / no_concurrent_calls_availablePlan / Guthaben.
maximum_authentication_attempts_exceededTelefon nach wiederholten Auth-Fehlern deaktiviert.

402 ist Abrechnung. 400 ist eine fehlerhafte Anfrage oder ein Schutz. 500 ist der Anrufserver — später erneut versuchen.

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.

  • 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 eine callId zurückgegeben.
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.

Schreiben Sie an developers@voicelogica.ai — zusätzliche Testguthaben und Hilfe bei der Integration.