---
title: "Efectuați apeluri din Slack sau dintr-o aplicație de chat"
description: "Creați propriul bot pentru Slack, Teams sau chat web care inițiază apeluri, le urmărește în timp real, ghidează agentul vocal și răspunde la întrebările acestuia, folosind API-ul public."
---

Puteți controla un agent vocal din aplicația de chat pe care echipa dumneavoastră o folosește deja. Un mesaj
inițiază un apel. Apelul se desfășoară în direct într-un fir de discuție. Un răspuns în firul de discuție
direcționează agentul vocal. Când agentul vocal are nevoie de o decizie, vă întreabă acolo și
așteaptă răspunsul dumneavoastră.

ThunderPhone nu găzduiește acest bot pentru dumneavoastră. Dumneavoastră (sau agentul dumneavoastră de programare) creați un
server mic care conectează aplicația de chat la API-ul public. Această pagină prezintă
componentele. Sunt aceleași pentru Slack, Microsoft Teams, Discord sau o pagină web de chat privată;
exemplele folosesc Slack.

## Cum se integrează

| Faceți aceasta în chat | Botul dumneavoastră apelează | Ce se întâmplă |
|---|---|---|
| Trimiteți „Sunați Comcast și aflați ora estimată pentru remedierea întreruperii” | [`POST /v1/call`](/api-reference/outbound-calls) cu mesajul ca `context` | Agentul vocal apelează. Botul dumneavoastră deschide un fir de discuție pentru apel |
| Urmăriți firul de discuție | Primește webhook-uri [`telephony.turn`](/ro/webhooks/events) | Fiecare replică rostită de agentul vocal sau de cealaltă persoană apare în firul de discuție |
| Răspundeți în firul de discuție în timpul apelului | [`POST /v1/calls/{call_id}/whisper`](/api-reference/calls#whisper-to-the-agent) | Agentul vocal primește nota dumneavoastră în mod privat și acționează în consecință. Cealaltă persoană nu o aude niciodată |
| Răspundeți la întrebarea agentului vocal | [Endpointul dumneavoastră de instrument](/ro/guides/build-tool-integration) returnează răspunsul sau îl livrează ulterior cu [`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result) | Agentul vocal continuă apelul cu acesta; în modul de așteptare, cealaltă persoană aude între timp muzică de așteptare |
| Citiți rezultatul | Primește [`telephony.complete`](/ro/webhooks/events) | Botul dumneavoastră publică rezumatul și rezultatul |

Botul dumneavoastră păstrează o singură asociere: ce fir de discuție din chat aparține cărui `call_id`.

## Înainte de a începe

- **O cheie API**, păstrată pe serverul dumneavoastră și niciodată într-un browser sau în chat.
  Creați una în **Integrations → API keys** (consultați
  [Crearea unei chei API de server](/ro/guides/api-keys)).
- **Un număr cu apeluri efectuate activate și un agent vocal** pentru apeluri. Mesajul
  devine `context` pentru fiecare apel, astfel încât un singur agent vocal general gestionează fiecare sarcină.
- **Un server** care poate primi webhookuri, precum Railway, Fly.io, Render sau
  propriul dumneavoastră host.
- **Un endpoint webhook** care indică spre acel server și este abonat la
  `telephony.turn` și `telephony.complete`. Evenimentele de tură sunt trimise doar către
  endpointurile care le listează. Consultați [Webhookuri](/ro/webhooks/endpoints).
  Evenimentele de tură necesită activarea înregistrării apelurilor agentului vocal, iar
  `summary` de la finalul apelului necesită setarea **Generate a call summary** a agentului vocal; fără
  acestea, câmpurile respective rămân goale.
- **Propria aplicație de chat.** Pentru Slack, creați o aplicație în spațiul dumneavoastră de lucru la
  [api.slack.com/apps](https://api.slack.com/apps).

<Tip>
  Folosiți o aplicație Slack creată pentru propriul spațiu de lucru și primiți mesajele
  prin Events API de la Slack, în loc să citiți istoricul canalelor. Slack
  aplică limite stricte de citire aplicațiilor distribuite către alte spații de lucru în afara
  Marketplace-ului său; o aplicație pe care o creați pentru propriul spațiu de lucru nu este supusă
  acestora, iar evenimentele ajung la dumneavoastră pe măsură ce au loc, fără citiri. Permisiuni tipice
  pentru bot: `chat:write`, `app_mentions:read`, `im:history` (mesaje directe),
  `channels:history` și `groups:history` (răspunsuri în fire de discuție din
  canale publice și private în care se află botul). Abonați-vă la evenimentele botului
  `app_mention`, `message.im`, `message.channels` și `message.groups` și
  activați fila Mesaje din App Home, astfel încât persoanele să poată trimite mesaje directe botului.
</Tip>

## 1. Începeți un apel dintr-un mesaj

Când botul dumneavoastră primește un mesaj (un mesaj direct sau o mențiune @),
confirmați imediat solicitarea Slack (Slack reîncearcă orice solicitare care nu
este confirmată în 3 secunde) și efectuați restul în fundal. Verificați dacă
expeditorul are permisiunea de a iniția apeluri, apoi începeți apelul folosind
mesajul drept `context`:

```bash
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+18005550100",
    "agent_id":    12,
    "context":     "Matthew asked: get the outage ETA for account 4471. Wait on hold if needed.",
    "idempotency_key": "slack-D012AB3CD-1731000000.000100"
  }'
```

Salvați `call_id` returnat asociat cu firul Slack (`channel` plus `ts`-ul
mesajului) și răspundeți în fir („Se apelează…”). Construiți
`idempotency_key` din canal și `ts`-ul mesajului (un `ts` este unic numai în
canalul său), astfel încât un eveniment Slack reîncercat să nu inițieze un al
doilea apel. Dacă solicitarea numește o persoană în locul unui număr, botul
dumneavoastră caută mai întâi numărul. ThunderPhone apelează numai
`to_number` pe care îl trimiteți.

## 2. Urmăriți apelul în fir

Fiecare webhook `telephony.turn` conține `call_id`, vorbitorul (`role`:
`assistant` pentru agent, `user` pentru cealaltă persoană), `text` și
`position` al rândului de dialog. Identificați firul după `call_id` și
publicați rândul.

- **Verificați fiecare webhook** înainte de a acționa pe baza lui. Consultați
  [Verificarea semnăturilor webhook](/ro/guides/verify-webhook-signatures).
- **Eliminați duplicatele după `event_id` din plic și ordonați după `position`.**
  Livrarea are loc cel puțin o dată, iar rândurile de dialog pot sosi în altă ordine.
- **Grupați rândurile** dacă un apel aglomerat ar inunda firul; publicarea la
  fiecare câteva secunde se citește mai bine decât câte un mesaj pentru fiecare rând.

Când sosește `telephony.complete`, publicați modul în care s-a încheiat apelul
(`status` și `end_reason`), `summary` și orice date extrase, apoi închideți
firul. Consultați [Finalizarea apelului](/ro/webhooks/call-complete) pentru
câmpuri.

## 3. Direcționați apelul din fir

Când cineva răspunde în firul unui apel activ, trimiteți răspunsul ca mesaj
șoptit, cu excepția cazului în care agentul așteaptă răspunsul la o întrebare
(pasul 4), caz în care răspunsul este chiar răspunsul la întrebare:

```bash
curl -X POST https://api.thunderphone.com/v1/calls/987654321/whisper \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ask whether they can waive the late fee."}'
```

Agentul îl aude în privat și îl integrează în următorul său rând de dialog;
cealaltă persoană nu aude niciodată mesajul șoptit în sine. Un mesaj șoptit
are între 1 și 1000 de caractere. Un `409` înseamnă că apelul nu mai este
activ: comunicați în fir că apelul s-a încheiat.

## 4. Permiteți agentului să vă întrebe

Oferiți agentului un instrument, de exemplu `ask_owner`, cu un parametru
`question`, care apelează serverul dvs. Creați-l ca
[o conexiune API](/ro/guides/build-tool-integration) și conectați-l la agent.
Fiecare solicitare de instrument include apelul în antetul său
`X-ThunderPhone-Call-ID`.

Există trei modalități de a primi răspunsul înapoi.

**Mențineți apelul în așteptare (până la 10 minute).** Setați instrumentul în modul de așteptare: `spec.wait_mode`
`"hold"` și `spec.timeout` la maximum 600 de secunde (fără un timeout, o așteptare
durează 20 de secunde), prin
[API](/api-reference/integrations#timeout-and-wait-mode) sau cereți-i lui Zeus să
le seteze (editorii aplicației nu au încă niciunul dintre câmpuri). Endpointul dumneavoastră publică întrebarea în firul apelului și răspunde
imediat cu un rezultat în așteptare:

```json
{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}
```

Cealaltă persoană aude o replică de la agent, apoi muzică de așteptare. Într-un
meniu telefonic sau în mesageria vocală, agentul folosește în schimb actualizări rostite, iar un
agent full-duplex nu pune apelul în așteptare: primește răspunsul în așteptare ca rezultat. Când
răspunsul ajunge în fir, transmiteți-l cu
[`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result):

