ūüí° Ik heb feedback op jullie hulppagina‚Äôs.

Updates

Wij werken constant aan ons platform en andere producten. Wil je op de hoogte blijven van alle updates, check voys.nl/updates.

Verbeteringen

Wij ontwikkelen voor en met jou als klant. Hierbij wordt alle feedback gewaardeerd. Heb je zelf een suggestie hoe wij onze producten kunnen verbeteren, check dan voys.nl/verbeteringen.

Contact

Kom je er met onze hulppagina's toch niet helemaal uit, plan dan een afspraak met ons in door rechtsonder op de afspraakplanner te drukken!

Technische specificaties

Technische specificaties

Op verschillende belangrijke gebeurtenissen in een gesprek worden notificaties verstuurd naar de opgegeven URL. De notificaties worden verstuurd als een POST-verzoek met de gegevens als JSON-document.

Soorten notificaties en data

icon

Created

een created wordt gestuurd bij het starten van een inkomend gesprek.

{
  "call_id": "ua9-grq-prd-1693575683.22973164",
  "timestamp": "2023-09-01T13:41:25.972110+00:00",
  "status": "created",
  "version": "v2",
  "direction": "inbound",
  "caller": {
    "number": "+31507009920",
    "name": "Johan | Voys",
    "account_number": null,
    "user_numbers": [],
    "user_emails": []
  },
  "destination": {
    "number": "+31332022074"
  }
}
  • call_id:¬†Een unieke tekenreeks om het gesprek te identificeren.
  • timestamp:¬†Een datum en tijd van het moment dat de webhook wordt gegenereerd in ISO 8601 formaat.
  • status:¬†De status van een gesprek. Voor dit notificatietype is het¬†created.
  • version:¬†Een versie-attribuut dat in de toekomst gebruikt kan worden om naar een andere versie van de webhooks te migreren. Op dit moment is het altijd¬†v2.
  • direction:¬†Of een gesprek inkomend (inbound) of uitgaand (outbound) is. Het created event wordt alleen gestuurd bij inkomende gesprekken.
  • caller:¬†De gegevens over de beller.
    • number:¬†Het telefoonnummer waarmee de beller naar buiten belt
    • name: Naam van de beller
    • account_number: Deze informatie wordt niet meegestuurd bij het¬†created¬†event.
    • user_numbers: Deze informatie wordt niet meegestuurd bij het¬†created¬†event
    • user_emails: Deze informatie wordt niet meegestuurd bij het¬†created¬†event
  • destination:¬†De gegevens over waar het gesprek naar toe gaat.
    • number:¬†Het telefoonnummer dat de beller heeft ingevoerd.
icon

Ringing

Een ringing notificatie wordt verstuurd op het moment dat telefoons beginnen te rinkelen vanwege een inkomend gesprek.

Het is mogelijk dat er meerdere ringing notificaties na elkaar worden verstuurd op het moment dat nieuwe toestellen beginnen te rinkelen.

