Funcții personalizate #

Funcțiile personalizate permit botului tău AI să se conecteze la alte sisteme în timpul conversațiilor live. În loc să spună „Voi verifica și revin către tine”, botul poate căuta starea unei comenzi, poate verifica stocul sau poate crea o înregistrare în CRM-ul tău (sistemul de gestionare a relațiilor cu clienții - software-ul pe care îl folosești pentru a urmări clienții potențiali și clienții actuali, cum ar fi HubSpot sau Salesforce) - totul în timp real, în timp ce clientul așteaptă.

Funcții personalizate vs. Webhook-uri #

Acesta este cel mai frecvent punct de confuzie, așa că merită să clarificăm acest aspect înainte de a construi ceva.

Când să alegi ce: Dacă trebuie doar să anunți un alt sistem că s-a întâmplat ceva, folosește un webhook - un mesaj automat unidirecțional trimis către un alt sistem (vezi Setări → Integrări → Webhook-uri). Dacă botul trebuie să afle ceva de la un alt sistem înainte de a continua conversația, folosește o funcție personalizată.

Exemple de ce pot debloca funcțiile personalizate #

Deoarece răspunsul este transmis înapoi în conversație, funcțiile personalizate deschid posibilități pe care webhook-urile pur și simplu nu le pot oferi:

• Verificarea stocului în timp real în Shopify sau WooCommerce — Înainte de a oferi o ofertă unui client, botul verifică stocul în timp real și răspunde „Da, avem 12 bucăți mărimea M” în loc de „lăsați-mă să verific și revin”.
• Prețuri dinamice dintr-un Google Sheet — Echipa ta de vânzări actualizează prețurile într-un tabel; botul citește cel mai recent rând în timpul conversației și oferă prețul actual fără ca cineva să modifice configurația AI-ului.
• Agent de apelare Voice-AI — Când botul califică un lead, acesta declanșează un agent vocal (de exemplu, un apelant bazat pe ElevenLabs) pentru a suna lead-ul în câteva minute și confirmă clientului „grozav, așteptați-vă la un apel în următoarele 5 minute”.
• PDF cu ofertă personalizată, generat și trimis prin e-mail în timpul chat-ului — Botul colectează cerințele, apelează generatorul de oferte, primește un URL către PDF și îi spune clientului „Tocmai v-am trimis oferta prin e-mail — verificați căsuța poștală”.

Ce pot face funcțiile personalizate? #

Gândește-te la funcțiile personalizate ca la niște superputeri oferite botului tău, dincolo de simpla conversație. Iată exemple din lumea reală:

• Urmărirea comenzilor - Un client întreabă „Unde este comanda mea?”, iar botul verifică sistemul tău de e-commerce și răspunde cu starea livrării și link-ul de urmărire.
• Verificarea inventarului - „Aveți acest produs pe mărimea 10?” Botul verifică sistemul de stocuri și oferă un răspuns în timp real.
• Actualizări CRM - Când botul califică un lead, acesta creează sau actualizează automat o înregistrare în HubSpot, Salesforce sau orice alt CRM.
• Generarea de oferte - Botul colectează cerințele clientului și generează o ofertă personalizată din sistemul tău de prețuri.
• Programări - Botul creează o programare în sistemul tău extern de rezervări.
• Verificarea reducerilor - „Este valid acest cod de cupon?” Botul verifică și confirmă.
• Căutarea contului - Un client care revine este recunoscut automat, iar detaliile contului său sunt extrase.

Clientul nu vede niciodată ce se întâmplă în culise. El experimentează pur și simplu un bot capabil să răspundă la întrebări cu informații reale și actualizate.

Cum funcționează funcțiile personalizate (Versiunea simplă) #

Iată ce se întâmplă atunci când o funcție personalizată este declanșată în timpul unei conversații:

1. Clientul întreabă ceva care necesită date în timp real (de ex., „Unde este comanda mea?”)
2. Botul recunoaște că trebuie să utilizeze o funcție personalizată pentru a răspunde
3. Botul colectează orice informație lipsă de la client (de ex., „Care este numărul comenzii tale?”)
4. Platforma trimite o cerere către sistemul tău (site-ul tău, CRM sau orice alt instrument) cu detaliile relevante
5. Sistemul tău răspunde cu datele (de ex., starea comenzii, numărul de urmărire, data livrării)
6. Botul citește răspunsul și formulează un răspuns natural: „Comanda ta ORD-4582 a fost expediată și ar trebui să ajungă până vineri!”

Cât costă un apel de funcție personalizat #

Fiecare apel de funcție personalizat este facturat în funcție de nivelul de Calitate AI al Agentului tău:

Configurarea unei funcții personalizate (pas cu pas) #

1. În bara laterală principală, sub AI Studio, faceți clic pe Custom Functions.

2. Faceți clic pe butonul verde + Add Function (sau New function) din partea dreaptă sus.

Lista de funcții personalizate afișează un tabel cu următoarele coloane:

Acest lucru facilitează scanarea rapidă a funcțiilor și găsirea celei de care ai nevoie.

Pasul 1: Oferă-i un nume și o descriere #

Sfat: Fii foarte specific în descriere și scop. Cu cât ești mai clar cu privire la momentul în care ar trebui utilizată funcția, cu atât mai fiabil o va folosi botul la momentul potrivit.

Pasul 2: Configurează conexiunea #

Trebuie să spui aplicației unde să trimită cererea:

Ce metodă să alegi:

Dacă nu ești sigur pe care să o folosești, verifică cu dezvoltatorul tău sau consultă documentația sistemului la care te conectezi. GET (pentru căutări) și POST (pentru crearea de înregistrări) sunt cele mai comune.

Pasul 3: Adaugă antetele de autentificare #

Majoritatea sistemelor necesită autentificare pentru a accepta cereri. Adaugă orice antete necesare:

Valorile antetelor care conțin o cheie sau o parolă, cum ar fi Authorization sau X-API-Key, apar sub formă de puncte după ce sunt introduse. Faceți clic pe pictograma ochi de lângă valoare pentru a o vedea.

Sfat de securitate: Folosește o cheie API dedicată cu permisiuni limitate. Nu utiliza credențiale de nivel admin.

Unde găsești cheile API: Verifică setările sau secțiunea pentru dezvoltatori a sistemului la care te conectezi (de exemplu, CRM-ul tău, platforma de e-commerce sau instrumentul de rezervări).

Pasul 4: Definește datele de intrare (ce trimite botul) #

Parametrii de intrare sunt informațiile pe care botul le colectează din conversație și le trimite către sistemul tău.

Pentru fiecare parametru, specifici:

Tipuri de parametri disponibili:

Fiecare parametru are, de asemenea, un câmp opțional Cale corp cerere (Request body path). În mod normal, un parametru este trimis ca un câmp de nivel superior în corpul cererii (sau ca o valoare în șirul de interogare, pentru tipul query_param). Dacă endpoint-ul tău se așteaptă ca acesta să fie imbricat — de exemplu {"order": {"id": "ORD-123"}} — setează calea la order.id, iar platforma va imbrica valoarea acolo pentru tine.

Exemplu: Pentru o căutare a stării comenzii, ai putea defini:

• order_number (string, obligatoriu): „Numărul comenzii clientului. De obicei începe cu ORD- urmat de cifre. Cere clientului acest număr dacă nu l-a menționat deja.”
• email (string, opțional): „Adresa de e-mail a clientului pentru verificare suplimentară. Necesară doar dacă numărul comenzii singur nu găsește o potrivire.”

Ce primește sistemul tău automat #

Pe lângă parametrii de intrare pe care îi definiți, platforma include automat date de sistem cu fiecare solicitare. Endpoint-ul dumneavoastră primește acest lucru într-un câmp system:

Acest lucru este util dacă sistemul tău trebuie să identifice contactul, să verifice ce agent a apelat funcția sau să se comporte diferit în timpul testării.

Când o verificare ulterioară apelează funcția ta (vezi Trimite doar când o verificare reușește), cererea este diferită de un apel în timpul conversației: nu are parametri de intrare, iar câmpul system conține doar system.contact (cu id-ul său), plus un bloc system.follow_up (type, cycle_number, follow_up_number, reason, campaign_id, agent_id). Nu conține niciun obiect campaign. Omite datele de sistem (Skip System Data) se aplică și acelui apel.

Nu ai nevoie de datele de sistem? Activează comutatorul Omite datele de sistem în generatorul de funcții. Botul va trimite apoi doar parametrii de intrare pe care i-ai definit — fără date despre contact sau agent. Folosește această opțiune dacă endpoint-ul tău respinge câmpurile neașteptate sau dacă pur și simplu dorești un payload mai simplu.

Pasul 5: Testează-l, apoi lasă botul să citească răspunsul #

În mod normal, nu trebuie să mapezi deloc câmpurile de răspuns. Odată ce endpoint-ul tău răspunde, botul citește întregul răspuns JSON și folosește Descrierea și Scopul (Acțiune AI) ale funcției tale — plus descrierea fiecărui parametru — pentru a determina ce este important și a prezenta informația în mod natural. O descriere clară a funcției în sine („Recuperează starea curentă a unei comenzi a clientului, incluzând informațiile de livrare și urmărirea”) face mai multă treabă aici decât ar face maparea câmp cu câmp.

Dacă endpoint-ul tău returnează un răspuns mare și vrei ca botul să vadă doar câteva valori specifice, deschide secțiunea Mapare răspuns (restrânsă implicit, chiar deasupra butonului Test). Fiecare rând alege un câmp de nivel superior din răspuns: Câmp răspuns este numele câmpului din răspunsul JSON al API-ului tău, iar Câmp ieșire este numele sub care îl primește botul. Cu cel puțin un rând completat, botul primește doar valorile mapate de tine în loc de întregul corp al răspunsului. Lasă secțiunea goală pentru a păstra comportamentul implicit de răspuns complet.

Înainte de a salva, folosește secțiunea Test din partea de jos a generatorului pentru a lansa cererea exact așa cum a fost configurată și pentru a vedea răspunsul real, fără a părăsi aplicația:

Răspunsul pe care îl vedeți aici este răspunsul brut al endpoint-ului. Dacă ați configurat Maparea răspunsului mai sus, botul într-un chat real primește doar acele câmpuri mapate — testul arată întotdeauna răspunsul brut complet, astfel încât să puteți vedea ce este disponibil pentru mapare. Dacă ceva pare în neregulă (nume de câmpuri neașteptate, imbricare suplimentară), remediați acest lucru la nivelul endpoint-ului sau ajustați maparea. #

Atribuirea funcțiilor unui Agent #

După crearea unei funcții personalizate, trebuie să spui fiecărui Agent ce funcții poate folosi:

1. Deschide Agentul din AI Studio → Agenți AI.
2. Mergi la fila Abilități AI.
3. Vei vedea o listă cu fiecare funcție personalizată pe care ai creat-o. Activează fiecare funcție pe care dorești ca botul acestui agent să o poată apela.
4. Apasă pe Salvează modificările în partea de jos. Selecțiile se aplică doar după salvare.

Doar funcțiile atribuite sunt disponibile botului pentru acel Agent. Acest lucru previne utilizarea accidentală a unor funcții care nu sunt relevante.

Testarea funcțiilor personalizate #

Înainte de a trece la varianta live, testați temeinic:

1. Rulează testul încorporat - Folosește secțiunea Test din interiorul generatorului de funcții (vezi mai sus) pentru o verificare rapidă fără a părăsi aplicația — introdu valori realiste și fă clic pe Run test.
2. Testează direct endpoint-ul sistemului tău - Pentru lista de verificare completă de mai jos, un instrument dedicat precum Postman (sau dezvoltatorul tău) analizează mai în profunzime decât un singur Run test.
3. Testează în Try Out - Simulează o conversație în care clientul întreabă ceva ce ar trebui să declanșeze funcția.
4. Verifică răspunsul - Asigură-te că botul citește și prezintă corect datele.
5. Testează scenariile de eroare - Ce se întâmplă dacă clientul oferă un număr de comandă invalid? Ce se întâmplă dacă sistemul tău este temporar indisponibil?

Când testul returnează 401 sau 403 #

O eroare 401 sau 403 înseamnă că punctul final (endpoint) a primit cererea, dar a refuzat-o. Indiciul este că nu apare nimic în propriile jurnale — majoritatea instrumentelor resping un apel neautorizat înainte de a începe fluxul de lucru, deci nu există nimic de văzut din partea ta și pare că cererea nu a ajuns niciodată.

Aproape întotdeauna este vorba despre o nepotrivire de autentificare: punctul tău final dorește un anumit tip de acreditări, iar funcția trimite unul diferit. Verifică dacă antetul pe care l-ai adăugat la Pasul 3 este exact cel așteptat de sistemul tău.

Cea mai comună variantă a acestei probleme este un webhook protejat cu Basic Auth (n8n, Make și majoritatea instrumentelor găzduite local oferă acest lucru ca o bifă pe webhook-ul în sine), în timp ce funcția trimite un antet secret personalizat precum X-My-Secret. Basic Auth acceptă doar un antet Authorization, deci un antet personalizat este ignorat și apelul este respins. Ai două opțiuni:

• Dezactivează Basic Auth pe webhook și verifică antetul personalizat în interiorul fluxului de lucru.
• Păstrează Basic Auth activat și adaugă un antet Authorization la funcție, a cărui valoare să fie cuvântul Basic urmat de username:password codificat în base64.

Oricare dintre variante funcționează — asigură-te doar că ambele părți sunt de acord.

Când testul returnează 404 #

URL-ul punctului final este greșit sau fluxul de lucru nu este publicat. În n8n, în mod specific, fiecare webhook are un URL de Test și un URL de Producție separat, iar cel de Test ascultă doar cât timp ai editorul deschis. Copiază URL-ul de Producție și asigură-te că fluxul de lucru este activ.

Vizualizarea erorilor în Try Out și Chats #

Atunci când AI-ul apelează o funcție personalizată în timpul unei conversații și apelul eșuează, de exemplu din cauza unor credențiale greșite, a unui endpoint care nu funcționează sau a unei depășiri de timp (timeout), conversația afișează acum acest lucru: un marcaj roșu “(nume funcție) a eșuat” apare în firul de discuție, atât în fila Try Out a agentului, cât și în conversațiile reale din Chats. Fă clic pe marcaj pentru a extinde detaliile: codul de stare returnat de endpoint-ul tău și corpul răspunsului, care sunt de obicei suficiente pentru a-ți spune exact ce trebuie să repari (un 401 cu un mesaj “unauthorized” înseamnă antetul de autentificare, un timeout înseamnă că endpoint-ul tău a durat mai mult de 30 de secunde; pentru o sarcină care necesită mai mult timp, vezi Sarcini de lungă durată).

Apelurile reușite afișează, de asemenea, un indicator — faceți clic pe el pentru a vedea ce a trimis efectiv înapoi endpoint-ul dumneavoastră. Aceasta este cea mai rapidă modalitate de a depana o integrare cap-la-cap: purtați conversația de test în Try Out, apoi faceți clic pe indicatorul funcției pentru a vedea rezultatul real al cererii fără a părăsi pagina.

Când un instrument continuă să eșueze în conversațiile reale #

Dacă aceeași funcție personalizată eșuează de 3 ori în decurs de 24 de ore în timp ce agentul tău AI poartă conversații, vei primi o alertă pe zi pentru aceasta: prin e-mail, în secțiunea cu notificări (pictograma clopoțel) și sub formă de notificare push, dacă ai activat-o. Alerta menționează instrumentul, afișează ultima eroare și oferă linkuri către conversațiile afectate, deoarece agentul va fi informat acele contacte că a întâmpinat o problemă tehnică. Rândul funcției din Setări afișează o linie Eșuat (Failing) cu numărul de erori și ultima eroare până când instrumentul funcționează din nou; un apel reușit va șterge această stare. Poți dezactiva aceste alerte din Setări → Notificări → Erori instrument. #

Exemplu complet: Căutare stare comandă #

Iată un exemplu complet configurat pe care îl poți folosi ca șablon:

Informații de bază:

• Nume: check_order_status
• Descriere: “Recuperează starea curentă a unei comenzi a clientului, inclusiv informațiile de livrare și urmărire”
• Acțiune AI: “Apelează această funcție atunci când un client întreabă despre starea comenzii sale, unde se află coletul sau când va sosi. Întreabă întotdeauna mai întâi numărul comenzii.”

Conexiune:

• URL: https://api.mystore.com/orders/lookup
• Metodă: POST

Antete:

• Authorization: Bearer sk_live_abc123
• Content-Type: application/json

Parametri de intrare:

• order_number (text, obligatoriu): “Numărul comenzii furnizat de client”
• customer_email (text, opțional): “Adresa de e-mail a clientului pentru verificare suplimentară”

Nu este necesară maparea răspunsului — cu o Descriere și o Acțiune AI clar setate mai sus, botul citește orice JSON returnează endpoint-ul tău (stare, număr de urmărire, dată de livrare, articole) și determină cum să comunice despre acesta.

Cum arată conversația:

Client: Hei, unde este comanda mea?

Bot: Bună! Mă bucur să verific starea comenzii tale. Îmi poți comunica numărul comenzii?

Client: Este ORD-78234

Bot: Lasă-mă să verific pentru tine…

Comanda ta ORD-78234 a fost expediată și este pe drum! Data estimată a livrării este 10 martie. Poți urmări coletul aici: https://tracking.example.com/1Z999AA1