```bash
curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "q-C012AB3CD-1731000042.000300", "result": {"answer": "Yes, book Tuesday at 10."}}'
```

Muzica se estompează, iar agentul continuă cu răspunsul dvs. Dacă nimeni nu
răspunde înainte de `timeout`, agentul este informat că nu a venit niciun răspuns și îi oferă
celeilalte persoane pașii următori. Cât timp o întrebare este în așteptare pentru un apel,
următorul răspuns din firul său îi răspunde: transmiteți-l ca rezultat al instrumentului și
nu îl trimiteți și ca șoaptă (o șoaptă ajunge la agent numai după ce
instrumentul revine). Consultați
[Așteptări lungi](/ro/tools/overview).

**Așteptați în solicitare (până la 3 minute).** Endpointul dvs. publică întrebarea,
așteaptă un răspuns și îl returnează, de exemplu `{"answer": "Yes, book Tuesday at 10."}`.
Setați `spec.timeout` al instrumentului prin API, până la 180 de secunde (valoarea
implicită este 20). Oferiți endpointului dvs. propriul termen-limită cu câteva secunde mai scurt
(de exemplu, 170 de secunde), astfel încât, atunci când nimeni nu răspunde, să returneze totuși
ceva asupra căruia agentul poate acționa, de exemplu
`{"answer": null, "note": "No reply yet. Offer to take a message."}`. Un instrument
care atinge `timeout` ajunge la agent ca eroare, iar gazda dvs. trebuie
să mențină o solicitare deschisă atât timp. În timp ce așteaptă, agentul îi spune celeilalte
persoane că verifică, spune că încă lucrează după aproximativ 12 secunde, apoi
oferă o actualizare scurtă aproximativ la fiecare 15 secunde. Modul de așteptare funcționează
și aici: setați `spec.wait_mode` la `"hold"`, iar cealaltă persoană aude muzică
în locul actualizărilor.