{
  "call_id": "ua9-grq-prd-1693575683.22973164",
  "timestamp": "2023-09-01T13:41:26.020742+00:00",
  "status": "ringing",
  "version": "v2",
  "direction": "inbound",
  "caller": {
    "number": "+31507009920",
    "name": "Johan | Voys",
    "account_number": null,
    "user_numbers": [],
    "user_emails": []
  },
  "destination": {
    "number": "+31332022074",
    "targets": [
      {
        "number": "+31332022074",
        "name": null,
        "account_number": "201",
        "user_numbers": [
          "610"
        ],
        "user_emails": [
          "email@email.nl"
        ]
      }
    ]
  }
}
  • call_id:¬†Een unieke tekenreeks om het gesprek te identificeren.
  • timestamp:¬†Een datum en tijd van het moment dat de webhook wordt gegenereerd in ISO 8601 formaat.
  • status:¬†De status van een gesprek. Voor dit notificatietype is het¬†ringing.
  • version:¬†Een versie-attribuut dat in de toekomst gebruikt kan worden om naar een andere versie van de webhooks te migreren. Op dit moment is het altijd¬†v2.
  • direction:¬†Of een gesprek inkomend (inbound) of uitgaand (outbound) is. Gesprekken tussen collega's worden als¬†outbound¬†vermeld.
  • caller:¬†De gegevens over de beller.
    • number:¬†Het telefoonnummer waarmee de beller naar buiten belt
    • name: Naam van de beller
    • account_number: Deze informatie wordt niet meegestuurd bij het¬†ringing.event.
    • user_numbers: Deze informatie wordt niet meegestuurd bij het¬†ringing.¬†event
    • user_emails: Deze informatie wordt niet meegestuurd bij het¬†ringing.¬†event
  • destination:¬†De gegevens over waar het gesprek naar toe gaat.
    • number:¬†Het telefoonnummer dat de beller heeft ingevoerd.
    • targets:¬†De telefoons die rinkelen voor dit gesprek. Telefoons die niet bereikbaar zijn worden niet getoond.
      • number: Het nummer waarop de telefoon wordt gebeld. Meestal is dit gelijk aan¬†destination.number, maar het nummer veranderd bijvoorbeeld op het moment dat een gesprek wordt doorgestuurd.
      • name: De naam van de persoon die wordt gebeld. Voor inkomende gesprekken is dit vrijwel altijd¬†null
      • account_number: De interne nummers van de gebruikers die hebben ingesteld dat ze op deze VoIP-account bereikbaar zijn (waar beschikbaar, kan een lege array zijn).
      • user_number: De interne nummers van de gebruikers die bereikbaar zijn (waar beschikbaar, kan een lege array zijn).
      • user_emails: e-mail adressen van de gebruikers.
icon

in-progress

Een in-progress notificatie wordt verstuurd op het moment dat een gesprek wordt beantwoord.

Let op! De target die het gesprek beantwoordt, is niet altijd een van de toestellen die aanvankelijk heeft gerinkeld. Vanwege call pickup kan het voorkomen dat het gesprek op een ander toestel wordt opgenomen.

{
  "call_id": "ua9-grq-prd-1693575683.22973164",
  "timestamp": "2023-09-01T13:41:26.992074+00:00",
  "status": "in-progress",
  "version": "v2",
  "direction": "inbound",
  "caller": {
    "number": "+31507009920",
    "name": "Johan | Voys",
    "account_number": null,
    "user_numbers": [],
    "user_emails": []
  },
  "destination": {
    "number": "+31332022074",
    "target": {
      "number": "+31332022074",
      "name": null,
      "account_number": "201",
      "user_numbers": [
        "610"
      ],
      "user_emails": [
        "email@email.nl"
      ]
    }
  }
}
  • call_id:¬†Een unieke tekenreeks om het gesprek te identificeren.
  • timestamp:¬†Een datum en tijd van het moment dat de webhook wordt gegenereerd in ISO 8601 formaat.
  • status:¬†De status van een gesprek. Voor dit notificatietype is het¬†in-progress.
  • version:¬†Een versie-attribuut dat in de toekomst gebruikt kan worden om naar een andere versie van de webhooks te migreren. Op dit moment is het altijd¬†v2.
  • direction:¬†Of een gesprek inkomend (inbound) of uitgaand (outbound) is. Gesprekken tussen collega's worden als¬†outbound¬†vermeld.
  • caller:¬†De gegevens over de beller.
    • number:¬†Het telefoonnummer waarmee de beller naar buiten belt
    • name: Naam van de beller
    • account_number: Het interne nummer van de VoIP-account (waar beschikbaar, voor inkomende gesprekken is dit eigenlijk altijd¬†null).
    • user_numbers:
    • user_emails:
  • destination:¬†De gegevens over waar het gesprek naar toe gaat.
    • number:¬†Het telefoonnummer dat de beller heeft ingevoerd.
    • targets:¬†De telefoons die rinkelen voor dit gesprek. Telefoons die niet bereikbaar zijn worden niet getoond.
      • number: Het nummer waarop de telefoon wordt gebeld. Meestal is dit gelijk aan¬†destination.number, maar het nummer veranderd bijvoorbeeld op het moment dat een gesprek wordt doorgestuurd.
      • name: De naam van de persoon die wordt gebeld. Voor inkomende gesprekken is dit vrijwel altijd¬†null
      • account_number: De interne nummers van de gebruikers die hebben ingesteld dat ze op deze VoIP-account bereikbaar zijn (waar beschikbaar, kan een lege array zijn).
      • user_number: De interne nummers van de gebruikers die bereikbaar zijn (waar beschikbaar, kan een lege array zijn).
      • user_emails: e-mail adressen van de gebruikers.
