# Canale personalizate Conectați orice platformă de mesagerie sau instrument de comunicare la platformă folosind canale personalizate. Acest lucru vă permite să aduceți mesaje din platforme precum widget-uri de chat live pe site-uri web, sisteme de e-mail, CRM-uri sau orice alt serviciu în căsuța dvs. de primire — și să răspundeți la acestea cu Agentul dvs. AI. --- ## Ce sunt canalele personalizate? Canalele personalizate extind platforma dincolo de platformele sale de mesagerie integrate ([WhatsApp](whatsapp-business.md), [SMS](sms.md), [Instagram](instagram-dms.md), [Messenger](facebook-messenger.md)). Cu canalele personalizate, puteți: - **Primi mesaje** de la orice platformă externă în căsuța de primire unificată a platformei. - **Trimite răspunsuri** din aplicație înapoi către platforma dvs. externă în mod automat. - **Utiliza un Agent AI** pentru a răspunde la mesajele din orice sursă. - **Urmări toate conversațiile** alături de celelalte canale într-o singură căsuță de primire. Aceasta este soluția ideală pentru companiile care utilizează instrumente de comunicare specializate, au o platformă construită personalizat sau doresc să centralizeze toate mesajele clienților într-un singur loc. ::: note **Notă:** Canalele personalizate necesită o configurare tehnică. Dacă tu sau echipa ta nu sunteți familiarizați cu integrările tehnice, poate ar fi bine să ceri ajutorul dezvoltatorului web sau echipei IT pentru această secțiune. ::: --- ## Cum funcționează Canalele personalizate funcționează prin transmiterea mesajelor între platforma dvs. externă și platformă folosind **webhook-uri** (mesaje automate trimise între sisteme prin internet). Iată fluxul: ``` Your Platform ──(sends message to)──> The App | AI Agent responds Contact saved Message stored | The App ──(sends reply to)──> Your Platform ``` 1. **Mesaje primite:** Platforma dvs. externă trimite mesaje către o adresă web (URL). Gândiți-vă la aceasta ca la „postarea” unui mesaj de către platforma dvs. în căsuța poștală a platformei. 2. **Procesare:** Platforma creează sau actualizează contactul, stochează mesajul și pune un Agent AI să genereze un răspuns (dacă este activ). 3. **Mesaje trimise:** Când platforma trimite un răspuns (fie de la AI, fie tastat de dvs.), acesta trimite mesajul către un URL de pe platforma dvs., unde sistemul dvs. îl poate livra utilizatorului final. --- ## Configurarea mesajelor primite (De la platforma dvs. către aplicație) Pentru a trimite mesaje din platforma dvs. externă în aplicație, platforma dvs. trebuie să trimită date către următorul URL. Dezvoltatorul dvs. va recunoaște acest lucru ca pe o cerere POST standard (o modalitate comună prin care un sistem trimite date către altul prin internet). ### Unde să trimiteți mesajele ``` POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY ``` Înlocuiți `YOUR_API_KEY` cu cheia dvs. API (un cod privat care dovedește platformei că platforma dvs. are permisiunea de a-i trimite mesaje). Găsiți-o sau generați-o în **Setări → Integrări → Cheie API**. ### Formatul mesajului Trimiteți datele mesajului în următorul format (JSON): ```json { "customData": { "messageSid": "unique-message-id-123", "fromId": "user-456", "toId": "your-business-id", "body": "Hello, I have a question about your service.", "status": "received", "channel": "my-live-chat", "campaignId": "optional-campaign-id", "firstName": "John", "lastName": "Doe", "email": "john@example.com", "mediaUrl": null, "mediaContentType": null }, "messageType": "text" } ``` **Ce înseamnă fiecare parte:** - `messageSid` - Un ID unic pentru acest mesaj specific (creat de sistemul dumneavoastră). Folosit pentru a preveni procesarea aceluiași mesaj de două ori. - `fromId` - Cine a trimis mesajul (poate fi un ID de utilizator, o adresă de e-mail sau un număr de telefon din sistemul dumneavoastră). - `toId` - Identificatorul afacerii dumneavoastră (poate fi orice etichetă alegeți). - `body` - Textul propriu-zis al mesajului. - `channel` - O etichetă pe care o alegeți pentru a identifica sursa mesajului (de exemplu, "website-chat", "email"). ### Referință completă a câmpurilor | Câmp | Obligatoriu? | Ce face | |---|---|---| | `customData.messageSid` sau `customData.id` | Da | Un ID unic pentru acest mesaj (previne duplicatele) | | `customData.fromId` | Da | Identifică cine a trimis mesajul (de exemplu, un ID de utilizator, e-mail sau număr de telefon din sistemul dvs.) | | `customData.toId` | Da | Identifică partea care primește (afacerea dvs.). Poate fi orice text alegeți. | | `customData.body` | Da | Textul propriu-zis al mesajului. Nu poate fi gol. | | `customData.status` | Nu | Starea mesajului. Lăsați necompletat pentru a utiliza valoarea implicită (`"received"`). | | `customData.channel` | Nu | O etichetă pentru sursă (de exemplu, `"live-chat"`, `"email"`, `"my-crm"`). Vă ajută să identificați de unde provin mesajele în căsuța dvs. de primire. | | `customData.campaignId` | Nu | Un ID de campanie/Agent. Utilizați acest lucru pentru a direcționa mesajul către o configurație AI specifică. | | `customData.firstName` | Nu | Prenumele contactului. Inclus la crearea unei noi înregistrări de contact. | | `customData.lastName` | Nu | Numele de familie al contactului. Inclus la crearea unei noi înregistrări de contact. | | `customData.email` | Nu | Adresa de e-mail a contactului. Inclus la crearea unei noi înregistrări de contact. | | `customData.mediaUrl` | Nu | Un link către un fișier atașat (imagine, video, audio sau document). Poate fi, de asemenea, un fișier codificat base64 (vezi mai jos). | | `customData.mediaContentType` | Nu | Tipul fișierului (de exemplu, `"image/jpeg"`, `"video/mp4"`, `"audio/ogg"`, `"application/pdf"`). Obligatoriu dacă includeți `mediaUrl`. | | `messageType` | Nu | Tipul mesajului. Lăsați necompletat pentru text obișnuit. Setați la `"reaction"` pentru reacții emoji. | ### Reacții emoji Dacă platforma ta acceptă reacții emoji (de exemplu, un deget mare în sus la un mesaj), trimite-le ca reacție în loc de mesaj text: setează `messageType` la `"reaction"` și pune doar emoji-ul în `customData.body`. ```json { "messageType": "reaction", "customData": { "messageSid": "reaction-123", "fromId": "user-42", "toId": "my-business", "body": "👍" } } ``` Asistentul le va trata apoi așa cum te-ai aștepta: - O reacție la o întrebare adresată de asistent (de exemplu, „Este bine joia?”) este tratată ca răspuns, iar asistentul va răspunde. - O reacție la un mesaj de încheiere (de exemplu, „Mai vorbim!”) încheie conversația în mod discret. Nu este trimis niciun răspuns. Dacă platforma ta transformă reacțiile în text, cum ar fi „A reacționat cu: 👍”, asistentul vede un mesaj text obișnuit și decide singur dacă să răspundă. Trimiterea tipului de reacție evită acest lucru. ### Ce primești înapoi O solicitare reușită returnează: ```json { "success": true, "messageId": "1234567890" } ``` Dacă ceva nu merge bine, veți primi un mesaj de eroare care explică problema: ```json { "error": "Message body cannot be empty" } ``` ### Coduri de stare | Cod | Ce înseamnă | |---|---| | `200` | Succes - mesajul a fost primit și este în curs de procesare | | `400` | Ceva nu este în regulă cu cererea ta - verifică dacă lipsesc câmpuri obligatorii sau dacă corpul mesajului este gol | | `401` | Cheie API invalidă - verifică din nou cheia în **Setări → Integrări → Cheie API** | | `405` | Metodă de cerere greșită - asigură-te că folosești POST, nu GET | | `500` | Ceva nu a funcționat corect de partea platformei - încearcă din nou peste câteva momente | > Dacă setezi `customData.status`, singura valoare acceptată este `"received"` — omite-o complet pentru a utiliza valoarea implicită în loc să trimiți altceva, altfel vei primi o eroare `400`. --- ## Trimiterea atașamentelor media (imagini, videoclipuri, fișiere) Puteți include atașamente de fișiere (imagini, videoclipuri, audio, documente) împreună cu mesajele dumneavoastră. Există două moduri de a face acest lucru: ### Opțiunea 1: Link către un fișier Dacă fișierul este deja găzduit online, furnizați URL-ul (adresa web) de unde platforma îl poate descărca: ```json { "customData": { "messageSid": "msg-789", "fromId": "user-456", "toId": "business-1", "body": "Here is a photo of the issue.", "channel": "support-portal", "mediaUrl": "https://example.com/uploads/photo.jpg", "mediaContentType": "image/jpeg" }, "messageType": "text" } ``` ### Opțiunea 2: Încorporați fișierul direct (Base64) Dacă fișierul nu este găzduit online, îl puteți încorpora direct în mesaj sub formă de text codificat (format base64). Acest lucru este comun în integrările tehnice în care sistemul dumneavoastră generează fișiere din mers. Platforma va decoda și stoca automat fișierul: ```json { "customData": { "messageSid": "msg-790", "fromId": "user-456", "toId": "business-1", "body": "Screenshot attached.", "channel": "support-portal", "mediaUrl": "data:image/png;base64,iVBORw0KGgo...", "mediaContentType": "image/png" }, "messageType": "text" } ``` ::: note **Notă:** Încorporarea directă a fișierelor mărește considerabil dimensiunea datelor mesajului. Pentru fișiere mari, este mai bine să găzduiești fișierul online și să trimiți un link (Opțiunea 1). ::: --- ## Configurarea mesajelor de ieșire (de la platformă către platforma dumneavoastră) Când platforma trimite un răspuns pe un canal personalizat (fie de la AI, fie tastat de dvs.), acesta trimite automat acel răspuns către un URL de pe platforma dvs., astfel încât sistemul dvs. să îl poată livra utilizatorului final. > **Setați mai întâi URL-ul webhook-ului.** Trebuie să salvați URL-ul webhook-ului canalului personalizat înainte ca orice răspuns să poată fi livrat. Dacă nu este salvat niciun URL, răspunsurile sunt totuși generate și stocate, dar nu sunt niciodată trimise — și **nu** vor afișa o stare „Eșuat”, deci nimic din căsuța dvs. de primire nu va semnala problema. Configurați întotdeauna URL-ul webhook-ului înainte de a trece la utilizarea live. ### Spuneți aplicației unde să trimită răspunsurile 1. În bara laterală din stânga, dă clic pe **Setări** aproape de partea de jos. 2. În meniul lateral din stânga al Setărilor, sub **Canale**, dă clic pe **Canale**. 3. Găsește cardul **Canal personalizat** chiar în partea de jos a paginii (după Android SMS Gateway, iMessage, widgetul de chat pentru site-ul web, Cont Twilio și Conformitate reglementară). 4. Introdu **URL-ul Webhook** — adresa URL de pe platforma ta unde AI-ul ar trebui să trimită mesajele de ieșire (dezvoltatorul tău configurează acest lucru pentru a primi și procesa răspunsurile). Acesta trebuie să fie un **URL HTTPS public** — adresele `http://` și gazdele non-publice sunt respinse. 5. Dă clic pe **Salvare**. ### Ce trimite platforma către platforma dumneavoastră Atunci când platforma trimite un răspuns, platforma dumneavoastră va primi următoarele date: ```json { "contactId": "abc123", "messageId": "msg-456", "userId": "your-user-id", "body": "Thank you for your message! Here is the information you requested...", "toId": "user-456", "channel": "my-live-chat" } ``` ### Ce înseamnă fiecare câmp | Câmp | Ce conține | |---|---| | `contactId` | ID-ul intern al platformei pentru acest contact | | `messageId` | ID-ul unic al acestui mesaj în aplicație | | `userId` | ID-ul dumneavoastră de utilizator | | `body` | Textul răspunsului | | `toId` | ID-ul contactului pe platforma dumneavoastră (acesta corespunde cu `fromId` pe care l-ați trimis în mesajul de intrare) | | `channel` | Eticheta canalului personalizat pe care ați atribuit-o | Platforma dumneavoastră primește aceste date și le folosește pentru a livra răspunsul utilizatorului final prin propriul sistem. ### Cum urmărește platforma livrarea După trimiterea răspunsului către platforma dumneavoastră, platforma actualizează starea mesajului: - **Trimis** - Platforma dumneavoastră a primit mesajul cu succes. - **Eșuat** - Platforma dumneavoastră a returnat o eroare sau nu a putut fi accesată. Platforma stochează detaliile erorii împreună cu mesajul, astfel încât să puteți depana problema. --- ## Trimiterea mesajelor din sistemul tău către aplicație Pe lângă primirea mesajelor, poți trimite și mesaje de ieșire printr-un canal personalizat direct din propriul tău sistem. Acest lucru este util atunci când dorești să inițiezi o conversație sau să trimiți un mesaj proactiv. > **Cerință privind planul.** Trimiterea și sincronizarea mesajelor prin API necesită un plan care include acces API și cel puțin un canal de mesagerie. Dacă primești o eroare `403` „permission denied / feature not enabled”, planul tău actual nu include această funcționalitate — fă upgrade la planul tău sau contactează asistența. ### Unde să trimiți ``` POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY ``` ### Formatul mesajului ```json { "customData": { "fromId": "user-456", "customChannel": "my-live-chat", "body": "Hello! How can I help you today?", "campaignId": "optional-campaign-id", "firstName": "John", "lastName": "Doe", "email": "john@example.com" } } ``` ### Câmpuri obligatorii | Câmp | Ce face | |---|---| | `customData.fromId` | ID-ul contactului pe platforma ta | | `customData.customChannel` | Numele canalului tău personalizat (de ex., "my-live-chat") | | `customData.body` | Textul mesajului de trimis | Câmpurile opționale (`campaignId`, `firstName`, `lastName`, `email`) funcționează la fel ca în cazul mesajelor primite — acestea ajută platforma să creeze sau să actualizeze înregistrarea contactului. ### Ce primești înapoi ```json { "success": true, "messageId": "generated-message-id", "contactId": "contact-id", "message": "Message sent successfully" } ``` --- ## Înregistrarea mesajelor trimise dintr-un alt sistem Uneori, ați trimis deja un mesaj către un contact dintr-un instrument diferit (de exemplu, un flux de lucru într-o altă platformă) și doriți pur și simplu ca platforma să știe despre acest lucru, astfel încât AI-ul să aibă contextul complet. Acest lucru este diferit de trimitere: platforma înregistrează mesajul, dar **nu** îl livrează din nou contactului. ### Unde să trimiți ``` POST https://api.youraiconnector.com/v1/sync_custom_channel_message?apiKey=YOUR_API_KEY ``` Include `customData.fromId` (ID-ul contactului pe platforma ta) și `customData.body` (textul mesajului care a fost deja trimis). ### Cum se comportă - **Mesajul este înregistrat, nu retrimis.** Platforma îl stochează în conversație doar pentru context. - **AI-ul este întrerupt implicit pentru acel contact.** Acest lucru previne ca botul să răspundă peste un mesaj pe care un om l-a gestionat deja. Pentru a menține botul activ, transmiteți `customData.pauseAi: false`. - **Contactele noi pot fi create automat.** Includeți `customData.customChannel` și contactul va fi creat dacă nu există deja. - **Duplicatele sunt ignorate.** Dacă reutilizați același `messageSid`, platforma recunoaște că mesajul a fost deja înregistrat și nu face nicio modificare. > **Cerință privind planul.** La fel ca trimiterea, înregistrarea mesajelor prin API necesită un plan care să includă accesul la API și cel puțin un canal de mesagerie. O eroare de tip `403` "permission denied / feature not enabled" înseamnă că planul tău actual nu include acest lucru. --- ## Exemple din lumea reală ### Chat live pe site-ul web Conectați un widget de chat live de pe site-ul dvs. web la platformă, astfel încât Agentul dvs. AI să poată răspunde la întrebările vizitatorilor: 1. Un vizitator scrie un mesaj în widgetul de chat al site-ului tău. 2. Widgetul tău de chat trimite mesajul către platformă. 3. Agentul AI generează un răspuns. 4. Răspunsul este trimis înapoi către widgetul tău de chat, care îl afișează vizitatorului. **De ce este util:** Vizitatorii site-ului tău primesc răspunsuri instantanee, bazate pe AI, la întrebările lor, fără a fi nevoie să fii online. ### E-mail Direcționează conversațiile prin e-mail prin intermediul platformei, astfel încât Agentul tău AI să poată răspunde la e-mailuri: 1. Configurează un sistem care redirecționează e-mailurile primite către platformă (folosind adresa expeditorului e-mailului drept `fromId`, subiectul și corpul e-mailului drept `body` și `"email"` drept `channel`). 2. Agentul AI citește e-mailul și generează un răspuns. 3. Răspunsul este trimis înapoi către sistemul tău de e-mail, care îl expediază ca pe un răspuns normal prin e-mail. **De ce este util acest lucru:** Întrebările frecvente despre e-mail (prețuri, program, disponibilitate) sunt soluționate instantaneu de către Agentul tău AI. > Dacă sistemul tău de e-mail utilizează IMAP/SMTP sau OAuth, [canalul de e-mail](email.md) integrat poate fi mai simplu decât o integrare personalizată. ### Integrare CRM Conectează sistemul tău CRM (gestionarea relațiilor cu clienții) existent la platformă: 1. Atunci când un lead trimite un mesaj prin CRM-ul tău, redirecționează-l către platformă. 2. Agentul AI răspunde și urmărește conversația. 3. Răspunsul AI este trimis înapoi către CRM-ul tău pentru livrare. 4. Istoricul complet al conversației este disponibil atât în platformă, cât și în CRM-ul tău. **De ce este util:** Echipa ta de vânzări primește răspunsuri asistate de AI pentru potențialii clienți fără a părăsi CRM-ul. ### Sistem de tichete de asistență Utilizați platforma ca prim răspuns bazat pe inteligență artificială pentru asistența clienților: 1. Sistemul tău de ticketing redirecționează noile tichete de asistență către platformă. 2. Agentul AI trimite un răspuns inițial (de exemplu, confirmarea primirii tichetului și adresarea unor întrebări de clarificare). 3. Răspunsul este atașat tichetului în sistemul tău de asistență. 4. Echipa ta de asistență poate revizui ceea ce a spus AI-ul și poate prelua conversația atunci când este necesar. **De ce este util:** Clienții primesc o confirmare imediată și ajutor inițial, chiar și în afara orelor de program. --- ## Depanare ### Mesajele nu sunt primite de platformă - Verifică dacă cheia ta API este corectă și activă (verifică **Setări → Integrări → Cheie API**). - Asigură-te că trimiți o cerere POST (nu GET). Dezvoltatorul tău va cunoaște diferența. - Verifică dacă câmpul `customData.body` nu este gol sau conține doar spații albe. - Verifică dacă câmpul `customData.fromId` este inclus. - Citește mesajul de răspuns pentru detalii specifice despre eroare. ### Răspunsurile nu ajung la platforma dvs. - Asigură-te că ai introdus URL-ul platformei tale în cardul **Canal personalizat** de pe pagina Canale. Dacă nu este salvat niciun URL, răspunsurile sunt generate și stocate, dar nu sunt niciodată trimise — și **nu** vor fi marcate ca „Eșuate”, așa că verifică acest lucru mai întâi. - Verifică dacă URL-ul este accesibil public (nu se află în spatele unei autentificări sau al unui firewall) și dacă returnează un răspuns de succes. - Doar răspunsurile (mesajele de ieșire) sunt trimise către URL-ul tău — mesajele primite nu declanșează acest lucru. - Verifică detaliile erorii pentru mesajul din căsuța ta de primire. ### Contactul nu este creat - Asigură-te că valoarea `fromId` este consecventă pentru același utilizator în toate mesajele sale. Platforma folosește această valoare pentru a identifica contactele — dacă aceasta se modifică între mesaje, platforma va crea un contact nou de fiecare dată. - Include `firstName`, `lastName` și `email` în primul mesaj de la un contact nou pentru a crea o fișă de contact completă. ### Atașamentele media nu funcționează - Pentru linkurile către fișiere (URL-uri), asigurați-vă că fișierul este accesibil public (nu este necesară autentificarea pentru a-l accesa). - Includeți întotdeauna `mediaContentType` atunci când includeți `mediaUrl`. - Pentru fișierele încorporate (base64), verificați dacă formatul este `data:MIME_TYPE;base64,ENCODED_DATA`. - Asigurați-vă că tipul de fișier pe care îl specificați corespunde conținutului real al fișierului. --- ## Cele mai bune practici - **Folosește valori `fromId` consecvente.** Fiecare utilizator de pe platforma ta ar trebui să aibă întotdeauna același `fromId`. Acest lucru asigură că platforma grupează toate mesajele lor într-o singură conversație, în loc să creeze contacte duplicate. - **Alege un nume `channel` clar.** Alege ceva descriptiv precum `"website-chat"`, `"email"` sau `"zendesk"`, astfel încât să poți identifica ușor de unde provin mesajele atunci când îți vizualizezi căsuța de primire. - **Include detalii de contact** (`firstName`, `lastName`, `email`) în primul mesaj de la un contact nou. Acest lucru creează imediat o fișă de contact completă și utilă. - **Implementează logica de reîncercare.** Configurează platforma ta să reîncerce trimiterea mesajelor dacă platforma nu răspunde la prima încercare (pot apărea probleme de rețea). - **Folosește valori `messageSid` unice** pentru fiecare mesaj. Acest lucru previne procesarea aceluiași mesaj de două ori dacă sistemul tău îl trimite de mai multe ori. - **Folosește `campaignId`** pentru a direcționa mesajele către diferiți Agenți AI atunci când ai mai multe cazuri de utilizare (de exemplu, întrebări de vânzări vs. întrebări de asistență). - **Testează înainte de lansare.** Trimite mesaje de test în ambele direcții și verifică dacă contactele, conversațiile și răspunsurile AI funcționează corect înainte de a lansa serviciul pentru utilizatorii reali.