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

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.

Erste Einrichtung — ein Anruf, dann Calls

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

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

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	1–3 bei besetzt / keine Antwort / Mailbox. Standard 3.
retryDelayMinutes	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)

Eingehend ist nie eingeschränkt.

• Zeit (an) — 09:00–21:00 Uhr in der Ortszeit des Ziellandes. Außerhalb dessen wird der Anruf blockiert oder geplant. Umgehung: overrideTimeRestriction: true.
• Tag (an) — Wochenenden / Feiertage können je nach Zielland blockiert sein. Umgehung: overrideDayRestriction: true.
• Anti-Belästigung (aus, es sei denn, Sie senden useAntiHarassmentProtection: true) — max. 3 erfolgreiche und 3 fehlgeschlagene Anrufe pro Nummer pro Tag, 1 Stunde zwischen erfolgreichen Anrufen, max. 5 erfolgreiche pro Woche, kein doppelter aktiver/geplanter Anruf. Kampagnen-Allowed test numbers umgehen dies.

Das Umgehen von Zeit- oder Tagesregeln kann lokale Gesetze brechen. Aktivieren Sie Anti-Belästigung für jeden Job mit wiederholtem Kontakt.

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.
weekly_call_limit_reached	5 erfolgreiche Anrufe diese Woche.
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

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

• 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.

Fehlerbehebung

fromNumber hat früher funktioniert

Der öffentliche Body ist sipTrunkId oder voipPhoneId. Senden Sie die Trunk-ID von Telephony → Trunks.

Ich habe jetzt gepostet und scheduled: true erhalten

Zeit- oder Tagesbeschränkung. Warten Sie auf das Fenster, oder setzen Sie overrideTimeRestriction / overrideDayRestriction nur, wenn Sie dazu berechtigt sind.

Bauen Sie etwas?

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

API-REFERENZ

api.voicelogica.ai/api-docs

ENTWICKLER

developers@voicelogica.ai

SUPPORT

support@voicelogica.ai