icon

ended

Een¬†ended¬†notificatie wordt verstuurd op het moment dat een gesprek wordt be√ęindigd. Er zijn een paar verschillende redenen waarom een gesprek kan eindigen.

Een ended notificatie kan worden verstuurd na een in-progress notificatie als het gesprek is opgehangen door een van de deelnemers, na een ringing notificatie als niemand op heeft genomen of als enige notificatie als geen enkel toestel bereikbaar is.

{
  "call_id": "ua9-grq-prd-1693575683.22973164",
  "timestamp": "2023-09-01T13:41:27.653775+00:00",
  "status": "ended",
  "reason": "completed",
  "version": "v2",
  "direction": "inbound",
  "caller": {
    "number": "+31507009920",
    "name": "Johan | Voys",
    "account_number": null,
    "user_numbers": [],
    "user_emails": []
  },
  "destination": {
    "number": "+31332022074"
  }
}
  • call_id:¬†Een unieke tekenreeks om het gesprek te identificeren.
  • timestamp:¬†Een datum en tijd van het moment dat de webhook wordt gegenereerd in ISO 8601 formaat.
  • status:¬†De status van een gesprek. Voor dit notificatietype is het¬†ended.
  • reason:¬†De reden waarom een gesprek is be√ęindigd. De reden kan een van de volgende waarden hebben:
    1. completed: Het gesprek is succesvol afgerond.
    2. busy: Het gesprek is geweigerd, de gebelde is bezet.
    3. no-answer: Niemand heeft het gesprek opgenomen, kan verschillende redenen hebben.
    4. failed: Er is een fout opgetreden waardoor het gesprek niet tot stand is gekomen.
    5. cancelled: De beller heeft het gesprek opgehangen voordat iemand op kon nemen.
    6. abandon: Wanneer een beller de verbinding verbreekt terwijl hij in de wachtrij staat.
  • version:¬†Een versie-attribuut dat in de toekomst gebruikt kan worden om naar een andere versie van de webhooks te migreren. Op dit moment is het altijd¬†v2.
  • direction:¬†Of een gesprek inkomend (inbound) of uitgaand (outbound) is. Gesprekken tussen collega's worden als¬†outbound¬†vermeld.
  • caller:¬†De gegevens over de beller.
    • number:¬†Het telefoonnummer waarmee de beller naar buiten belt
    • name: Naam van de beller
    • account_number: Het interne nummer van de VoIP-account (waar beschikbaar, voor inkomende gesprekken is dit eigenlijk altijd¬†null).
    • user_numbers:
    • user_emails:
  • destination:¬†De gegevens over waar het gesprek naar toe gaat.
    • number:¬†Het telefoonnummer dat de beller heeft ingevoerd.
icon

warm-transfer

Een warm-transfer notificatie wordt verstuurd op het moment dat een gesprek "warm" wordt doorgeschakeld. Bij een warme doorschakeling belt de doorstuurder eerst de nieuwe deelnemer, de nieuwe deelnemer neemt op, spreekt met de doorstuurder waarna het gesprek wordt doorgeschakeld.

Het gesprek van de doorstuurder naar de derde partij genereert ook een ringing en een in-progress notificatie met een eigen call_id. Bij een transfer worden deze twee gesprekken als het ware samengevoegd tot een enkel gesprek. De call_id van een van de twee gesprekken wordt vervolgens gebruikt voor het gesprek na de doorschakeling. Het andere call_id wordt in de doorschakelijk meegegeven als de merged_id en vervalt daarna.

