Mukautetut kanavat #

Yhdistä mikä tahansa viestintäalusta tai viestintätyökalu alustaan mukautettujen kanavien avulla. Tämän avulla voit tuoda viestejä esimerkiksi verkkosivustojen live-chat-widgeteistä, sähköpostijärjestelmistä, CRM-järjestelmistä tai mistä tahansa muusta palvelusta postilaatikkoosi – ja vastata niihin tekoälyagentillasi.

Mitä mukautetut kanavat ovat? #

Mukautetut kanavat laajentavat alustaa sen sisäänrakennettujen viestintäalustojen (WhatsApp, SMS, Instagram, Messenger) ulkopuolelle. Mukautettujen kanavien avulla voit:

• Vastaanottaa viestejä mistä tahansa ulkoisesta alustasta alustan yhtenäiseen postilaatikkoon.
• Lähettää vastauksia sovelluksesta takaisin ulkoiselle alustallesi automaattisesti.
• Käyttää tekoälyagenttia vastaamaan viesteihin mistä tahansa lähteestä.
• Seurata kaikkia keskusteluja muiden kanaviesi rinnalla yhdessä postilaatikossa.

Tämä on ihanteellista yrityksille, jotka käyttävät erikoistuneita viestintätyökaluja, joilla on itse rakennettu alusta tai jotka haluavat kaikki asiakasviestit yhteen paikkaan.

Miten se toimii #

Mukautetut kanavat toimivat välittämällä viestejä edestakaisin ulkoisen alustasi ja tämän alustan välillä webhookien (järjestelmien välillä internetin kautta lähetettävät automaattiset viestit) avulla. Tässä on prosessin kulku:

Your Platform  ──(sends message to)──>  The App
                                           |
                                       AI Agent responds
                                       Contact saved
                                       Message stored
                                           |
The App  ──(sends reply to)──>  Your Platform

1. Saapuvat viestit: Ulkoinen alustasi lähettää viestejä verkko-osoitteeseen (URL). Ajattele tätä alustasi “lähettävän” viestin alustan postilaatikkoon.
2. Käsittely: Alusta luo tai päivittää yhteystiedon, tallentaa viestin ja antaa tekoälyagentin luoda vastauksen (jos se on aktiivinen).
3. Lähtevät viestit: Kun alusta lähettää vastauksen (olipa se tekoälyn luoma tai itse kirjoittamasi), se lähettää viestin alustallasi olevaan URL-osoitteeseen, josta järjestelmäsi voi toimittaa sen loppukäyttäjälle.

Saapuvien viestien määrittäminen (Alustaltasi sovellukseen) #

Jotta voit lähettää viestejä ulkoiselta alustaltasi sovellukseen, alustasi on lähetettävä tiedot seuraavaan URL-osoitteeseen. Kehittäjäsi tunnistaa tämän tavalliseksi POST-pyynnöksi (yleinen tapa, jolla yksi järjestelmä lähettää tietoja toiselle internetin välityksellä).

Mihin viestit lähetetään #

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY

Korvaa YOUR_API_KEY API-avaimellasi (yksityinen koodi, joka todistaa alustalle, että alustallasi on lupa lähettää sille viestejä). Löydät tai luot sen kohdasta Asetukset → Integraatiot → API-avain.

Viestin muoto #

Lähetä viestitiedot seuraavassa muodossa (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"
}

Mitä kukin osa tarkoittaa:

• messageSid - Yksilöllinen tunniste tälle nimenomaiselle viestille (järjestelmäsi luo tämän). Käytetään estämään saman viestin käsittely kahdesti.
• fromId - Kuka viestin lähetti (voi olla käyttäjätunnus, sähköpostiosoite tai puhelinnumero järjestelmästäsi).
• toId - Yrityksesi tunniste (voi olla mikä tahansa valitsemasi nimi).
• body - Varsinainen viestin teksti.
• channel - Valitsemasi tunniste, jolla tunnistat viestin alkuperän (esim. “website-chat”, “email”).

Täydellinen kenttäviite #

Emojireaktiot #

Jos alustasi tukee emojireaktioita (esimerkiksi peukalo ylös -reaktio viestiin), lähetä ne reaktiona tekstiviestin sijaan: aseta messageType arvoon "reaction" ja laita vain emoji kohtaan customData.body.

{
  "messageType": "reaction",
  "customData": {
    "messageSid": "reaction-123",
    "fromId": "user-42",
    "toId": "my-business",
    "body": "👍"
  }
}

Avustaja käsittelee sen tällöin odotetulla tavalla:

• Avustajan esittämään kysymykseen (esimerkiksi “Sopiiko torstai?”) annettu reaktio tulkitaan vastaukseksi, ja avustaja vastaa siihen.
• Lopetusviestiin (esimerkiksi “Puhutaan pian!”) annettu reaktio päättää keskustelun hiljaisesti. Vastausta ei lähetetä.

