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 tapana “postittaa” viesti alustan postilaatikkoon.
2. Käsittely: Alusta luo tai päivittää yhteystiedon, tallentaa viestin ja antaa tekoälyagentin luoda vastauksen (jos se on käytössä).
3. Lähtevät viestit: Kun alusta lähettää vastauksen (olipa se tekoälyn luoma tai itse kirjoittamasi), se lähettää viestin alustasi URL-osoitteeseen, josta järjestelmäsi voi toimittaa sen loppukäyttäjälle. Vastaukset voivat sisältää myös tiedoston: tekoälyagentin mediakirjastosta lähettämän kohteen, saapuneet-kansiosta tulevan liitteen tai ääniviestin, tai API:n kautta lähetetyn tiedoston, joka saapuu tekstin ohessa olevana latauslinkkinä.

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.

Myös rajattu avain toimii, kunhan se ei ole vain luku -muotoinen ja sen alueisiin kuuluvat Viestit. Viestit päätyvät sille tilille, johon avain kuuluu, joten käytä sen tilin (tai alitilin) avainta, jonka postilaatikkoon haluat niiden saapuvan.

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 järjestelmäsi käyttäjätunnus, sähköpostiosoite tai puhelinnumero).
• toId - Yrityksesi tunniste (voi olla mikä tahansa valitsemasi nimi).
• body - Varsinainen viestiteksti.
• channel - Valitsemasi nimi, jolla tunnistat viestin alkuperän (esim. “verkkosivun-chat”, “sähköposti”). Se näkyy kyseisen yhteyshenkilön kanavan nimenä postilaatikossa ja ilmoituksissa.

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

Tämä osio käsittelee saapuvia tiedostoja (alustaltasi sovellukseen). Vastauksen mukana lähtevistä tiedostoista voit lukea kohdasta Vastaukset tiedostojen kanssa.

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",
  "mediaUrl": null,
  "mediaContentType": null,
  "mediaFileName": null,
  "isVoiceNote": false
}

Mitä kukin kenttä tarkoittaa #

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

Vastaukset tiedostojen kanssa #

Vastaus sisältää tiedoston, kun:

• tekoälyagentti lähettää kohteen mediakirjastostaan (esite, hinnasto, valokuva),
• joku liittää tiedoston tai tallentaa ääniviestin saapuneet-kansiossa,
• viesti lähetetään API:n kautta käyttäen mediaUrl ja mediaContentType.

Tiedosto saapuu samassa webhook-kutsussa kuin teksti, yllä mainituissa neljässä media…-kentässä. Pelkkää tekstiä sisältävässä vastauksessa ne kaikki on asetettu arvoon null (ja isVoiceNote arvoon false), joten vastaanotin, joka lukee vain body-kenttää, toimii edelleen muuttumattomana.

{
  "contactId": "abc123",
  "messageId": "msg-789",
  "userId": "your-user-id",
  "body": "Here is our pricing breakdown.",
  "toId": "user-456",
  "channel": "my-live-chat",
  "mediaUrl": "https://storage.googleapis.com/.../Pricing.pdf?X-Goog-Signature=...",
  "mediaContentType": "application/pdf",
  "mediaFileName": "Pricing.pdf",
  "isVoiceNote": false
}

Nouda mediaUrl tavallisella GET-pyynnöllä (ei kirjautumista, ei ylimääräisiä otsikoita) ja välitä tiedosto loppukäyttäjälle oman kanavasi kautta. Toimita body kuvatekstinä tai erillisenä tekstiviestinä, riippuen siitä, kumpaa kanavasi tukee.

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 Mukautettu kanava -korttiin Kanavat-sivulla. 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 että se palauttaa onnistuneen vastauksen.
• Vain vastaukset (lähtevät viestit) lähetetään URL-osoitteeseesi — saapuvat viestit eivät käynnistä tätä.
• Tarkista virhetiedot viestistä saapuneet-kansiossasi.
• Tiedoston sisältävä vastaus saapuu samassa kutsussa, ja latauslinkki on kentässä mediaUrl. Jos vastaanottimesi välittää vain body-kentän, tiedosto hylätään päädyssäsi — lue myös media…-kentät (katso Vastaukset tiedostojen kanssa).
• mediaUrl-linkki vanhenee tunnin kuluttua. Lataa se webhookin saapuessa, älä myöhemmin jonosta.

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.