Te mai pot ajuta cu altceva?

Exemplu complet: Starea comenzii Shopify #

Dacă magazinul rulează pe Shopify, nu ai nevoie de un dezvoltator pentru a crea un endpoint de căutare — sistemul propriu Shopify poate răspunde direct la întrebările despre comenzi. (Pentru întrebări despre produse și stocuri într-un magazin Shopify, nu ai nevoie deloc de o funcție personalizată: conectează serverul integrat al magazinului — vezi Conectarea unui magazin Shopify.)

Mai întâi, creați un jeton de acces în Shopify. Shopify a modificat acest lucru în cursul anului 2026: aplicațiile nu mai pot fi create în interiorul panoului de administrare Shopify, iar noul ecran pentru aplicații vă oferă un ID de client și un Secret de client în loc de un jeton gata pregătit. Pașii de mai jos transformă aceste date într-un jeton permanent. Alocați aproximativ zece minute, o singură dată per magazin. (Dacă magazinul are deja o aplicație mai veche creată prin metoda veche, jetonul existent va continua să funcționeze — treceți direct la funcția personalizată de mai jos.)

1. Accesați Shopify Dev Dashboard la dev.shopify.com, deschideți organizația dvs. și faceți clic pe Apps → Create app. Denumiți-o ceva de genul Order lookup.
2. Acordați aplicației permisiunea read_orders, lansați o versiune și instalați aplicația pe magazin.
3. Deschideți Setările aplicației și adăugați adresa web a magazinului (de exemplu https://www.yourstore.com/) la URL-urile de redirecționare permise. Salvați.
4. Tot în Setări, copiați Client ID și Client secret.
5. Într-un browser în care sunteți conectat la Shopify admin al acelui magazin, deschideți adresa de mai jos, înlocuind numele magazinului, ID-ul clientului și adresa de redirecționare cu ale dvs.: https://YOUR-STORE.myshopify.com/admin/oauth/authorize?client_id=YOUR-CLIENT-ID&scope=read_orders&redirect_uri=https://www.yourstore.com/&state=12345 Aprobați ecranul care apare. Browserul va ajunge la adresa dvs. de redirecționare, iar bara de adrese va conține acum code= urmat de o valoare lungă — copiați acea valoare. Este validă doar pentru câteva minute, așa că treceți direct la pasul următor.
6. Schimbați acel cod cu token-ul, ceea ce puteți face în Your AI Connector. În constructorul de funcții personalizate, setați Metoda la POST și URL la https://YOUR-STORE.myshopify.com/admin/oauth/access_token, adăugați trei parametri de intrare text numiți client_id, client_secret și code, apoi faceți clic pe Test, completați cele trei valori și rulați-l. Răspunsul conține access_token — acesta este token-ul dvs. permanent. Copiați-l într-un loc sigur, apoi goliți constructorul și configurați funcția reală mai jos.

Apoi configurează funcția personalizată:

Informații de bază:

• Nume: check_shopify_order
• Descriere: “Caută o comandă în sistemul Shopify al magazinului și returnează starea, urmărirea și articolele acesteia”
• Acțiune AI: “Apelează această funcție atunci când un client întreabă despre starea comenzii sau livrarea sa. Întreabă întotdeauna mai întâi numărul comenzii.”

Conexiune:

• URL: https://YOUR-STORE.myshopify.com/admin/api/2026-01/orders.json?status=any — înlocuiește YOUR-STORE cu numele .myshopify.com al magazinului (această adresă folosește domeniul tehnic Shopify, nu domeniul personalizat al magazinului)
• Metodă: GET

Antete:

• X-Shopify-Access-Token: shpat_... (tokenul de mai sus)

Parametri de intrare:

• name (query_param, obligatoriu): “Numărul comenzii clientului exact așa cum apare în confirmarea comenzii, inclusiv semnul # — de exemplu #1001. Cere clientului acest număr dacă nu l-a menționat deja.”

Nu este necesară maparea răspunsului — botul citește comanda returnată (starea plății, starea livrării, urmărirea, articolele) și răspunde în mod natural.

Bine de știut: un token creat în acest mod poate vedea comenzile din ultimele 60 de zile — suficient pentru întrebările de asistență zilnice, dar nu pentru un istoric complet al comenzilor.

Exemplu complet: Programare #

Informații de bază:

• Nume: create_booking
• Descriere: “Creează o programare nouă în sistemul nostru de rezervări”
• Acțiune AI: “Folosește această funcție după confirmarea datei, orei și a detaliilor de contact cu clientul. Nu apela funcția până când clientul nu confirmă explicit că dorește să facă programarea.”

Conexiune:

• URL: https://booking.mycompany.com/api/appointments
• Metodă: POST

Parametri de intrare:

• date (text, obligatoriu): “Data programării în format AAAA-LL-ZZ”
• time (text, obligatoriu): “Ora programării în format HH:MM”
• name (text, obligatoriu): “Numele complet al clientului”
• phone (text, obligatoriu): “Numărul de telefon al clientului”
• service_type (text, obligatoriu): “Tipul serviciului rezervat”

Exemplu complet: Adăugarea unui abonat la newsletter în CRM-ul tău #

Un tipar foarte comun: botul termină de răspuns, oferă newsletter-ul tău, contactul răspunde cu adresa de e-mail, iar acea adresă ar trebui să ajungă direct în instrumentul tău de e-mail. Majoritatea sistemelor CRM (FluentCRM, ActiveCampaign, MailerLite, Brevo și altele) acceptă un simplu POST exact pentru acest lucru, deci nu este nevoie de o platformă de automatizare intermediară.

Acest exemplu utilizează FluentCRM pe WordPress. Structura este aceeași pentru orice alt instrument care îți oferă un „webhook de intrare” sau un endpoint de „creare abonat”.

Mai întâi, obține URL-ul din CRM-ul tău. În WordPress, deschide FluentCRM → Settings → Incoming Webhooks și creează un webhook. Alege lista, etichetele și starea abonamentului pe care ar trebui să le primească noile contacte, apoi copiază URL-ul webhook-ului generat. Tot ce setezi aici este aplicat automat, astfel încât botul trebuie doar să trimită adresa de e-mail.

Apoi configurează funcția personalizată:

Informații de bază:

• Nume: add_newsletter_subscriber
• Descriere: „Adaugă o persoană în lista noastră de newsletter folosind adresa de e-mail oferită în chat”
• Acțiune AI: „Folosește acest lucru în momentul în care contactul este de acord să se aboneze la newsletter și oferă adresa de e-mail. Nu apela funcția înainte ca aceștia să fi furnizat efectiv o adresă și nu o apela de două ori pentru aceeași persoană.”

Conexiune:

• URL: URL-ul webhook-ului pe care l-ai copiat din CRM-ul tău
• Metodă: POST

Parametri de intrare:

• email (șir, obligatoriu): „Adresa de e-mail pe care contactul a oferit-o în conversație”
• first_name (șir, opțional): „Prenumele contactului, dacă a fost menționat”

Omite datele de sistem: activează această opțiune (on). CRM-ul tău are nevoie doar de câmpurile de mai sus, iar un payload mai simplu evită erorile din partea instrumentelor care resping câmpurile neașteptate.

Maparea răspunsului: nu este necesară aici. Nu trebuie să se întoarcă nimic pentru ca botul să își continue activitatea.

Nu uitați să activați funcția pentru Agentul care rulează conversația (consultați Atribuirea funcțiilor unui agent). Acesta este cel mai frecvent motiv pentru care o funcție construită corect nu se declanșează niciodată.

Sfaturi pentru funcții personalizate fiabile #

1. Asigură-te că cererile repetate sunt sigure. Dacă aceeași cerere este trimisă accidental de două ori, aceasta nu ar trebui să creeze înregistrări duplicate. Problemele de rețea pot cauza ocazional acest lucru.

2. Returnează mesaje de eroare clare. Dacă ceva nu merge bine din partea sistemului tău, returnează o eroare ușor de înțeles pentru utilizatori. Botul o va transmite clientului într-o manieră elegantă.

3. Menține timpii de răspuns sub 10 secunde. Dacă sistemul tău are nevoie de mai mult timp, ia în considerare returnarea unei confirmări rapide mai întâi.

4. Gestionează credențialele expirate sau invalide. Dacă cheia ta API expiră, asigură-te că mesajul de eroare este clar, astfel încât botul să știe să alerteze un om în loc să reîncerce.

5. Scrie descrieri detaliate. AI-ul folosește descrierile tale pentru a determina când să apeleze funcția și cum să extragă informațiile corecte din conversație. Descrierile vagi duc la greșeli.

6. Testează cu conversații reale. „Încearcă” este excelent pentru testarea inițială, dar monitorizează primele conversații live pentru a te asigura că totul funcționează cu întrebări reale ale clienților.

7. Păstrează jurnale (logs) de partea ta. Cere dezvoltatorului tău să înregistreze cererile care vin din aplicație, astfel încât să poți depana rapid orice problemă.

8. Dacă firewall-ul tău necesită o listă de IP-uri permise, fiecare apel de funcție personalizată (și fiecare verificare ulterioară) este trimis de la o singură adresă IPv4 fixă, aceeași pe care o folosesc webhook-urile noastre; fără intervale, fără IPv6, fără rotație. Contactează asistența și îți vom oferi adresa. Activează semnarea cererilor și verifică semnătura ca metodă principală de încredere, tratând IP-ul doar ca pe un filtru suplimentar.

9. Folosește o adresă URL publică finală. Adresa URL a funcției tale trebuie să fie o adresă web publică (HTTP/HTTPS). Adresele interne, localhost și cele din rețele private sunt respinse din motive de securitate, iar platforma nu urmărește redirecționările — direcționează funcția direct către URL-ul final, nu către unul care redirecționează către acesta.

Sarcini de lungă durată: obține rezultatul mai târziu #

În mod normal, o funcție personalizată trebuie să răspundă în termen de 30 de secunde, în timp ce contactul așteaptă răspunsul. Unele sarcini durează mai mult de atât: randarea unui videoclip, efectuarea unei verificări de credit, așteptarea ca o persoană din partea ta să aprobe ceva. Pentru acestea, activează Rezultatul vine mai târziu (de lungă durată). Apelul AI-ului doar pornește sarcina. Serviciul tău răspunde imediat, AI-ul îi spune contactului că rezultatul este pe drum și continuă conversația, iar serviciul tău trimite rezultatul către un link de callback imediat ce este gata.

Când să îl folosești #

Folosește-l atunci când serviciul tău nu poate răspunde în mod fiabil în termen de 30 de secunde. Lasă-l dezactivat pentru căutări rapide (starea unei comenzi, verificarea stocului, un preț): acestea sunt mai simple ca un apel normal, deoarece AI-ul răspunde cu rezultatul în același mesaj.

Setările din editor #

Le găsești în editorul de funcții personalizate, lângă Omite datele de sistem.

Ce primește serviciul tău #

Cu comutatorul activat, fiecare apel poartă linkul de callback în trei locuri, pe lângă tot ce a fost descris mai sus (parametrii tăi de intrare, blocul system și antetele de semnare):

Linkul este unic pentru fiecare apel, aparține acelui contact și acelui apel, funcționează o singură dată și expiră după Așteaptă până la. Nu ai nevoie de o cheie API pentru a-l folosi: linkul în sine reprezintă permisiunea. Tratează-l ca pe o parolă și nu îl scrie niciodată într-un jurnal public.

Trimiterea rezultatului #

Când sarcina este gata, trimite un POST către linkul de callback:

POST https://api.<your host>/v1/custom-functions/callback/d3f9...
Content-Type: application/json

{
  "result": { "video_url": "https://cdn.example.com/spring-offer.mp4", "duration_seconds": 42 },
  "message": "Your video is ready: https://cdn.example.com/spring-offer.mp4"
}

• result este ceea ce citește AI-ul. Poate fi text sau un obiect JSON.
• message este opțional. Cu Trimite textul ca atare, contactul primește message atunci când trimiți unul, altfel result când este text.
• media_url este opțional: un link https către un fișier (imagine, video, audio sau document) pe care contactul îl primește ca atașament real, nu ca link. Vezi Trimiterea unui fișier mai jos.
• De asemenea, poți trimite un corp de text simplu cu Content-Type: text/plain. Acesta este tratat ca result.
• Corpul mesajului poate avea până la 64 KB.

La ce răspunde linkul de callback:

Un exemplu complet: un videoclip care durează trei minute #

1. AI-ul apelează funcția ta. Primești (prescurtat):

POST https://api.example.com/render
X-Callback-Url: https://api.<your host>/v1/custom-functions/callback/d3f9...
Content-Type: application/json

{
  "video_title": "Spring offer",
  "callback_url": "https://api.<your host>/v1/custom-functions/callback/d3f9...",
  "system": {
    "contactId": "...",
    "callback_url": "https://api.<your host>/v1/custom-functions/callback/d3f9...",
    "callback_expires_at": "2026-10-20T19:15:00.000Z"
  }
}

2. Serviciul tău începe randarea și răspunde imediat:

{ "status": "started" }

3. AI-ul îi spune contactului că videoclipul este în curs de creare și continuă conversația.
4. Trei minute mai târziu, serviciul tău postează rezultatul către linkul de callback:

{ "result": { "video_url": "https://cdn.example.com/spring-offer.mp4", "duration_seconds": 42 } }

5. AI-ul scrie următorul mesaj cu propriile cuvinte, de exemplu “Videoclipul tău este gata: https://cdn.example.com/spring-offer.mp4”.

Folosești Zapier sau Make? Lasă webhook-ul de declanșare să primească apelul și fă ultimul pas al fluxului un POST către callback_url din datele de declanșare.

Ce se întâmplă în chat #

Rezultatul este salvat în conversație ca o intrare de funcție, deci îl vezi în inbox ca pe orice alt apel de funcție personalizată. Apoi, în funcție de Când sosește rezultatul, AI-ul scrie și trimite următorul mesaj (acest lucru costă un răspuns AI, ca orice mesaj AI), sau textul tău este trimis ca atare. Cu Trimite textul ca atare, câmpul message este trimis când incluzi unul, altfel result când este text simplu; dacă postezi doar un obiect fără text, AI-ul scrie mesajul în schimb.

Dacă AI-ul este oprit pentru acel contact când sosește rezultatul (un membru al echipei a preluat conversația, AI-ul a fost pus pe pauză, agentul este oprit sau nu mai are credite), rezultatul este totuși salvat în conversație, dar nu este trimis niciun mesaj. Acesta nu este trimis nici mai târziu când AI-ul este repornit. Membrul echipei vede rezultatul în chat și îl poate folosi.

În fila Încearcă a agentului, întregul flux funcționează de asemenea: rezultatul sosește în chat-ul de test.

Trimiterea unui fișier (video, imagine, PDF) #

Un rezultat care este un fișier, de exemplu un videoclip pe care serviciul tău l-a redat în fundal, ajunge la contact ca un atașament pe care acesta îl poate deschide în chat, în ambele moduri. Platforma găsește fișierul în callback-ul tău astfel:

1. media_url în corp, atunci când trimiți unul.
2. Altfel, un câmp de fișier pe obiectul result: file_url, video_url, image_url, pdf_url, document_url, audio_url, attachment_url sau download_url.
3. Altfel, primul link https din text care se termină cu o extensie de fișier precum .mp4, .jpg, .png sau .pdf.

Cu AI-ul scrie următorul mesaj, AI-ul scrie textul și fișierul este atașat acelui mesaj (AI-ului i se spune să nu lipească linkul). Cu Trimite textul ca atare, message-ul tău este legenda atașamentului.

{
  "result": { "status": "done", "title": "Spring offer" },
  "message": "Your video is ready.",
  "media_url": "https://cdn.example.com/spring-offer.mp4"
}

Fișierele pot avea până la 16 MB și trebuie să fie accesibile prin https. Fiecare canal suportă tipuri diferite: de exemplu, canalele de e-mail și WhatsApp acceptă video, imagini, audio și documente, SMS-ul nu suportă fișiere. Când un canal nu poate prelua fișierul sau fișierul este prea mare, contactul primește totuși mesajul, cu linkul către fișier adăugat la final.

Când rezultatul nu sosește niciodată #

Dacă nu se postează nimic înainte ca timpul de Așteaptă până la să expire, AI-ul este informat că rezultatul nu a sosit niciodată, astfel încât să poată anunța contactul. O intrare cu codul APP-3103 apare sub Setări → Jurnal erori și primești o notificare de eroare a instrumentului.

Limite pe scurt #

• Un rezultat per link de callback. Postările ulterioare către același link sunt tratate ca duplicate și nu schimbă nimic.
• Până la 64 KB per rezultat.
• Un fișier per rezultat, până la 16 MB, prin https.
• Până la 20 de postări pe minut către un link.
• Așteaptă până la între 1 și 168 de ore.
• Serviciul tău are în continuare 30 de secunde pentru a răspunde la primul apel.

Verificarea faptului că un apel provine într-adevăr de la noi #

Oricine află URL-ul funcției tale îi poate trimite o cerere falsă. Un secret lung într-un antet de autentificare ajută, dar este aceeași valoare la fiecare apel, așa că oricine vede o cerere (într-un jurnal sau o captură de ecran) o poate reutiliza. Semnarea cererilor rezolvă această problemă: fiecare apel poartă o semnătură pe care doar cineva care deține secretul tău o poate produce și care expiră după câteva minute.

Semnarea este opțională și dezactivată implicit, fiind o setare unică pentru întregul tău cont: un singur secret semnează fiecare funcție personalizată.

Activarea semnării #

1. Deschide Funcții personalizate (Custom Functions).
2. Sub lista ta de funcții, găsește cardul Semnarea cererilor (Request signing) și dă clic pe Activează semnarea (Turn on signing).
3. Dă clic pe Afișează (Show), copiază secretul (începe cu whsec_) și stochează-l în sistemul care primește apelurile. Tratează-l ca pe o parolă.

Din același card poți copia din nou secretul, îl poți Rota (cel vechi încetează să mai funcționeze imediat) sau poți Dezactiva semnarea.

Ce trimitem #

Odată ce semnarea este activată, fiecare apel efectuat de o funcție personalizată poartă două anteturi suplimentare: apelurile AI-ului în timpul unui chat, condițiile de trimitere ulterioară și butonul Rulează testul (Run Test) din editor.

Fiecare apel, semnat sau nu, poartă de asemenea User-Agent: Custom-Function/1.0, cu excepția cazului în care setezi propriul tău antet User-Agent.

Anteturile și semnătura funcționează exact ca webhook-urile semnate, deci dacă verifici deja webhook-urile noastre, același cod va funcționa și aici. Doar secretul este diferit.

Cum se verifică #

Semnătura este un HMAC-SHA256 al șirului <timestamp>.<raw request body>, folosind secretul tău de semnare drept cheie. Verifică-l comparându-l cu corpul brut (raw), octeții exacți pe care i-ai primit: parsarea JSON-ului și transformarea lui înapoi în text poate modifica octeții, iar semnătura nu se va potrivi.

O funcție care folosește GET (sau un POST fără date de trimis) nu are corp, deci șirul semnat este doar <timestamp>. cu un corp gol. Semnătura dovedește atunci că apelul provine de la noi și este recent, dar nu acoperă șirul de interogare (query string).

Exemplu Node.js:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"] || ""; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const received = signature.replace("v1=", "");

  return received.length === expected.length && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

Exemplu Python:

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers.get("X-Webhook-Timestamp", "")
    signature = headers.get("X-Webhook-Signature", "").replace("v1=", "")
    if not timestamp or abs(time.time() - int(timestamp)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

Testează cu Rulează testul (Run Test) în editor: odată ce semnarea este activată, apelul de test este semnat exact ca unul real, deci o funcție care trece testul va trece și verificarea ta în timpul chat-urilor reale.

Folosești API-ul? Același secret poate fi citit, generat sau rotat și eliminat cu GET, POST și DELETE pe /v1/custom-functions/signing-secret.

Limite de execuție #

Fiecare funcție personalizată are o secțiune opțională Limite de execuție în partea de jos a editorului. Aceasta controlează cât de des poate rula AI-ul funcția și dacă un rezultat anterior poate fi refolosit. Totul aici este opțional — lăsați totul gol și funcția se va comporta exact ca înainte.

Funcție read-only (doar citire). Activați această opțiune dacă funcția dvs. doar citește date — o căutare de stoc, o verificare de preț, o căutare a stării unei comenzi — și nu creează sau modifică niciodată nimic. Atunci când o problemă temporară de rețea întrerupe AI-ul în timpul răspunsului, platforma poate reîncerca în siguranță etapa conversației, în loc să lase clientul fără un răspuns. Activați această opțiune doar dacă funcția nu scrie cu adevărat nimic: o funcție care creează înregistrări trebuie să rămână dezactivată, astfel încât o reîncercare să nu o poată rula accidental de două ori. Funcțiile care utilizează metoda GET sunt tratate automat ca read-only, deoarece cererile GET sunt destinate doar preluării datelor; funcțiile POST, PUT, PATCH și DELETE necesită activarea comutatorului.

Servește rezultatul din cache la apeluri repetate. Când AI-ul apelează funcția din nou cu aceleași date de intrare (de exemplu, clientul pune aceeași întrebare de două ori), rezultatul anterior este refolosit în loc să apeleze din nou punctul final (endpoint). Rezultatele din cache sunt păstrate timp de până la 24 de ore, iar un apel cu date de intrare diferite va accesa întotdeauna punctul final pentru o interogare nouă.

Număr maxim de rulări per conversație. O limită strictă privind numărul de ori în care funcția poate rula în cadrul unei conversații. Setați-o la 1 pentru funcțiile care ar trebui să fie declanșate o singură dată per chat — generarea unei oferte, declanșarea unui apel înapoi, pornirea unei automatizări. Când limita este atinsă, AI-ul este informat că funcția a rulat deja și primește cel mai recent rezultat, astfel încât să poată răspunde în continuare clientului în loc să rămână tăcut.

Număr maxim de rulări per interval de timp. O limită de rată în timp: de exemplu, cel mult 5 rulări în 60 de minute. Util pentru funcțiile care apelează servicii terțe plătite sau declanșează automatizări mai complexe. Ambele căsuțe trebuie completate împreună (un număr de rulări și un interval în minute, până la 7 zile).

Trimiterea de oferte, contracte sau facturi pe LinkedIn. Când AI-ul răspunde pe LinkedIn, acesta scrie din propria căsuță poștală a proprietarului contului, așa că nu ar trebui să trimită o ofertă, un contract, o cotație, o factură, un link de plată sau acces în numele proprietarului decât dacă acesta a specificat acest lucru. Cu Automat (setarea implicită), o funcție al cărei nume sau descriere indică trimiterea unuia dintre aceste elemente nu este executată pe LinkedIn: AI-ul este informat că nu a fost trimis nimic și anunță persoana respectivă că proprietarul se va ocupa de acest aspect. Alegeți Permis pentru a permite totuși rularea funcției pe LinkedIn sau Niciodată pe LinkedIn pentru a bloca o funcție pe care verificarea automată ar putea să o omită. Celelalte canale nu sunt afectate și, spre deosebire de limitele de mai sus, această setare se aplică și în modul Încearcă (Try Out).

Câteva lucruri de știut:

• Limitele contorizează doar rulările reușite. Un apel care a eșuat din partea punctului dvs. final nu consumă din buget.
• Atunci când o rulare este blocată de o limită, clientul nu este lăsat niciodată în așteptare — AI-ul este informat despre motiv și lucrează cu informațiile pe care le are deja.
• Limitele se aplică peste tot unde rulează funcția: chat-uri obișnuite pe fiecare canal și funcții gestionate de o automatizare. Conversațiile de test din „Încearcă” (Try Out) nu sunt contorizate și nu sunt limitate.

Instrumente integrate pentru boți #

Pe lângă funcțiile personalizate pe care le construiești singur, platforma vine cu o bibliotecă de instrumente predefinite pe care botul AI le poate folosi în timpul unei conversații. Acestea acoperă cele mai comune acțiuni pe care trebuie să le facă un bot — alertarea unui coleg, programarea unei întâlniri, etichetarea unui contact, căutarea pe site-ul tău, programarea unei urmăriri și multe altele — astfel încât să nu fii nevoit să le configurezi de la zero.

Botul decide când să folosească fiecare instrument în funcție de ceea ce se întâmplă în conversație și de modul în care este configurat agentul tău. Majoritatea acestor instrumente se activează automat atunci când funcția aferentă este activată (de exemplu, instrumentele de rezervare devin disponibile doar după ce conectezi un calendar și activezi rezervările).

Cost în credite: Fiecare apel de instrument este facturat în funcție de nivelul de Calitate AI al Agentului tău, iar funcțiile personalizate pe care le creezi singur sunt facturate în același mod:

Instrumente pentru echipă și sarcini #

Instrumente pentru contacte #

Instrumente pentru programări și rezervări #

Aceste instrumente sunt disponibile doar atunci când rezervările sunt activate pentru agentul tău și este configurat un tip de eveniment în calendar.

Instrumente pentru cunoștințe și web #

Instrumente de follow-up #

Aceste instrumente necesită ca funcția de follow-up să fie activată pentru agentul tău.

Executor de funcții personalizate #

Instrumente pentru rezervări la restaurant (Zenchef și Formitable) #

Aceste instrumente sunt disponibile doar atunci când este conectată o integrare Zenchef sau Formitable. Acestea permit botului să gestioneze rezervările la restaurant cap-la-cap.

Activarea și dezactivarea instrumentelor #

Majoritatea instrumentelor sunt controlate din fila Abilități AI a agentului:

• Instrumentele de rezervare se activează când activezi rezervările și conectezi un calendar, în cardul Rezervări din aceeași filă Abilități AI
• Instrumentele de follow-up se activează când activezi funcția de follow-up
• Instrumentele pentru restaurante se activează când conectezi un cont Zenchef sau Formitable
• Căutarea pe web are propriul comutator în fila Întrebări frecvente și cunoștințe
• Instrumentele pentru sarcini pot fi dezactivate pentru fiecare agent cu ajutorul comutatorului Permite AI să creeze sarcini (sunt activate implicit; comutatorul general pentru sarcini din Setări → Profil → Funcții oprește întregul sistem de sarcini peste tot)
• Instrumentele de actualizare a contactelor sunt controlate din aceeași filă Abilități AI — dacă AI-ul poate redenumi contactele sau salva informații suplimentare colectate despre acestea
• Instrumentele de alertă sunt întotdeauna disponibile; etichetarea rulează automat după fiecare răspuns al botului (nu este un instrument pe care botul alege să îl apeleze)

Dacă dorești ca botul să nu mai folosească un anumit instrument încorporat, cea mai simplă metodă este să dezactivezi funcția subiacentă (de exemplu, dezactivează rezervările pentru a dezactiva toate instrumentele de rezervare).

Funcții gestionate de o automatizare #

Unele intrări din pagina Funcții personalizate pot purta insigna Gestionat de automatizare. Acestea nu au fost create aici — ele provin dintr-o automatizare cu un declanșator de tip Funcție Agent AI, care oferă agentului tău o abilitate ai cărei pași îi construiești vizual pe pânza de automatizare, în loc să indici o adresă web externă.

O funcție gestionată este administrată pentru tine: numele, descrierea și câmpurile sale respectă întotdeauna ceea ce este setat în declanșatorul automatizării, așa că nu poate fi editată sau ștearsă din această pagină — folosește linkul Deschide automatizarea și modifică automatizarea în sine. Poți alege în continuare ce agenți o au în mod obișnuit: în fila Capacități AI a unui agent, aceasta apare alături de celelalte capacități ale agentului cu un comutator obișnuit pornit/oprit (dacă automatizarea sa este întreruptă, rândul va specifica acest lucru — capacitatea devine activă când automatizarea este pornită). Tot restul se comportă ca orice altă funcție personalizată: AI-ul decide când să o apeleze, colectează detaliile pe care le-ai definit și poate folosi răspunsul automatizării în aceeași conversație.

Dacă alegi între cele două: direcționează o funcție personalizată obișnuită către un sistem care are deja o adresă de apelat; construiește o automatizare cu un declanșator de Funcție Agent AI atunci când munca este ceva ce ai prefera să asamblezi din pași — caută ceva într-o foaie de calcul sau bază de date, ramifică pe baza unei condiții, creează înregistrări — fără a rula propriul tău server. Vezi Automatizări.

Cerințele planului #

Funcțiile personalizate sunt disponibile în planurile care includ funcționalitatea de funcții personalizate. Verificați abonamentul pentru a confirma disponibilitatea.

Pașii următori #

• Conectează servere MCP la botul tău — un pachet gata pregătit de instrumente în loc de o singură funcție pe rând.
• Agenți AI — pagina principală a grupului AI Studio în care se află Funcțiile Personalizate și unde funcțiile personalizate sunt atribuite unui bot.