Jos alustasi muuttaa reaktiot tekstiksi, kuten “Reagoi viestiin: 👍”, avustaja näkee sen tavallisena tekstiviestinä ja päättää itse, vastaako se siihen. Reaktiotyypin lähettäminen välttää tämän.

Mitä saat vastauksena #

Onnistunut pyyntö palauttaa:

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

Jos jokin menee vikaan, saat virheilmoituksen, joka selittää ongelman:

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

Tilakoodit #

Jos asetat kohdan customData.status, ainoa hyväksytty arvo on "received" — jätä se kokonaan pois käyttääksesi oletusarvoa sen sijaan, että lähettäisit mitään muuta, tai saat virheen 400.

Medialiitteiden lähettäminen (kuvat, videot, tiedostot) #

Voit sisällyttää viesteihisi tiedostoliitteitä (kuvia, videoita, ääntä, asiakirjoja). Tähän on kaksi tapaa:

Vaihtoehto 1: Linkki tiedostoon #

Jos tiedosto on jo verkossa, anna URL-osoite (verkko-osoite), josta alusta voi ladata sen:

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

Vaihtoehto 2: Upota tiedosto suoraan (Base64) #

Jos tiedostoa ei ole isännöity verkossa, voit upottaa sen suoraan viestiin koodattuna tekstinä (base64-muodossa). Tämä on yleistä teknisissä integraatioissa, joissa järjestelmäsi luo tiedostoja lennosta. Alusta purkaa koodauksen ja tallentaa tiedoston automaattisesti:

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

Lähtevien viestien määrittäminen (alustasta sinun alustallesi) #

Kun alusta lähettää vastauksen mukautetulla kanavalla (olipa se tekoälyn luoma tai itse kirjoittamasi), se lähettää vastauksen automaattisesti alustallasi olevaan URL-osoitteeseen, jotta järjestelmäsi voi toimittaa sen loppukäyttäjälle.

Aseta webhook-URL ensin. Sinun on tallennettava mukautetun kanavan webhook-URL ennen kuin vastauksia voidaan toimittaa. Jos URL-osoitetta ei ole tallennettu, vastaukset luodaan ja tallennetaan silti, mutta niitä ei koskaan lähetetä – eivätkä ne näytä “Epäonnistui”-tilaa, joten mikään postilaatikossasi ei ilmoita ongelmasta. Määritä webhook-URL aina ennen käyttöönottoa.

Kerro sovellukselle, minne vastaukset lähetetään #

1. Napsauta vasemmassa sivupalkissa alareunan lähellä olevaa kohtaa Asetukset.
2. Napsauta Asetusten vasemmassa reunassa kohdan Kanavat alta Kanavat.
3. Etsi sivun alareunasta Mukautettu kanava -kortti (Android SMS Gatewayn, iMessagen, verkkosivuston chat-widgetin, Twilio-tilin ja säädöstenmukaisuuden alapuolelta).
4. Syötä Webhook URL — se URL-osoite alustallasi, johon tekoälyn tulisi lähettää lähtevät viestit (kehittäjäsi määrittää tämän vastaanottamaan ja käsittelemään vastauksia). Sen on oltava julkinen HTTPS-URL — http://-osoitteet ja ei-julkiset isännät hylätään.
5. Napsauta Tallenna.

Mitä alusta lähettää alustallesi #

Kun alusta lähettää vastauksen, alustasi vastaanottaa seuraavat tiedot:

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

Mitä kukin kenttä tarkoittaa #

Alustasi vastaanottaa nämä tiedot ja käyttää niitä vastauksen toimittamiseen loppukäyttäjälle oman järjestelmäsi kautta.

Miten alusta seuraa toimitusta #

Lähetettyään vastauksen alustallesi, alusta päivittää viestin tilan:

• Lähetetty - Alustasi vastaanotti viestin onnistuneesti.
• Epäonnistunut - Alustasi palautti virheen tai siihen ei saatu yhteyttä. Alusta tallentaa virheen tiedot viestin yhteyteen, jotta voit selvittää ongelman.

Viestien lähettäminen järjestelmästäsi sovellukseen #

Viestien vastaanottamisen lisäksi voit myös lähettää lähteviä viestejä mukautetun kanavan kautta suoraan omasta järjestelmästäsi. Tämä on hyödyllistä, kun haluat aloittaa keskustelun tai lähettää proaktiivisen viestin.

Tilausvaatimus. Viestien lähettäminen ja synkronointi API:n kautta edellyttää tilausta, joka sisältää API-käyttöoikeuden ja vähintään yhden viestintäkanavan. Jos saat 403 “permission denied / feature not enabled” -virheen, nykyinen tilauksesi ei sisällä tätä ominaisuutta – päivitä tilauksesi tai ota yhteyttä tukeen.

