Gespreksnotificaties

Uit Help
(Doorverwezen vanaf CallNotification)
Ga naar:navigatie, zoeken

Let op

Gespreksnotificaties is op dit moment een beta functie. Het kan voorkomen dat er bepaalde functies niet correct werken. Ook is het mogelijk dat bepaalde functies wijzigen. Zorg er daarom voor dat je altijd deze pagina controleert op nieuwe informatie.

Wat kan ik hier?

De sectie Gespreksnotificaties maakt het mogelijk om automatisch statusnotificaties te versturen voor alle inkomende gesprekken voor alle VoIP-accounts. Op het moment dat, bijvoorbeeld, een telefoon overgaat, de telefoon wordt opgenomen of weer wordt opgehangen, dan wordt er een http-verzoek gedaan naar de ingevoerde URL met gegevens over het gesprek. Dankzij deze notificaties is het mogelijk om bijvoorbeeld gespreksgegevens te registreren in een CRM-systeem of om bij te houden wie op een bepaald moment in gesprek is.

Velden

Beschrijving: een eigen beschrijving die vertelt waar de notificatie voor is.

URL: de URL waar de gespreksnotificaties naar moeten worden verstuurd.

Technische documentatie statusnotificaties

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

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": "24c562241e9f-1502721212.159",
  "timestamp": "2017-07-20T13:17:39+00:00",
  "status": "ringing",
  "version": "v2",
  "direction": "inbound",
  "caller": {
    "account_number": null, 
    "user_numbers": [],
    "number": "+31508009044",
    "name": "John Doe"
  },
  "destination": {
    "number": "+315080090000",
    "targets": [
      {
        "account_number": 234, 
        "user_numbers": ["678"],
        "number": "+315080090000",
        "name": "Jane Doe"
      },
      {
        "account_number": 456,
        "user_numbers": ["789"],
        "number": "+315080090000",
        "name": "Jan Jansen"
      }
    ]
  }
}

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.

caller.account_number: Het interne nummer van de VoIP-account (waar beschikbaar, voor inkomende gesprekken is dit eigenlijk altijd null).

caller.number: Het telefoonnummer waarmee de beller naar buiten belt.

caller.user_numbers: De interne nummers van de gebruikers die hebben ingesteld dat ze op deze VoIP-account bereikbaar zijn (waar beschikbaar, voor inkomende gesprekken is dit eigenlijk altijd een lege array).

caller.name: De naam van de beller.

destination: De gegevens over waar het gesprek naar toe gaat.

destination.number: Het telefoonnummer dat de beller heeft ingevoerd.

destination.targets: De telefoons die rinkelen voor dit gesprek. Telefoons die niet bereikbaar zijn worden niet getoond.

destination.targets.account_number: Het interne nummer van de VoIP-account, waar beschikbaar.

destination.targets.user_numbers: De interne nummers van de gebruikers die hebben ingesteld dat ze op deze VoIP-account bereikbaar zijn (waar beschikbaar, kan een lege array zijn).

destination.targets.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.

destination.targets.name: De naam van de persoon die wordt gebeld. Voor inkomende gesprekken is dit vrijwel altijd null.


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": "24c562241e9f-1502721212.159",
  "timestamp": "2017-07-20T13:17:39+00:00",
  "status": "in-progress",
  "version": "v2",
  "direction": "inbound",
  "caller": {
    "account_number": null, 
    "user_numbers": [],
    "number": "+31508009044",
    "name": "John Doe"
  },
  "destination": {
    "number": "+315080090000",
    "target": {
      "account_number": 234, 
      "user_numbers": ["678"],
      "number": "+315080090000",
      "name": "Jane Doe"
    }
  }
}

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.

caller.account_number: Het interne nummer van de VoIP-account (waar beschikbaar, voor inkomende gesprekken is dit eigenlijk altijd null).

caller.number: Het telefoonnummer waarmee de beller naar buiten belt.

caller.user_numbers: De interne nummers van de gebruikers die hebben ingesteld dat ze op deze VoIP-account bereikbaar zijn (waar beschikbaar, voor inkomende gesprekken is dit eigenlijk altijd een lege array).

