# API

Μία outbound κλήση από το σύστημά σας — γεγονός CRM, φόρμα, επιστροφή χαμένης κλήσης. Μια λίστα σε πρόγραμμα είναι [Campaigns](https://docs.voicelogica.ai/el/outbound-calls/campaigns/), όχι αυτό το endpoint.

Οι ρυθμίσεις [Outgoing](https://docs.voicelogica.ai/el/outbound-calls/outgoing/) του agent εξακολουθούν να ισχύουν. Αυτό το αίτημα επιλέγει τον αριθμό, τον agent και προαιρετικό επιπλέον πλαίσιο για *αυτήν* την κλήση.

## Πριν καλέσετε

1. Το πρόγραμμα περιλαμβάνει **Allow Outbound Calls**.
2. [Κλειδί API](https://docs.voicelogica.ai/el/getting-started/api-keys/) με την ομάδα **Calls**.
3. Trunk (ή VoIP phone) από το οποίο να καλέσετε — [Your own carrier](https://docs.voicelogica.ai/el/telephony/your-own-carrier/) / [Voice Logica numbers](https://docs.voicelogica.ai/el/telephony/voice-logica-numbers/).
4. Το **agent id** — από το URL agent στο **My Agents**, ή **Copy** σε γραμμή εκστρατείας.

## Πρώτη ρύθμιση — μία κλήση, στη συνέχεια Calls

```
POST https://api.voicelogica.ai/api/v1/phones/calls/initiate-call
```

```http
x-api-key: YOUR_API_KEY
Content-Type: application/json
```

Resellers: προαιρετικό `x-company-id` για ενέργεια σε θυγατρική. Χωρίς αυτό, χρησιμοποιείται η δική εταιρεία του κλειδιού.

Στείλτε **`destinationNumber`** και **`agentId`**. Στείλτε **`sipTrunkId`** ή **`voipPhoneId`** εκτός αν η εταιρεία έχει ήδη outbound route / default trunk που μπορεί να μεταφέρει την κλήση — αν δεν σταλεί κανένα και κανένα trunk δεν μπορεί να επιλυθεί, το API επιστρέφει ότι δεν προσδιορίστηκε ενεργό SIP trunk ή VoIP phone.

**Trunk (συνήθως):**

```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 phone id** εξακολουθεί να λειτουργεί — ο server το επιλύει σε trunk.

Επιτυχία είναι `{ "callId": "..." }`. Αν ο προορισμός είναι εκτός 09:00–21:00 τοπικής ώρας, μπορεί να λάβετε `"scheduled": true` συν `scheduleTime` και `reason`. Ανοίξτε τα **Calls** και ακούστε.

`destinationNumber` σε E.164 (`+14155552671`).

## Τι μπορείτε να στείλετε

**Απαιτούμενα για AI outbound κλήση**

| Πεδίο | Τι κάνει |
|-------|----------------|
| `destinationNumber` | Αριθμός για κλήση. |
| `agentId` | Agent που μιλάει. Απαιτείται για AI outbound· προαιρετικό μόνο για `isInternalCall`. |

**Πηγή κλήσης — στείλτε ένα ή βασιστείτε στην προεπιλογή outbound εταιρείας**

| Πεδίο | Τι κάνει |
|-------|----------------|
| `sipTrunkId` | Trunk από **Telephony → Trunks**. Προτιμήστε αυτό. |
| `voipPhoneId` | Legacy line id. Επιλύεται σε trunk. |
| `callerId` | E.164 ή SIP URI που εμφανίζεται στον παραλήπτη. Πρέπει να είναι αριθμός που το trunk επιτρέπεται να παρουσιάσει. |

**Μόνο αυτή η κλήση**

| Πεδίο | Τι κάνει |
|-------|----------------|
| `contextForAi` | Προστίθεται στο system prompt για αυτήν την κλήση. |
| `dynamicVariables` | Ζεύγη κλειδιού/τιμής string που μπορεί να χρησιμοποιήσει το prompt (`{{customer_name}}`). |
| `superVariables` | Πληκτρολογημένες τιμές: `{ placeholder, value, type }` — `text` / `number` / `boolean` / `date` / `time`. |
| `metadata` | Η παρακολούθησή σας. Αποθηκεύεται στην κλήση. Κλειδιά που ξεκινούν με `scenario_` αφαιρούνται. |
| `emailAddress` | Πού να σταλεί η περίληψη / εγγραφή. |
| `welcomeMessageOverride` | Ειπώνεται αντί του χαιρετισμού agent. |
| `isWelcomeMessageAIGenerated` | Το AI γράφει τον χαιρετισμό για αυτήν την κλήση. |
| `scheduledAt` | Ημερομηνία ISO. Κλήση αργότερα αντί τώρα. |
| `maxRetries` | 1–3 αν απασχολημένος / καμία απάντηση / voicemail. Προεπιλογή 3. |
| `retryDelayMinutes` | 30–1440. Προεπιλογή 30. |
| `additionalPhoneNumbers` | Επιπλέον αριθμοί στο ίδιο αίτημα. |

Μην στέλνετε `fromNumber`. Το δημόσιο συμβόλαιο είναι `sipTrunkId` / `voipPhoneId`.

## Προστασίες (outbound μόνο)

Το inbound δεν περιορίζεται ποτέ.

- **Time** (on) — 09:00–21:00 στην τοπική ώρα της χώρας *προορισμού*. Εκτός αυτού, η κλήση μπλοκάρεται ή προγραμματίζεται. Παράκαμψη: `overrideTimeRestriction: true`.
- **Day** (on) — τα Σαββατοκύριακα / αργίες μπορεί να μπλοκαριστούν ανά χώρα προορισμού. Παράκαμψη: `overrideDayRestriction: true`.
- **Anti-harassment** (off εκτός αν στείλετε `useAntiHarassmentProtection: true`) — max 3 επιτυχημένες και 3 αποτυχημένες κλήσεις ανά αριθμό ανά ημέρα, 1 ώρα μεταξύ επιτυχημένων κλήσεων, max 5 επιτυχημένες ανά εβδομάδα, καμία διπλή ενεργή/προγραμματισμένη κλήση. Το **Allowed test numbers** εκστρατείας παρακάμπτει αυτό.

Η παράκαμψη κανόνων ώρας ή ημέρας μπορεί να σπάσει τοπικό νόμο. Ενεργοποιήστε anti-harassment για οποιαδήποτε δουλειά επαναλαμβανόμενης επαφής.

## Αν αποτύχει

Το body είναι `{ "error": "<code>", "reason": "<message>" }`.

| Κωδικός | Σημασία |
|------|---------|
| `call_already_in_progress` | Ζωντανή ή προγραμματισμένη κλήση σε αυτόν τον αριθμό υπάρχει ήδη. |
| `agent_not_found` / `voip_phone_not_found` | Λάθος id. |
| `daily_call_limit_reached` | 3 επιτυχημένες κλήσεις σε αυτόν τον αριθμό σήμερα (anti-harassment). |
| `failed_call_limit_reached` | 3 αποτυχημένες προσπάθειες σήμερα. |
| `cooldown_period_active` | Περιμένετε 1 ώρα μετά από επιτυχημένη κλήση σε αυτόν τον αριθμό. |
| `weekly_call_limit_reached` | 5 επιτυχημένες κλήσεις αυτή την εβδομάδα. |
| `call_already_scheduled` / `failed_to_schedule_call` | Σύγκρουση προγράμματος. |
| `callee_opted_out` | Αυτός ο αριθμός ζήτησε να μην κληθεί ξανά. |
| `insufficient_credits` / `no_seconds_available` / `no_channels_available` / `no_concurrent_calls_available` | Πρόγραμμα / πιστώσεις. |
| `maximum_authentication_attempts_exceeded` | Τηλέφωνο απενεργοποιήθηκε μετά από επαναλαμβανόμενες αποτυχίες auth. |

402 είναι χρέωση. 400 είναι λάθος αίτημα ή προστασία. 500 είναι ο calls server — επαναλάβετε αργότερα.

## Παράδειγμα

```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: 'Customer asked about order 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);
```

Πρόγραμμα + επαναλήψεις:

```json
{
  "destinationNumber": "+14155552671",
  "agentId": "your_agent_id",
  "sipTrunkId": "your_sip_trunk_id",
  "scheduledAt": "2026-09-16T14:30:00Z",
  "maxRetries": 2,
  "retryDelayMinutes": 120
}
```

Το `scheduledAt` μετατρέπεται στη ζώνη της χώρας προορισμού. Οι προστασίες εξακολουθούν να ισχύουν εκτός αν τις παρακάμψετε.

## Τι μοιάζει "σπασμένο"

- 400 "no active SIP trunk" — στείλτε `sipTrunkId`, ή προσθέστε trunk με αριθμούς και προεπιλογή outbound.
- `scheduled: true` όταν αναμενόταν τώρα — η τοπική ώρα προορισμού είναι εκτός 09:00–21:00.
- Ο agent μιλάει πάνω στο "hello" — [Outgoing](https://docs.voicelogica.ai/el/outbound-calls/outgoing/) **Who speaks first**, όχι αυτό το payload.
- Κλήση που λείπει στα **Calls** — λάθος εταιρεία (`x-company-id`), ή το αίτημα δεν επέστρεψε ποτέ `callId`.

## Αντιμετώπιση προβλημάτων

**Το fromNumber λειτουργούσε**

Το δημόσιο body είναι `sipTrunkId` ή `voipPhoneId`. Στείλτε το trunk id από **Telephony → Trunks**.

**Πόσταρα τώρα και πήρα scheduled: true**

Περιορισμός ώρας ή ημέρας. Περιμένετε το παράθυρο ή ορίστε `overrideTimeRestriction` / `overrideDayRestriction` μόνο αν επιτρέπεται.

## Χτίζετε κάτι;

Γράψτε [developers@voicelogica.ai](mailto:developers@voicelogica.ai) — επιπλέον πιστώσεις δοκιμής και βοήθεια στην ενοποίηση.

- API REFERENCE [api.voicelogica.ai/api-docs](https://api.voicelogica.ai/api-docs)
- DEVELOPERS [developers@voicelogica.ai](mailto:developers@voicelogica.ai)
- SUPPORT [support@voicelogica.ai](mailto:support@voicelogica.ai)