Minne lähettää #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY

Viestin muoto #

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

Pakolliset kentät #

Valinnaiset kentät (campaignId, firstName, lastName, email) toimivat samalla tavalla kuin saapuvissa viesteissä – ne auttavat alustaa luomaan tai päivittämään yhteystietueen.

Mitä saat vastauksena #

{
  "success": true,
  "messageId": "generated-message-id",
  "contactId": "contact-id",
  "message": "Message sent successfully"
}

Toisesta järjestelmästä lähetettyjen viestien tallentaminen #

Joskus olet jo lähettänyt viestin yhteystiedolle toisesta työkalusta (esimerkiksi toisen alustan työnkulusta) ja haluat vain, että alusta tietää siitä, jotta tekoälyllä on täysi konteksti. Tämä eroaa lähettämisestä: alusta tallentaa viestin, mutta ei lähetä sitä uudelleen yhteystiedolle.

Minne lähettää #

POST https://api.youraiconnector.com/v1/sync_custom_channel_message?apiKey=YOUR_API_KEY

Sisällytä customData.fromId (yhteyshenkilön tunnus alustallasi) ja customData.body (jo lähetetty viestiteksti).

Miten se toimii #

• Viesti tallennetaan, ei lähetetä uudelleen. Alusta tallentaa sen keskusteluun vain kontekstia varten.
• Tekoäly on oletusarvoisesti tauotettu kyseisen yhteystiedon kohdalla. Tämä estää bottia vastaamasta viestiin, jonka ihminen on jo käsitellyt. Jos haluat pitää botin aktiivisena, välitä customData.pauseAi: false.
• Uusia yhteystietoja voidaan luoda automaattisesti. Sisällytä customData.customChannel, niin yhteystieto luodaan, jos sitä ei vielä ole olemassa.
• Kaksoiskappaleet jätetään huomiotta. Jos käytät samaa messageSid-tunnistetta uudelleen, alusta tunnistaa, että viesti on jo tallennettu, eikä tee muutoksia.

Tilausvaatimus. Viestien lähettämisen tavoin viestien tallentaminen API:n kautta edellyttää tilausta, joka sisältää API-käyttöoikeuden ja vähintään yhden viestintäkanavan. 403 “permission denied / feature not enabled” -virhe tarkoittaa, että nykyinen tilauksesi ei sisällä tätä ominaisuutta.

Käytännön esimerkkejä #

Verkkosivuston live-chat #

Yhdistä verkkosivustosi live-chat-widget alustaan, jotta tekoälyagenttisi voi vastata vierailijoiden kysymyksiin:

1. Kävijä kirjoittaa viestin verkkosivustosi chat-widgetiin.
2. Chat-widgetisi lähettää viestin alustalle.
3. AI-agentti luo vastauksen.
4. Vastaus lähetetään takaisin chat-widgetiisi, joka näyttää sen kävijälle.

Miksi tämä on hyödyllistä: Verkkosivustosi vierailijat saavat välittömiä, tekoälypohjaisia vastauksia kysymyksiinsä ilman, että sinun tarvitsee olla paikalla.

Sähköposti #

Ohjaa sähköpostikeskustelut alustan kautta, jotta AI-agenttisi voi vastata sähköposteihin:

1. Määritä järjestelmä, joka välittää saapuvat sähköpostit alustalle (käyttäen sähköpostin lähettäjän osoitetta fromId-kentässä, sähköpostin aihetta ja runkoa body-kentässä sekä "email"-arvoa channel-kentässä).
2. AI-agentti lukee sähköpostin ja luo vastauksen.
3. Vastaus lähetetään takaisin sähköpostijärjestelmääsi, joka lähettää sen tavallisena sähköpostivastauksena.

Miksi tämä on hyödyllistä: AI-agenttisi vastaa välittömästi yleisiin sähköpostikysymyksiin (hinnoittelu, aukioloajat, saatavuus).

Jos sähköpostijärjestelmäsi tukee IMAP/SMTP- tai OAuth-protokollia, sisäänrakennettu Sähköpostikanava voi olla yksinkertaisempi kuin mukautettu integraatio.

CRM-integraatio #

Yhdistä nykyinen CRM-järjestelmäsi (asiakkuudenhallinta) alustaan:

1. Kun liidi lähettää viestin CRM-järjestelmäsi kautta, välitä se alustalle.
2. AI-agentti vastaa ja seuraa keskustelua.
3. AI-vastaus lähetetään takaisin CRM-järjestelmääsi toimitettavaksi.
4. Koko keskusteluhistoria on saatavilla sekä alustassa että CRM-järjestelmässäsi.

Miksi tämä on hyödyllistä: Myyntitiimisi saa tekoälyavusteisia vastauksia liideille poistumatta CRM-järjestelmästään.