caller.name: De naam van de beller.

destination: De gegevens over waar het gesprek naar toe gaat.

destination.number: Het telefoonnummer dat de beller heeft ingevoerd.

destination.target: De gegevens van de telefoon waarmee het gesprek is opgenomen.

destination.target.account_number: Het interne nummer van de VoIP-account, wanneer beschikbaar.

destination.target.number: Het nummer waarop de telefoon wordt gebeld. Meestal is dit gelijk aan destination.number, maar het nummer verandert bijvoorbeeld op het moment dat een gesprek wordt doorgestuurd.

destination.target.user_numbers: De interne nummers van de gebruikers die hebben ingesteld dat ze op deze VoIP-account bereikbaar zijn (waar beschikbaar, kan een lege array zijn).

destination.target.name: De naam van de persoon die wordt gebeld. Voor inkomende gesprekken is dit vrijwel altijd null.

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": "24c562241e9f-1502721212.159",
  "timestamp": "2017-07-20T13:17:39+00:00",
  "status": "ended",
  "reason": "completed",
  "version": "v2",
  "direction": "inbound",
  "caller": {
    "account_number": null, 
    "user_numbers": [],
    "number": "+31508009044",
    "name": "John Doe"
  },
  "destination": {
    "number": "+315080090000"
  }
}

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:

  • completed: Het gesprek is succesvol afgerond.
  • busy: Het gesprek is geweigerd, de gebelde is bezet.
  • no-answer: Niemand heeft het gesprek opgenomen, kan verschillende redenen hebben.
  • failed: Er is een fout opgetreden waardoor het gesprek niet tot stand is gekomen.
  • cancelled: De beller heeft het gesprek opgehangen voordat iemand op kon nemen.

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.

caller.account_number: Het interne nummer van de VoIP-account (waar beschikbaar, voor inkomende gesprekken is dit eigenlijk altijd null).

caller.number: Het telefoonnummer waarmee de beller naar buiten belt.

caller.user_numbers: De interne nummers van de gebruikers die hebben ingesteld dat ze op deze VoIP-account bereikbaar zijn (waar beschikbaar, voor inkomende gesprekken is dit eigenlijk altijd een lege array).

caller.name: De naam van de beller.

destination: De gegevens over waar het gesprek naar toe gaat.

destination.number: Het telefoonnummer dat de beller heeft ingevoerd.

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": "24c562241e9f-1502721212.159",
  "merged_id": "24c562241e9f-1502719948.132",
  "timestamp": "2017-07-20T13:17:39+00:00",
  "status": "warm-transfer",
  "version": "v2",
  "direction": "inbound",
  "caller": {
    "account_number": null, 
    "user_numbers": [],
    "number": "+31508009044",
    "name": "John Doe"
  },
  "destination": {
    "number": "+315080090000",
    "target": {
      "account_number": 246, 
      "number": "246",
      "user_numbers": ["680"],
      "name": null
    }
  },
  "redirector": {
    "account_number": 234, 
    "number": "+315080090000",
    "user_numbers": ["678"],
    "name": "Jane Doe"
  }
}

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 de persoon van het oude gesprek die wordt doorverbonden.

caller.account_number: Het interne nummer van de VoIP-account (waar beschikbaar, voor inkomende gesprekken is dit eigenlijk altijd null).

caller.number: Het telefoonnummer waarmee de doorgestuurde naar buiten belt.

caller.user_numbers: De interne nummers van de gebruikers die hebben ingesteld dat ze op deze VoIP-account bereikbaar zijn (waar beschikbaar).

caller.name: De naam van de doorgestuurde gespreksdeelnemer.

destination: De gegevens over de persoon naar wie het gesprek wordt doorverbonden.

destination.number: Het telefoonnummer dat de doorstuurder heeft ingevoerd.

destination.target: De gegevens van de telefoon waarmee het gesprek is opgenomen.