**Răspundeți prin șoaptă.** Endpointul dvs. publică întrebarea și revine imediat,
de exemplu `{"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}`.
Când sosește răspunsul, trimiteți-l ca șoaptă (pasul 3), iar agentul
răspunde imediat la acesta. Folosiți această opțiune pentru răspunsuri care pot dura mai mult de
10 minute. Apelul nu este pus în așteptare: promptul dvs. ar trebui să îi spună
agentului ce să facă între timp, de exemplu să țină companie persoanei sau să ofere
să o sune înapoi.

În fiecare caz, precizați în promptul agentului când să folosească instrumentul și ce să îi
spună celeilalte persoane cât timp așteaptă:

```text
When you need Matthew's decision, use ask_owner with a short question.
Tell the person you're checking with Matthew and it may take a minute.
If there's no answer, offer to take a message or have Matthew call back.
```

## Limite de avut în vedere

- Endpointul dumneavoastră trebuie să răspundă în `timeout` al instrumentului, în cel mult **180 de secunde**. Un instrument în modul de așteptare poate menține apelul în așteptare până la **600 de secunde** cu un rezultat în curs.
- Cât timp un instrument așteaptă, agentul nu răspunde celeilalte persoane. În modul de așteptare, aceasta aude muzică; în caz contrar, actualizări vocale scurte.
- O șoaptă are cel mult **1000 de caractere**.
- Livrarea `telephony.turn` are loc cel puțin o dată și poate fi în altă ordine.

## Listă de verificare pentru securitate

- Păstrați cheia API pe serverul dumneavoastră.
- Verificați semnăturile ThunderPhone pentru webhookuri și solicitările de instrumente, precum și secretul de semnare Slack pentru solicitările Slack. Cele două semnături ThunderPhone folosesc secrete diferite: livrările prin webhook folosesc secretul propriu al endpointului webhook, iar solicitările de instrumente folosesc secretul webhook al organizației dumneavoastră din [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook).
- Decideți cine poate iniția apeluri: verificați ID-ul utilizatorului Slack înainte de a plasa un apel.
- Apelurile efectuate respectă aceleași reguli ca oricare altele. Consultați [Legile privind apelurile efectuate](/ro/guides/outbound-calling-laws).

## Construiți-l cu un agent de programare

Indicați agentului dumneavoastră de programare [serverul MCP pentru documentație](/ro/guides/docs-mcp) și această pagină și solicitați „un bot Slack pentru agentul meu ThunderPhone care urmează acest ghid”. Zeus, asistentul din aplicația ThunderPhone, poate configura partea agentului vocal (endpointul webhook, instrumentul și liniile de prompt) și poate scrie cod inițial pentru bot în chat.
