Aangepaste kanalen #

Verbind elk berichtenplatform of communicatietool met het platform via aangepaste kanalen. Hiermee kun je berichten van platforms zoals live chat-widgets op websites, e-mailsystemen, CRM’s of elke andere dienst in je inbox ontvangen — en ze beantwoorden met je AI-agent.

Wat zijn aangepaste kanalen? #

Aangepaste kanalen breiden het platform uit voorbij de ingebouwde berichtenplatforms (WhatsApp, SMS, Instagram, Messenger). Met aangepaste kanalen kun je:

• Berichten ontvangen van elk extern platform in de centrale inbox van het platform.
• Antwoorden versturen vanuit de app terug naar je externe platform, automatisch.
• Een AI-agent gebruiken om berichten van elke bron te beantwoorden.
• Alle gesprekken volgen naast je andere kanalen in één inbox.

Dit is ideaal voor bedrijven die gespecialiseerde communicatiemiddelen gebruiken, een eigen platform hebben gebouwd of alle klantberichten op één plek willen hebben.

Hoe het werkt #

Aangepaste kanalen werken door berichten heen en weer te sturen tussen je externe platform en het platform via webhooks (geautomatiseerde berichten die via internet tussen systemen worden verstuurd). Dit is de stroom:

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

1. Inkomende berichten: Uw externe platform verstuurt berichten naar een webadres (URL). Zie het als uw platform dat een bericht “plaatst” in de mailbox van het platform.
2. Verwerking: Het platform maakt de contactpersoon aan of werkt deze bij, slaat het bericht op en laat een AI-agent een antwoord genereren (indien actief).
3. Uitgaande berichten: Wanneer het platform een antwoord verstuurt (of dit nu van de AI komt of door u is getypt), stuurt het het bericht naar een URL op uw platform, waar uw systeem het kan afleveren bij de eindgebruiker. Antwoorden kunnen ook een bestand bevatten: een item dat de AI-agent verstuurt vanuit zijn mediabibliotheek, een bijlage of spraakbericht uit de inbox, of een bestand dat via de API wordt verstuurd en aankomt als een downloadlink naast de tekst.

Inkomende berichten instellen (Jouw platform naar de app) #

Om berichten van je externe platform naar de app te sturen, moet je platform gegevens versturen naar de volgende URL. Je ontwikkelaar zal dit herkennen als een standaard POST-verzoek (een gebruikelijke manier voor systemen om gegevens via internet naar elkaar te sturen).

Waar berichten naartoe sturen #

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

Vervang YOUR_API_KEY door je API-sleutel (een privégecode die aan het platform bewijst dat jouw platform berichten mag sturen). Je kunt deze vinden of genereren onder Instellingen → Integraties → API-sleutel.

Een scoped key werkt ook, zolang deze niet alleen-lezen is en de gebieden Messages bevat. Berichten komen aan op het account waartoe de sleutel behoort, dus gebruik de sleutel van het account (of sub-account) wiens inbox ze moet ontvangen.

Berichtindeling #

Verstuur de berichtgegevens in het volgende formaat (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"
}

Wat elk onderdeel betekent:

• messageSid - Een unieke ID voor dit specifieke bericht (uw systeem maakt dit aan). Wordt gebruikt om te voorkomen dat hetzelfde bericht twee keer wordt verwerkt.
• fromId - Wie het bericht heeft verzonden (kan een gebruikers-ID, e-mailadres of telefoonnummer uit uw systeem zijn).
• toId - Uw bedrijfs-ID (kan elk label zijn dat u kiest).
• body - De eigenlijke berichttekst.
• channel - Een label dat u kiest om te identificeren waar het bericht vandaan kwam (bijv. “website-chat”, “email”). Dit wordt de kanaalnaam die voor dat contact in de inbox en in meldingen wordt getoond.

Volledige veldreferentie #

Emoji-reacties #

Als je platform emoji-reacties ondersteunt (bijvoorbeeld een duimpje omhoog bij een bericht), stuur deze dan als een reactie in plaats van als een tekstbericht: stel messageType in op "reaction" en plaats alleen de emoji in customData.body.

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

De assistent behandelt dit vervolgens zoals je zou verwachten:

• Een reactie op een vraag die de assistent stelde (bijvoorbeeld “Schikt donderdag?”) wordt behandeld als het antwoord, en de assistent antwoordt.
• Een reactie op een afsluitend bericht (bijvoorbeeld “Tot snel!”) beëindigt het gesprek geruisloos. Er wordt geen antwoord gestuurd.

Als je platform reacties omzet in tekst zoals “Reageerde met: 👍”, ziet de assistent een normaal tekstbericht en beslist zelf of er geantwoord moet worden. Door het reactietype te sturen, voorkom je dat.

Wat u terugkrijgt #

Een succesvol verzoek retourneert:

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

Als er iets misgaat, ontvangt u een foutmelding waarin het probleem wordt uitgelegd:

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

Statuscodes #

Als u customData.status instelt, is de enige geaccepteerde waarde "received" — laat deze volledig weg om de standaardwaarde te gebruiken in plaats van iets anders te sturen, anders krijgt u een 400.

Mediabijlagen verzenden (afbeeldingen, video’s, bestanden) #

Dit gedeelte behandelt bestanden die binnenkomen (van uw platform naar de app). Voor bestanden die uitgaan met een antwoord, zie Antwoorden met bestanden.

U kunt bestandsbijlagen (afbeeldingen, video’s, audio, documenten) bij uw berichten voegen. Er zijn twee manieren om dit te doen:

Optie 1: Link naar een bestand #

Als het bestand al online wordt gehost, geef dan de URL (webadres) op waar het platform het kan downloaden:

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

Optie 2: Het bestand direct insluiten (Base64) #

Als het bestand niet online wordt gehost, kun je het direct in het bericht insluiten als gecodeerde tekst (base64-indeling). Dit is gebruikelijk bij technische integraties waarbij je systeem bestanden on-the-fly genereert. Het platform zal het bestand automatisch decoderen en opslaan:

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

Uitgaande berichten instellen (het platform naar jouw platform) #

Wanneer het platform een antwoord verstuurt via een aangepast kanaal (of dit nu van de AI komt of door jou is getypt), stuurt het dit antwoord automatisch naar een URL op jouw platform, zodat jouw systeem het kan afleveren bij de eindgebruiker.

Stel eerst de webhook-URL in. Je moet de webhook-URL van het aangepaste kanaal opslaan voordat er antwoorden kunnen worden afgeleverd. Als er geen URL is opgeslagen, worden antwoorden nog steeds gegenereerd en opgeslagen, maar ze worden nooit verzonden — en ze zullen geen “Mislukt”-status tonen, dus niets in je inbox markeert het probleem. Configureer de webhook-URL altijd voordat je live gaat.

Vertel de app waar antwoorden naartoe moeten worden gestuurd #

1. Klik in de linkerzijbalk onderaan op Instellingen.
2. Klik in de linker kolom van Instellingen onder Kanalen op Kanalen.
3. Zoek de kaart Aangepast kanaal helemaal onderaan de pagina (voorbij Android SMS Gateway, iMessage, de website-chatwidget, Twilio-account en Naleving van regelgeving).
4. Voer de Webhook-URL in — de URL op uw platform waar de AI uitgaande berichten naartoe moet sturen (uw ontwikkelaar stelt dit in om antwoorden te ontvangen en te verwerken). Dit moet een openbare HTTPS-URL zijn — http://-adressen en niet-openbare hosts worden geweigerd.
5. Klik op Opslaan.

Wat het platform naar jouw platform stuurt #

Wanneer het platform een antwoord verstuurt, ontvangt jouw platform de volgende gegevens:

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

Wat elk veld betekent #

Jouw platform ontvangt deze gegevens en gebruikt ze om het antwoord via jouw eigen systeem bij de eindgebruiker af te leveren.

Antwoorden met bestanden #

Een antwoord bevat een bestand wanneer:

• de AI-agent een item uit zijn mediabibliotheek verstuurt (een brochure, een prijslijst, een foto),
• iemand een bestand bijvoegt of een spraakbericht opneemt in de inbox,
• een bericht wordt verstuurd via de API met mediaUrl en mediaContentType.

Het bestand komt aan in dezelfde webhook-aanroep als de tekst, in de vier media… velden hierboven. Een antwoord met alleen tekst heeft deze allemaal ingesteld op null (en isVoiceNote op false), zodat een ontvanger die alleen body leest, ongewijzigd blijft werken.

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

Haal mediaUrl op met een eenvoudige GET (geen login, geen extra headers) en stuur het bestand door naar de eindgebruiker via uw eigen kanaal. Lever body af als het bijschrift of als een apart tekstbericht, afhankelijk van wat uw kanaal ondersteunt.

Hoe het platform de aflevering bijhoudt #

Nadat het antwoord naar jouw platform is verzonden, werkt het platform de berichtstatus bij:

• Verzonden - Jouw platform heeft het bericht succesvol ontvangen.
• Mislukt - Jouw platform gaf een foutmelding of was niet bereikbaar. Het platform slaat de foutdetails op bij het bericht, zodat je problemen kunt oplossen.

Berichten verzenden vanuit uw systeem naar de app #