destination.target.account_number: Het interne nummer van de VoIP-account, waar beschikbaar.

destination.target.number: Het nummer waarop de telefoon wordt gebeld. Meestal is dit gelijk aan destination.number, maar het nummer verandert bijvoorbeeld op het moment dat een gesprek wordt doorgestuurd.

destination.target.user_numbers: De interne nummers van de gebruikers die hebben ingesteld dat ze op deze VoIP-account bereikbaar zijn (waar beschikbaar, kan een lege array zijn).

destination.target.name: De naam van de persoon die wordt gebeld. Dit is meestal null.

redirector: De gegevens van de gespreksdeelnemer die de doorschakeling uitvoert.

redirector.account_number: Het interne nummer van de VoIP-account, waar beschikbaar.

redirector.number: Het nummer waarop de doorstuurder werd gebeld (als het een gebelde was) of het nummer waarmee de de doorstuurder belde (als het een beller was).

redirector.user_numbers: De interne nummers van de gebruikers die hebben ingesteld dat ze op deze VoIP-account bereikbaar zijn (waar beschikbaar, kan een lege array zijn).

redirector.name: De naam van de persoon die wordt gebeld. Dit kan null zijn.

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": "24c562241e9f-1502721212.159",
  "merged_id": "24c562241e9f-1502719948.132",
  "timestamp": "2017-07-20T13:17:39+00:00",
  "status": "cold-transfer",
  "version": "v2",
  "direction": "inbound",
  "caller": {
    "account_number": null, 
    "user_numbers": [],
    "number": "+31508009044",
    "name": "John Doe"
  },
  "destination": {
    "number": "499",
    "targets": [
      {
        "account_number": 246, 
        "number": "499",
        "user_numbers": ["680"],
        "name": null
      },
      {
        "account_number": 289, 
        "number": "499",
        "user_numbers": ["686"],
        "name": null
      }
    ]
  },
  "redirector": {
    "account_number": 234, 
    "number": "+315080090000",
    "user_numbers": ["678"],
    "name": "Jane Doe"
  }
}

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 de persoon van het oude gesprek die wordt doorverbonden.

caller.account_number: Het interne nummer van de VoIP-account (waar beschikbaar, voor inkomende gesprekken is dit eigenlijk altijd null).

caller.number: Het telefoonnummer waarmee de doorgestuurde naar buiten belt.

caller.user_numbers: De interne nummers van de gebruikers die hebben ingesteld dat ze op deze VoIP-account bereikbaar zijn (waar beschikbaar).

caller.name: De naam van de doorgestuurde gespreksdeelnemer.

destination: De gegevens over de persoon naar wie het gesprek wordt doorverbonden.

destination.number: Het telefoonnummer dat de doorstuurder heeft ingevoerd.

destination.targets: De gegevens van de telefoon die rinkelen voor deze doorschakeling.

destination.targets.account_number: Het interne nummer van de VoIP-account, waar beschikbaar.

destination.targets.number: Het nummer waarop de telefoon wordt gebeld. Meestal is dit gelijk aan destination.number, maar het nummer verandert bijvoorbeeld op het moment dat een gesprek wordt doorgestuurd.

destination.targets.user_numbers: De interne nummers van de gebruikers die hebben ingesteld dat ze op deze VoIP-account bereikbaar zijn (waar beschikbaar, kan een lege array zijn).

destination.targets.name: De naam van de persoon die wordt gebeld. Dit is meestal null.

redirector: De gegevens van de gespreksdeelnemer die de doorschakeling uitvoert.

redirector.account_number: Het interne nummer van de VoIP-account, waar beschikbaar.

redirector.number: Het nummer waarop de doorstuurder werd gebeld (als het een gebelde was) of het nummer waarmee de de doorstuurder belde (als het een beller was).

redirector.user_numbers: De interne nummers van de gebruikers die hebben ingesteld dat ze op deze VoIP-account bereikbaar zijn (waar beschikbaar, kan een lege array zijn).

redirector.name: De naam van de persoon die wordt gebeld. Dit kan null zijn.

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:

;