{
  "call_id": "ua7-ams-prd-1693576700.23986757",
  "merged_id": "ua7-ams-prd-1693576711.23987220",
  "timestamp": "2023-09-01T13:58:44.399054+00:00",
  "status": "warm-transfer",
  "version": "v2",
  "direction": "inbound",
  "caller": {
    "number": "+31507009920",
    "name": "Johan N",
    "account_number": null,
    "user_numbers": [],
    "user_emails": []
  },
  "destination": {
    "number": "629",
    "target": {
      "number": "629",
      "name": null,
      "account_number": "203",
      "user_numbers": [
        "629"
      ],
      "user_emails": [
        "e-mail2@e-mail.com"
      ]
    }
  },
  "redirector": {
    "number": "610",
    "name": "Johan N",
    "account_number": "201",
    "user_numbers": [
      "610"
    ],
    "user_emails": [
      "e-mail@e-mail.com"
    ]
  }
}
  • call_id:¬†Een unieke tekenreeks om het gesprek te identificeren, overgenomen van een van de voorgaande gesprekken.
  • merged_id¬†Het call_id van het andere voorgaande gesprek, die niet meer gebruikt zal worden.
  • timestamp:¬†Een datum en tijd van het moment dat de webhook wordt gegenereerd in ISO 8601 formaat.
  • status:¬†De status van een gesprek. Voor dit notificatietype is het¬†transfer.
  • version:¬†Een versie-attribuut dat in de toekomst gebruikt kan worden om naar een andere versie van de webhooks te migreren. Op dit moment is het altijd¬†v2.
  • direction:¬†Of een gesprek inkomend (inbound) of uitgaand (outbound) is. Gesprekken tussen collega's worden als¬†outbound¬†vermeld.
  • caller:¬†De gegevens over de beller.
    • number:¬†Het telefoonnummer waarmee de beller naar buiten belt
    • name: Naam van de beller
    • account_number: Het interne nummer van de VoIP-account (waar beschikbaar, voor inkomende gesprekken is dit eigenlijk altijd¬†null).
    • user_numbers:
    • user_emails:
  • destination:¬†De gegevens over waar het gesprek naar toe gaat.
    • number:¬†Het telefoonnummer dat de beller heeft ingevoerd.
    • targets:¬†De telefoons die rinkelen voor dit gesprek. Telefoons die niet bereikbaar zijn worden niet getoond.
      • number: Het nummer waarop de telefoon wordt gebeld. Meestal is dit gelijk aan¬†destination.number, maar het nummer veranderd bijvoorbeeld op het moment dat een gesprek wordt doorgestuurd.
      • name: De naam van de persoon die wordt gebeld. Voor inkomende gesprekken is dit vrijwel altijd¬†null
      • account_number: De interne nummers van de gebruikers die hebben ingesteld dat ze op deze VoIP-account bereikbaar zijn (waar beschikbaar, kan een lege array zijn).
      • user_number: De interne nummers van de gebruikers die bereikbaar zijn (waar beschikbaar, kan een lege array zijn).
      • user_emails: e-mail adressen van de gebruikers.
  • redirector:¬†De gegevens van de gespreksdeelnemer die de doorschakeling uitvoert.
    • number:¬†Het telefoonnummer waarmee de beller naar buiten belt
    • name: Naam van de beller
    • account_number: Het interne nummer van de VoIP-account (waar beschikbaar, voor inkomende gesprekken is dit eigenlijk altijd¬†null).
    • user_number: De interne nummers van de gebruikers die bereikbaar zijn (waar beschikbaar, kan een lege array zijn).
    • user_emails: e-mail adressen van de gebruikers.
icon

cold-transfer

Een cold-transfer notificatie wordt verstuurd op het moment dat een gesprek "koud" wordt doorgeschakeld. Bij een koude doorschakeling belt de doorstuurder de nieuwe deelnemer, maar stuurt het gesprek door zonder te wachten of en door wie er op wordt genomen.