Tukipyyntöjärjestelmä #

Käytä alustaa tekoälypohjaisena ensivasteena asiakastuessa:

1. Tikettijärjestelmäsi välittää uudet tukitiketit alustalle.
2. AI-agentti lähettää alustavan vastauksen (esim. kuittaa tiketin vastaanotetuksi ja esittää tarkentavia kysymyksiä).
3. Vastaus liitetään tikettiin tukijärjestelmässäsi.
4. Tukitiimisi voi tarkistaa, mitä AI on sanonut, ja ottaa keskustelun haltuun tarvittaessa.

Miksi tämä on hyödyllistä: Asiakkaat saavat välittömän kuittauksen ja ensiapua, myös aukioloaikojen ulkopuolella.

Vianmääritys #

Viestit eivät saavu alustalle #

• Varmista, että API-avaimesi on oikea ja aktiivinen (tarkista Asetukset → Integraatiot → API-avain).
• Varmista, että lähetät POST-pyynnön (et GET-pyyntöä). Kehittäjäsi tietää eron.
• Tarkista, ettei customData.body-kenttä ole tyhjä tai sisällä vain välilyöntejä.
• Varmista, että customData.fromId-kenttä on sisällytetty.
• Lue vastausviesti saadaksesi tarkat virhetiedot.

Vastaukset eivät saavu alustallesi #

• Varmista, että olet syöttänyt alustasi URL-osoitteen Kanavat-sivun Mukautettu kanava -korttiin. Jos URL-osoitetta ei ole tallennettu, vastaukset luodaan ja tallennetaan, mutta niitä ei koskaan lähetetä — eikä niitä merkitä “Epäonnistuneiksi”, joten tarkista tämä ensin.
• Varmista, että URL-osoite on julkisesti käytettävissä (ei kirjautumisen tai palomuurin takana) ja palauttaa onnistuneen vastauksen.
• Vain vastaukset (lähtevät viestit) lähetetään URL-osoitteeseesi — saapuvat viestit eivät käynnistä tätä.
• Tarkista viestin virhetiedot postilaatikostasi.

Yhteystietoa ei luoda #

• Varmista, että fromId-arvo on johdonmukainen samalle käyttäjälle kaikissa hänen viesteissään. Alusta käyttää tätä arvoa yhteystietojen tunnistamiseen — jos se muuttuu viestien välillä, alusta luo joka kerta uuden yhteystiedon.
• Sisällytä firstName, lastName ja email uuden yhteystiedon ensimmäiseen viestiin, jotta voit luoda täydellisen yhteystietueen.

Medialiitteet eivät toimi #

• Tiedostolinkkien (URL-osoitteiden) kohdalla varmista, että tiedosto on julkisesti käytettävissä (ei vaadi kirjautumista).
• Sisällytä aina mediaContentType, kun sisällytät mediaUrl-tiedoston.
• Upotettujen tiedostojen (base64) kohdalla varmista, että muoto on data:MIME_TYPE;base64,ENCODED_DATA.
• Varmista, että määrittämäsi tiedostotyyppi vastaa tiedoston todellista sisältöä.

Parhaat käytännöt #

• Käytä johdonmukaisia fromId-arvoja. Jokaisella alustasi käyttäjällä tulisi aina olla sama fromId. Tämä varmistaa, että alusta ryhmittelee kaikki heidän viestinsä yhdeksi keskusteluksi sen sijaan, että se loisi päällekkäisiä yhteystietoja.
• Valitse selkeä channel-nimi. Valitse jotain kuvaavaa, kuten "website-chat", "email" tai "zendesk", jotta näet helposti, mistä viestit ovat peräisin, kun tarkastelet postilaatikkoasi.
• Sisällytä yhteystiedot (firstName, lastName, email) uuden yhteystiedon ensimmäiseen viestiin. Tämä luo heti täydellisen ja hyödyllisen yhteystietueen.
• Rakenna uudelleenyritysmekanismi. Anna alustasi yrittää viestien lähettämistä uudelleen, jos alusta ei vastaa ensimmäisellä yrityksellä (verkko-ongelmia sattuu).
• Käytä yksilöllisiä messageSid-arvoja jokaisessa viestissä. Tämä estää saman viestin käsittelemisen kahdesti, jos järjestelmäsi lähettää sen useammin kuin kerran.
• Käytä campaignId-arvoa viestien reitittämiseen eri AI-agenteille, kun sinulla on useita käyttötapauksia (esim. myyntikyselyt vs. tukikysymykset).
• Testaa ennen julkaisua. Lähetä testiviestejä molempiin suuntiin ja varmista, että yhteystiedot, keskustelut ja AI-vastaukset toimivat oikein ennen kuin julkaiset palvelun todellisille käyttäjille.