Naast het ontvangen van berichten kunt u ook uitgaande berichten via een aangepast kanaal rechtstreeks vanuit uw eigen systeem verzenden. Dit is handig wanneer u een gesprek wilt starten of een proactief bericht wilt sturen.

Abonnementsvereiste. Voor het verzenden en synchroniseren van berichten via de API is een abonnement vereist dat API-toegang en ten minste één berichtkanaal bevat. Als u een 403 “permission denied / feature not enabled”-foutmelding ontvangt, bevat uw huidige abonnement dit niet — upgrade uw abonnement of neem contact op met de ondersteuning.

Waar naartoe verzenden #

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

Berichtindeling #

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

Vereiste velden #

De optionele velden (campaignId, firstName, lastName, email) werken op dezelfde manier als bij inkomende berichten — ze helpen het platform bij het aanmaken of bijwerken van het contactrecord.

Wat u terugkrijgt #

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

Berichten registreren die vanuit een ander systeem zijn verzonden #

Soms heb je al een bericht naar een contactpersoon gestuurd vanuit een andere tool (bijvoorbeeld een workflow in een ander platform) en wil je simpelweg dat het platform hiervan op de hoogte is, zodat de AI over de volledige context beschikt. Dit is anders dan verzenden: het platform registreert het bericht maar verstuurt het niet opnieuw naar de contactpersoon.

Waar naartoe verzenden #

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

Voeg customData.fromId (het ID van de contactpersoon op uw platform) en customData.body (de berichttekst die al is verzonden) toe.

Hoe het zich gedraagt #

• Het bericht wordt geregistreerd, niet opnieuw verzonden. Het platform slaat het alleen op in het gesprek voor de context.
• De AI wordt standaard gepauzeerd voor die contactpersoon. Dit voorkomt dat de bot antwoordt op een bericht dat al door een mens is afgehandeld. Om de bot actief te houden, geef je customData.pauseAi: false door.
• Nieuwe contactpersonen kunnen automatisch worden aangemaakt. Voeg customData.customChannel toe en de contactpersoon wordt aangemaakt als deze nog niet bestaat.
• Dubbele berichten worden genegeerd. Als je dezelfde messageSid opnieuw gebruikt, herkent het platform dat het bericht al is geregistreerd en worden er geen wijzigingen aangebracht.

Abonnementsvereiste. Net als bij het verzenden, vereist het opnemen van berichten via de API een abonnement dat API-toegang en ten minste één berichtkanaal bevat. Een 403 “permission denied / feature not enabled”-fout betekent dat uw huidige abonnement dit niet bevat.

Praktijkvoorbeelden #

Livechat op website #

Verbind een live chat-widget op je website met het platform zodat je AI-agent vragen van bezoekers kan beantwoorden:

1. Een bezoeker typt een bericht in de chatwidget van uw website.
2. Uw chatwidget verstuurt het bericht naar het platform.
3. De AI-agent genereert een antwoord.
4. Het antwoord wordt teruggestuurd naar uw chatwidget, die het aan de bezoeker toont.

Waarom dit nuttig is: Uw websitebezoekers krijgen direct AI-gestuurde antwoorden op hun vragen zonder dat u online hoeft te zijn.

E-mail #

Routeer e-mailgesprekken via het platform zodat uw AI-agent op e-mails kan reageren:

1. Stel een systeem in dat inkomende e-mails doorstuurt naar het platform (gebruik het adres van de e-mailafzender als de fromId, het e-mailonderwerp en de hoofdtekst als de body, en "email" als de channel).
2. De AI-agent leest de e-mail en genereert een antwoord.
3. Het antwoord wordt teruggestuurd naar uw e-mailsysteem, dat het als een normale e-mailreactie verstuurt.

Waarom dit nuttig is: Veelgestelde e-mailvragen (over prijzen, openingstijden, beschikbaarheid) worden direct beantwoord door uw AI-agent.

Als uw e-mailsysteem IMAP/SMTP of OAuth ondersteunt, is het ingebouwde E-mailkanaal wellicht eenvoudiger dan een aangepaste integratie.

CRM-integratie #

Verbind uw bestaande CRM-systeem (customer relationship management) met het platform:

1. Wanneer een lead een bericht stuurt via uw CRM, stuurt u dit door naar het platform.
2. De AI-agent reageert en volgt het gesprek.
3. Het AI-antwoord wordt teruggestuurd naar uw CRM voor aflevering.
4. De volledige gespreksgeschiedenis is beschikbaar in zowel het platform als uw CRM.

Waarom dit nuttig is: Uw verkoopteam krijgt AI-ondersteunde antwoorden aan leads zonder hun CRM te verlaten.

Supportticketsysteem #

Gebruik het platform als een AI-gestuurde eerstehulpverlener voor klantenondersteuning:

1. Uw ticketsysteem stuurt nieuwe supporttickets door naar het platform.
2. De AI-agent stuurt een eerste reactie (bijv. een ontvangstbevestiging van het ticket en het stellen van verduidelijkende vragen).
3. Het antwoord wordt gekoppeld aan het ticket in uw supportsysteem.
4. Uw supportteam kan bekijken wat de AI heeft gezegd en het overnemen wanneer dat nodig is.

Waarom dit nuttig is: Klanten krijgen direct een ontvangstbevestiging en eerste hulp, zelfs buiten kantooruren.

Probleemoplossing #

Berichten worden niet ontvangen door het platform #

• Controleer of uw API-sleutel correct en actief is (kijk bij Instellingen → Integraties → API-sleutel).
• Zorg ervoor dat u een POST-verzoek verstuurt (geen GET). Uw ontwikkelaar weet wat het verschil is.
• Controleer of het customData.body-veld niet leeg is of alleen uit witruimte bestaat.
• Controleer of het customData.fromId-veld is opgenomen.
• Lees het antwoordbericht voor specifieke foutdetails.

Antwoorden bereiken je platform niet #

• Zorg ervoor dat u de URL van uw platform hebt ingevoerd in de kaart Aangepast kanaal op de pagina Kanalen. Als er geen URL is opgeslagen, worden antwoorden wel gegenereerd en opgeslagen, maar nooit verzonden — en ze worden niet gemarkeerd als “Mislukt”, dus controleer dit eerst.
• Controleer of de URL publiek toegankelijk is (niet achter een login of firewall) en een succesrespons retourneert.
• Alleen antwoorden (uitgaande berichten) worden naar uw URL gestuurd — inkomende berichten activeren dit niet.
• Controleer op foutdetails bij het bericht in uw inbox.
• Een antwoord met een bestand komt aan in dezelfde aanroep, met de downloadlink in mediaUrl. Als uw ontvanger alleen body doorstuurt, wordt het bestand aan uw kant genegeerd — lees ook de media… velden (zie Antwoorden met bestanden).
• De mediaUrl link verloopt na één uur. Download het bestand wanneer de webhook binnenkomt, niet later vanuit een wachtrij.

Contactpersoon wordt niet aangemaakt #

• Zorg ervoor dat de fromId-waarde consistent is voor dezelfde gebruiker bij al zijn berichten. Het platform gebruikt deze waarde om contacten te identificeren — als deze verandert tussen berichten, maakt het platform elke keer een nieuw contact aan.
• Voeg firstName, lastName en email toe in het eerste bericht van een nieuw contact om een volledig contactrecord aan te maken.

Media-bijlagen werken niet #

• Zorg er bij bestandskoppelingen (URL’s) voor dat het bestand publiek toegankelijk is (geen login vereist om het te openen).
• Voeg altijd mediaContentType toe wanneer je mediaUrl opneemt.
• Controleer bij ingesloten bestanden (base64) of het formaat data:MIME_TYPE;base64,ENCODED_DATA is.
• Zorg ervoor dat het bestandstype dat je opgeeft overeenkomt met de werkelijke inhoud van het bestand.

Best practices #

• Gebruik consistente fromId-waarden. Elke gebruiker op uw platform moet altijd dezelfde fromId hebben. Dit zorgt ervoor dat het platform al hun berichten groepeert in één gesprek in plaats van dubbele contacten aan te maken.
• Kies een duidelijke channel-naam. Kies iets beschrijvends zoals "website-chat", "email" of "zendesk", zodat u gemakkelijk kunt zien waar berichten vandaan kwamen wanneer u uw inbox bekijkt.
• Voeg contactgegevens toe (firstName, lastName, email) in het eerste bericht van een nieuw contact. Dit creëert direct een volledig en nuttig contactrecord.
• Bouw retry-logica in. Laat uw platform het verzenden van berichten opnieuw proberen als het platform niet reageert bij de eerste poging (netwerkstoringen komen voor).
• Gebruik unieke messageSid-waarden voor elk bericht. Dit voorkomt dat hetzelfde bericht twee keer wordt verwerkt als uw systeem het meer dan eens verstuurt.
• Gebruik campaignId om berichten naar verschillende AI-agenten te routeren wanneer u meerdere gebruiksgevallen heeft (bijv. verkoopvragen versus supportvragen).
• Test voordat u live gaat. Verstuur testberichten in beide richtingen en controleer of contacten, gesprekken en AI-antwoorden allemaal correct werken voordat u lanceert voor echte gebruikers.