Er zijn twee belangrijke verschillen tussen een cold-transfer en een warm-transfer:

  • Bij een warme doorschakeling is er altijd √©√©n gebelde, waar dit bij een koude doorschakeling meerdere kunnen zijn (bijvoorbeeld als het gesprek wordt doorgeschakeld naar een belgroep).
  • Voor een warme doorschakeling wordt eerst een¬†ringing¬†en¬†in-progress¬†notificaties gegenereerd. Bij een koude doorschakeling wordt alleen een¬†ringing¬†notificatie gegeven, en volgt de¬†in-progress¬†notificatie alleen als de derde partij het gesprek aanneemt.

Het gesprek van de doorstuurder naar de derde partij genereert ook een ringing notificatie met een eigen call_id. Bij een transfer worden deze twee gesprekken als het ware samengevoegd tot een enkel gesprek. De call_id van een van de twee gesprekken wordt vervolgens gebruikt voor het gesprek na de doorschakeling. Het andere call_id wordt in de doorschakelijk meegegeven als de merged_id en vervalt daarna.

{
  "call_id": "ua4-grq-prd-1693576927.25584586",
  "merged_id": "ua4-grq-prd-1693576937.25585499",
  "timestamp": "2023-09-01T14:02:17.054643+00:00",
  "status": "cold-transfer",
  "version": "v2",
  "direction": "inbound",
  "caller": {
    "number": "+31507009920",
    "name": "Johan N",
    "account_number": null,
    "user_numbers": [],
    "user_emails": []
  },
  "destination": {
    "number": "629",
    "targets": [
      {
        "number": "629",
        "name": null,
        "account_number": "203",
        "user_numbers": [
          "629"
        ],
        "user_emails": [
          "e-mail2@e-mail.com"
        ]
      }
    ]
  },
  "redirector": {
    "number": "+31332022074",
    "name": null,
    "account_number": "201",
    "user_numbers": [
      "610"
    ],
    "user_emails": [
      "e-mail@e-mail.com"
    ]
  }
}
  • call_id:¬†Een unieke tekenreeks om het gesprek te identificeren, overgenomen van een van de voorgaande gesprekken.
  • merged_id¬†Het call_id van het andere voorgaande gesprek, die niet meer gebruikt zal worden.
  • timestamp:¬†Een datum en tijd van het moment dat de webhook wordt gegenereerd in ISO 8601 formaat.
  • status:¬†De status van een gesprek. Voor dit notificatietype is het¬†transfer.
  • version:¬†Een versie-attribuut dat in de toekomst gebruikt kan worden om naar een andere versie van de webhooks te migreren. Op dit moment is het altijd¬†v2.
  • direction:¬†Of een gesprek inkomend of uitgaand is. Op dit moment worden alleen inkomende gesprekken ondersteund, en is deze waarde atijd¬†inbound.
  • caller:¬†De gegevens over de beller.
    • number:¬†Het telefoonnummer waarmee de beller naar buiten belt
    • name: Naam van de beller
    • account_number: Het interne nummer van de VoIP-account (waar beschikbaar, voor inkomende gesprekken is dit eigenlijk altijd¬†null).
    • user_numbers:
    • user_emails:
  • destination:¬†De gegevens over waar het gesprek naar toe gaat.
    • number:¬†Het telefoonnummer dat de beller heeft ingevoerd.
    • targets:¬†De telefoons die rinkelen voor dit gesprek. Telefoons die niet bereikbaar zijn worden niet getoond.
      • number: Het nummer waarop de telefoon wordt gebeld. Meestal is dit gelijk aan¬†destination.number, maar het nummer veranderd bijvoorbeeld op het moment dat een gesprek wordt doorgestuurd.
      • name: De naam van de persoon die wordt gebeld. Voor inkomende gesprekken is dit vrijwel altijd¬†null
      • account_number: De interne nummers van de gebruikers die hebben ingesteld dat ze op deze VoIP-account bereikbaar zijn (waar beschikbaar, kan een lege array zijn).
      • user_number: De interne nummers van de gebruikers die bereikbaar zijn (waar beschikbaar, kan een lege array zijn).
      • user_emails: e-mail adressen van de gebruikers.
  • redirector:¬†De gegevens van de gespreksdeelnemer die de doorschakeling uitvoert.
    • number:¬†Het telefoonnummer waarmee de beller naar buiten belt
    • name: Naam van de beller
    • account_number: Het interne nummer van de VoIP-account (waar beschikbaar, voor inkomende gesprekken is dit eigenlijk altijd¬†null).
    • user_number: De interne nummers van de gebruikers die bereikbaar zijn (waar beschikbaar, kan een lege array zijn).
    • user_emails: e-mail adressen van de gebruikers.

