# API Ein ausgehender Anruf aus Ihrem System — ein CRM-Event, ein Formular, ein Rückruf bei verpasstem Anruf. Eine Liste nach Zeitplan ist [Campaigns](https://docs.voicelogica.ai/de/outbound-calls/campaigns/), nicht dieser Endpunkt. Die [Outgoing](https://docs.voicelogica.ai/de/outbound-calls/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](https://docs.voicelogica.ai/de/getting-started/api-keys/) mit der **Calls**-Gruppe. 3. Ein Trunk (oder VoIP-Telefon) zum Rauswählen — [Ihr eigener Carrier](https://docs.voicelogica.ai/de/telephony/your-own-carrier/) / [Voice Logica-Nummern](https://docs.voicelogica.ai/de/telephony/voice-logica-numbers/). 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 ``` ```http 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):** ```bash 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 *Ziel*landes. 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": "", "reason": "" }`. | 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 ```typescript 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: ```json { "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](https://docs.voicelogica.ai/de/outbound-calls/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](mailto:developers@voicelogica.ai) — zusätzliche Testguthaben und Hilfe bei der Integration. - API-REFERENZ [api.voicelogica.ai/api-docs](https://api.voicelogica.ai/api-docs) - ENTWICKLER [developers@voicelogica.ai](mailto:developers@voicelogica.ai) - SUPPORT [support@voicelogica.ai](mailto:support@voicelogica.ai)