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, SMS, Instagram, Messenger). 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.

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):

{
  "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 #

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.

{
  "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ă:

{
  "success": true,
  "messageId": "1234567890"
}

Dacă ceva nu merge bine, veți primi un mesaj de eroare care explică problema:

{
  "error": "Message body cannot be empty"
}

Coduri de stare #

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:

{
  "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:

{
  "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"
}

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:

{
  "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 #

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 #

{
  "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â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 #

{
  "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 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.