Volgorde van notificaties

Voor elk gesprek worden er meerdere notificaties verstuurd. Welke notificaties er worden verstuurd hangt af van hoe het gesprek wordt uitgevoerd. Hieronder wordt de volgorde van notificaties voor de meest veelvoorkomende gesprekstypen behandeld.

Eenvoudig gesprek

Een succesvol gesprek met twee deelnemers:

  • ringing - A belt B
  • in-progress - A belt B
  • ended - A belt B (reden:¬†completed)

De telefoon wordt niet opgenomen

De telefoon van de gebelde rinkelt, maar wordt niet opgenomen.

  • ringing - A belt B
  • ended - A belt B (reden:¬†busy¬†of¬†no-answer¬†afhankelijk van toestel)

De gebelde is niet beschikbaar

De gebelde is niet beschikbaar (bijvoorbeeld doordat de telefoon op Do Not Disturb staat), dus de telefoon van de gebelde rinkelt niet en wordt ook niet opgenomen.

  • ended - A belt B (reden:¬†busy)

Attended transfer

Bij een attended transfer (warme doorschakeling) belt A eerst met B, waarna een van de deelnemers het gesprek doorverbind naar deelnemer C. De deelnemer belt daarvoor eerst met C, en pas nadat ze hebben gesproken wordt het gesprek doorverbonden. Vervolgens zitten alleen de andere deelnemer A en C nog in het gesprek.

  • ringing - A belt B
  • in-progress - A belt B
  • ringing - B belt C
  • in-progress - B belt C
  • warm-transfer - B verbindt A en C
  • ended - A en C hangen op (reden:¬†completed)

Blind transfer

Bij een blind transfer (koude doorschakeling) belt A eerst met B, waarna een van de deelnemers het gesprek doorverbind naar deelnemer C. De deelnemer schakelt daarvoor direct door naar C, zonder te wachten of C beschikbaar is.

  • ringing - A belt B
  • in-progress - A belt B
  • ringing - B belt C
  • cold-transfer - B verbindt A en C
  • in-progress - A belt C
  • ended - A belt niet meer met C (reden:¬†completed)

Semi-attended transfer

Bij een semi-attended transfer (lauwe doorschakeling of blonde transfer) belt A eerst met B, waarna een van de deelnemers het gesprek doorverbind naar deelnemer C. De deelnemer probeert eerst C te bellen, maar schakelt het gesprek al door voordat C opneemt.

  • ringing - A belt B
  • in-progress - A belt B
  • ringing - B belt C
  • cold-transfer - B verbindt A en C
  • in-progress - A belt C
  • ended - A belt niet meer met C (reden:¬†completed)

Call pickup

Als twee telefoons in dezelfde pickupgroep zitten, dan is het mogelijk om vanaf de ene telefoon een gesprek over te nemen dat voor de andere telefoon is bedoeld.

  • ringing - A belt B
  • in-progress - A belt met C
  • ended - A belt niet meer met C (reden:¬†completed)

Call forwarding

Als een gebruiker zijn/haar telefoon instelt dat deze binnenkomende gesprekken automatisch doorzet naar een ander nummer.

  • ringing - A belt B
  • ringing - A belt B & C
  • in-progress of ended, afhankelijk van of er iemand opneemt.

Voorbeeld integraties

Hier onder staan een aantal voorbeelden van integraties in combinatie met Zapier: