• Bouw je eigen integraties met Voys
• De vier bouwstenen
• API: jouw software haalt iets op bij ons
• Gespreksnotificaties: wij sturen iets naar jou
• Belplan-webhook: wij vragen jou iets terwijl de telefoon nog overgaat
• Klik-en-bel: bellen met één klik
• API's in één oogopslag
• Wat kun je hiermee bouwen?
• Zelf bouwen of iets kant-en-klaars gebruiken?
• Verantwoordelijkheid en support
• FAQ

Bouw je eigen integraties met Voys

Wil je dat je CRM laat zien wie er belt voordat je opneemt? Of dat een gemiste oproep automatisch in Slack verschijnt? Dat kan. Voys heeft vier bouwstenen waarmee jouw software en ons telefoonsysteem met elkaar kunnen praten: API's, gespreksnotificaties, de belplan-webhook en Klik-en-bel.

Deze pagina gaat verder dan de basis: je vindt hier ook basis-URL's, endpoints en voorbeeldverzoeken.

Goed om te weten voordat je begint:

1. Deze pagina legt uit wat er mogelijk is met onze API's, maar het is geen technische specificatie. Endpoints, velden en voorbeelden kunnen veranderen. De actuele documentatie vind je altijd op het OpenAPI-portaal, dus gebruik dat als referentie wanneer je gaat bouwen (of deel het met je ontwikkelaar).
2. Goed om te weten: wat je met deze API's bouwt, en hoe, is aan jou. Voys levert het platform en de documentatie, maar we kunnen geen support bieden op maatwerk-integraties die jij (of iemand die je inhuurt) bouwt. Meer daarover lees je verderop op deze pagina.

De vier bouwstenen

API: jouw software haalt iets op bij ons

Een API is een loket waar jouw software data kan ophalen of afgeven: gespreksgeschiedenis, contacten, wie beschikbaar is. Jouw systeem vraagt, wij antwoorden.

Voys heeft dertien API's, verdeeld over twee generaties met elk hun eigen adres:

• De nieuwere API's draaien op api.eu-production.holodeck.voys.nl (Contactbook, User status, Call transcription storage).
• De rest draait op api.voys.nl/api/v2 (Call, Call recording, Users, VoIP accounts, Caller ID numbers, Webphone user, en de partner-API's voor onboarding).

Authenticatie werkt overal hetzelfde: een header Authorization: Bearer <jouw-token> of Authorization: Token <jouw-token>. Dit is bijvoorbeeld hoe je je eigen gespreksgeschiedenis van de afgelopen vijf weken ophaalt:

GET https://api.voys.nl/api/v2/call/personalized/
Authorization: Bearer <your-token>

Dat geeft onder andere direction, answered, start_time, duration_in_seconds, en wie met wie belde. De volledige lijst met endpoints en velden vind je op het OpenAPI-portaal.

Gespreksnotificaties: wij sturen iets naar jou

Dit werkt andersom: zodra er iets gebeurt met een gesprek, sturen wij dat automatisch naar een URL van jouw keuze. Jouw software hoeft niet te vragen. Wij melden het zelf, als een POST-verzoek met een JSON-body.

Er zijn zes momenten per gesprek: created (alleen inkomend), ringing, in progress, warm transfer, cold transfer en ended (met een reden: completed, busy, no answer, failed, cancelled of abandoned). Heb je Voys Intelligence aan staan? Dan volgen er na het gesprek nog twee: call_transcription zodra de transcriptie klaar is, en summary zodra de AI-samenvatting klaar is.

Elke notificatie bevat minimaal een call_id, timestamp, status, direction en details over de beller en bestemming. Je kunt die call_id ook gebruiken om de opname of transcriptie van hetzelfde gesprek op te halen via de bijbehorende API's, dus notificaties en API's werken hier samen.

Dit stel je zelf in via Freedom: Integratie -> Gespreksnotificaties -> Toevoegen. Kies Custom voor je eigen URL, of Robin voor een directe integratie.

Belplan-webhook: wij vragen jou iets terwijl de telefoon nog overgaat

Dit lijkt veel op gespreksnotificaties, maar werkt andersom. En het gebeurt vroeg genoeg om nog iets met het gesprek te doen: terwijl iemand belt, sturen wij een GET-verzoek naar jouw server om te vragen waar het gesprek naartoe moet. Dit werkt alleen voor inkomende gesprekken, en op precies één punt in het belplan. Het is het enige moment waarop jouw systeem het gesprek daadwerkelijk kan beïnvloeden.

De twee zijn makkelijk te verwarren, dus hier het verschil: de webhook routeert het gesprek (GET, alleen inkomend, vraagt om een beslissing), terwijl notificaties alleen melden wat er gebeurde (POST, alle richtingen, geen invloed op het gesprek). Je kunt ze zonder problemen naast elkaar gebruiken voor hetzelfde gesprek.

Klik-en-bel: bellen met één klik

Hiermee laat je jouw software een gesprek starten vanaf iemands eigen toestel, app of Webphone. Denk aan een belknop naast elk telefoonnummer in je CRM.

• Adres: https://api.voipgrid.nl/api/clicktodial/. Goed om te weten: dit is een ander domein dan de rest.
• Authenticatie: Authorization: Token <e-mailadres>:<jouw-token>. Dit werkt net iets anders dan bij de andere API's: het e-mailadres van de gebruiker is onderdeel van het token, gescheiden door een dubbele punt.

POST https://api.voipgrid.nl/api/clicktodial/
Authorization: Token name@company.com:<your-token>
Content-Type: application/json

{ "b_number": "+31612345678" }

Dit geeft een callid terug. Wil je checken hoe het gesprek loopt? Vraag dan GET /api/clicktodial/{callid}/ op. Je krijgt een status terug: verbinden (dialing_a, dialing_b), verbonden (connected) of beëindigd/mislukt (disconnected, failing_a, failing_b). Nog makkelijker: laat gespreksnotificaties je vertellen wanneer het gesprek overgaat, wordt opgenomen of eindigt.

API's in één oogopslag

Tien van de dertien API's zijn voor je eigen software. De andere drie (partner client, phone number en onboarding dial plan) zijn voor partners die nieuwe klanten onboarden, dus die laten we hier weg.

Je vindt alle details, velden en parameters voor elke API op het OpenAPI-portaal.

Wat kun je hiermee bouwen?

Herken bellers automatisch. Op het moment dat iemand belt, zoekt jouw systeem het nummer op in het gedeelde adresboek (Contactbook API) en toont de naam en klantgegevens voordat het gesprek überhaupt is opgenomen. Wil je het gesprek ook routeren op basis van wie er belt? Combineer dit dan met de belplan-webhook.

Gemiste oproep, direct een seintje. Er komt een ended-notificatie met reason no-answer binnen op jouw URL. Je zoekt het nummer op via de Contactbook API en post de naam en het nummer naar je teamkanaal.

Bellen vanuit je CRM, met live status. Een collega klikt op een nummer en jouw integratie stuurt een POST naar Click-to-Dial. In plaats van pollen met GET /clicktodial/{callid}/, kun je de gespreksnotificaties (ringing, in-progress, ended) het CRM-record laten updaten.

Opname, transcript en samenvatting belanden automatisch in het klantdossier. Heb je Voys Intelligence aanstaan? Dan komt er na het gesprek een call recording created-notificatie binnen met een kant-en-klare recording_url, gevolgd door call_transcription en summary zodra die klaar zijn. Je haalt de definitieve versies vervolgens op via de Call Transcription Storage API en voegt ze toe aan het dossier.

Zelf bouwen of iets kant-en-klaars gebruiken?

Werk je samen met een developer? Die kan meteen aan de slag op het OpenAPI-portaal, waar je de actuele technische documentatie vindt voor alle dertien API's. Iedereen vindt zijn eigen API-token in Freedom onder persoonlijke instellingen (API-token). Dat token is de sleutel waarmee je software zich bij ons identificeert, dus behandel het als een wachtwoord: houd het voor jezelf en zorg dat het nooit terechtkomt in code die anderen kunnen zien.

Geen developer bij de hand? Geen probleem, je hoeft niet vanaf nul te beginnen. Voor populaire tools bestaan er al kant-en-klare integraties, zoals Zapier, Slack, HubSpot, Bubble, ROBIN en Microsoft Teams. Kijk voordat je iemand vraagt iets te bouwen even op deze Integraties hulppagina. Misschien bestaat er al een oplossing voor jouw systeem.

Verantwoordelijkheid en support

Voys levert de API's, de gespreksnotificaties, de webhook en de documentatie daarvoor. Jij bepaalt wat je ermee bouwt, met wie je het bouwt en hoe. Dat betekent ook dat het aan jou is om het draaiende te houden.

In de praktijk betekent dit:

• We helpen je graag met: of de API bereikbaar is, of je token werkt, of Voys Intelligence aanstaat, of dat een endpoint of statuscode niet klopt met de documentatie.
• We kunnen niet helpen met: bugs in je eigen code, een Zapier-flow die je zelf hebt opgezet en niet meer werkt, of een integratie die een derde partij voor je heeft gebouwd en niet meer onderhoudt. Daarvoor kun je het beste terecht bij je developer of de maker van de integratie.

Loop je vast en weet je niet zeker aan welke kant het probleem zit? Laat het gerust weten. We denken graag met je mee, maar het bouwen en onderhouden van je eigen integratie blijft bij jou (of je developer).

FAQ

Moet ik kunnen programmeren? Nee. Deze pagina helpt je begrijpen wat mogelijk is en grofweg hoe het werkt. Het daadwerkelijke bouwen doet een developer, of je gebruikt een kant-en-klare integratie.

Is mijn API-token veilig? Ja, zolang je 'm geheimhoudt. Iedereen met die token kan namens jou gegevens ophalen of instellingen wijzigen. Denk je dat je token gelekt is? Dan kun je in Freedom een nieuwe aanvragen.

Waarom krijg ik geen samenvattingen van mijn gesprekken? In bijna alle gevallen komt dit doordat Voys Intelligence nog niet aanstaat. Het loont om dat eerst te checken, voordat je verder zoekt.

Kan ik een opname of transcript automatisch laten verwijderen? Dat kan niet, maar dat hoeft ook niet: ze verlopen vanzelf na de bewaartermijn.

Wat als mijn integratie stopt met werken? Check eerst of het probleem aan onze kant zit: de API-status, of je token nog geldig is, of instellingen zoals Voys Intelligence. Zit het in je eigen code of in een integratie van een derde partij? Dan is het aan jou of je developer om het op te lossen. Meer daarover lees je bij 'Verantwoordelijkheid en support' hierboven.

Zijn er rate limits en wat gebeurt er bij een 429? Sommige endpoints (zoals Call Recording) geven een 429 throttled terug als je ze te vaak aanroept. We hebben de exacte limieten niet gepubliceerd, en ook niet of er een Retry-After-header wordt meegestuurd. Om veilig te zijn: bouw een retry in met backoff.

Kan ik checken of een opname, transcript of samenvatting al klaar is? Op dit moment niet: er is geen statusveld en geen "since X"-filter. Het goede nieuws is dat de gespreksnotificatie je automatisch laat weten zodra iets klaar is, dus je hoeft niet te pollen.