Technical Specifications

Technical Specifications

Notifications are sent to the specified URL at various important events in a conversation. The notifications are sent as a POST request with the data in JSON format.

Types of notifications and data

icon

Created

When an incoming call starts, a created message is sent.

{
   "call_id": "58f1a078416b-1531150397.972",
   "timestamp": "2019-07-20T13:17:39+00:00",
   "status": "created",
   "version": "v2",
   "direction": "inbound",
   "caller": {
       "number": "+31508009008",
       "name": null,
       "account_number": null,
       "user_numbers": []
   },
   "destination": {
       "number": "+31508009000"
   }
}

  • call_id: A unique string to identify the call.
  • timestamp: A date and time when the webhook is generated in ISO 8601 format.
  • status: The status of a conversation. For this notification type, it is created.
  • version: A version attribute that can be used in the future to migrate to another version of the webhooks. At this moment, it is always v2.
  • direction: Whether a conversation is incoming (inbound) or outgoing (outbound). The created event is only sent for incoming conversations.
  • caller: The details about the caller.
  • caller.account_number: This information is not sent with the created event.
  • caller.number: The phone number the caller is dialing out from.
  • caller.user_numbers: This information is not sent with the created event.
  • caller.name: This information is not sent with the created event.
  • destination: The details of where the call is going.
  • destination.number: The phone number the caller has entered.

icon

Ringing

A ringing notification is sent when phones start ringing due to an incoming call.

It is possible that multiple ringing notifications are sent in succession when new devices start ringing.

{
  "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": "+31508009000",
    "targets": [
      {
        "account_number": 234,
        "user_numbers": ["678"],
        "number": "+31508009000",
        "name": "Jane Doe"
      },
      {
        "account_number": 456,
        "user_numbers": ["789"],
        "number": "+31508009000",
        "name": "Jan Jansen"
      }
    ]
  }
}
  • call_id: A unique string to identify the call.
  • timestamp: A date and time when the webhook is generated in ISO 8601 format.
  • status: The status of a call. For this notification type, it's ringing.
  • version: A version attribute that can be used in the future to migrate to a different version of webhooks. Currently, it is always v2.
  • direction: Whether a call is incoming (inbound) or outgoing (outbound). Calls between colleagues are listed as outbound.
  • caller: The details about the caller.
  • caller.account_number: The internal number of the VoIP account (where available, for incoming calls this is usually null).
  • caller.number: The phone number the caller is calling from.
  • caller.user_numbers: The internal numbers of the users who have set that they are reachable on this VoIP account (where available, for incoming calls this is usually an empty array).
  • caller.name: The name of the caller.
  • destination: Details about where the call is going.
  • destination.number: The phone number the caller has entered.
  • destination.targets: The phones that are ringing for this call. Phones that are unreachable are not displayed.
  • destination.targets.account_number: The internal number of the VoIP account, where available.
  • destination.targets.user_numbers: The internal numbers of the users who have set that they are reachable on this VoIP account (where available, may be an empty array).
  • destination.targets.number: The number the phone is being called on. Usually, this is the same as destination.number, but the number changes, for example, when a call is forwarded.
  • destination.targets.name: The name of the person being called. For incoming calls, this is almost always null.

icon

in-progress

An in-progress notification is sent when a call is answered.

Note! The target that answers the call is not always one of the devices that initially rang. Due to call pickup, it may happen that the call is answered on a different device.

{
  "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": "+31508009000",
    "target": {
      "account_number": 234,
      "user_numbers": ["678"],
      "number": "+31508009000",
      "name": "Jane Doe"
    }
  }
}
  • call_id: A unique string to identify the call.
  • timestamp: A date and time when the webhook is generated in ISO 8601 format.
  • status: The status of a call. For this notification type, it is in-progress.
  • version: A version attribute that can be used in the future to migrate to a different version of the webhooks. Currently, it is always v2.
  • direction: Whether a call is incoming (inbound) or outgoing (outbound). Calls between colleagues are listed as outbound.
  • caller: The information about the caller.
  • caller.account_number: The internal number of the VoIP account (where available, for incoming calls this is usually null).
  • caller.number: The phone number the caller is dialing from.
  • caller.user_numbers: The internal numbers of the users who have set themselves as reachable on this VoIP account (where available, for incoming calls this is usually an empty array).
  • caller.name: The name of the caller.
  • destination: The information about where the call is going.
  • destination.number: The phone number that the caller has dialed.
  • destination.target: The information of the phone which answered the call.
  • destination.target.account_number: The internal number of the VoIP account, if available.
  • destination.target.number: The number the phone is being called at. Usually, this is the same as destination.number, but the number can change, for example, when a call is forwarded.
  • destination.target.user_numbers: The internal numbers of the users who have set themselves as reachable on this VoIP account (where available, can be an empty array).
  • destination.target.name: The name of the person being called. For incoming calls, this is almost always null.

icon

ended

An ended notification is sent when a conversation is ended. There are a few different reasons why a conversation may end.

An ended notification can be sent after an in-progress notification if the conversation is hung up by one of the participants, after a ringing notification if nobody answered, or as the only notification if no device is reachable.

{
  "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": "+31508009000"
  }
}
  • call_id: A unique string to identify the call.
  • timestamp: A date and time of the moment the webhook is generated in ISO 8601 format.
  • status: The status of a call. For this notification type, it is ended.
  • reason: The reason why a call has ended. The reason can have one of the following values:
  1. completed: The call was successfully completed.
  2. busy: The call was rejected, the called party is busy.
  3. no-answer: No one answered the call, which can have different reasons.
  4. failed: An error occurred preventing the call from being established.
  5. canceled: The caller hung up before anyone could answer.
  6. abandon: When a caller disconnects while waiting in the queue.
  • version: A version attribute that may be used in the future to migrate to a different version of the webhooks. Currently, it is always v2.
  • direction: Whether a call is incoming (inbound) or outgoing (outbound). Calls between colleagues are listed as outbound.
  • caller: Information about the caller.
  • caller.account_number: The internal number of the VoIP account (where available, for incoming calls this is actually always null).
  • caller.number: The telephone number the caller is calling from.
  • caller.user_numbers: The internal numbers of the users who have set themselves to be reachable on this VoIP account (where available, for incoming calls this is actually always an empty array).
  • caller.name: The name of the caller.
  • destination: Information about where the call is going.
  • destination.number: The telephone number the caller has dialed.

icon

warm-transfer

A warm-transfer notification is sent when a call is transferred "warm." In a warm transfer, the transferor first calls the new participant, the new participant answers, speaks with the transferor, and then the call is transferred.

The transfer from the transferor to the third party also generates a ringing and an in-progress notification with its own call_id. During a transfer, these two calls are merged into a single call. The call_id of one of the two calls is then used for the call after the transfer. The other call_id is sent with the transfer as the merged_id and then expires.

{
  "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": "+31508009000",
    "target": {
      "account_number": 246,
      "number": "246",
      "user_numbers": ["680"],
      "name": null
    }
  },
  "redirector": {
    "account_number": 234,
    "number": "+31508009000",
    "user_numbers": ["678"],
    "name": "Jane Doe"
  }
}
  • call_id: A unique string to identify the call, taken from one of the previous calls.
  • merged_id: The call_id of the other previous conversation that will no longer be used.
  • timestamp: A date and time of the moment the webhook is generated in ISO 8601 format.
  • status: The status of a conversation. For this notification type, it is transfer.
  • version: A version attribute that may be used in the future to migrate to a different version of the webhooks. Currently, it is always v2.
  • direction: Whether a conversation is inbound (inbound) or outbound (outbound). Conversations between colleagues are listed as outbound.
  • caller: Data about the person from the old conversation being transferred.
  • caller.account_number: The internal number of the VoIP account (where available, for incoming calls this is almost always null).
  • caller.number: The phone number with which the transfer is made.
  • caller.user_numbers: The internal numbers of the users who have set themselves to be reachable on this VoIP account (where available).
  • caller.name: The name of the forwarded caller.
  • destination: The data about the person to whom the call is being forwarded.
  • destination.number: The phone number that the redirector has entered.
  • destination.target: The data of the phone that answered the call.
  • destination.target.account_number: The internal number of the VoIP account, where available.
  • destination.target.number: The number that the phone is being called on. Usually this is the same as destination.number, but the number may change, for example, when a call is forwarded.
  • destination.target.user_numbers: The internal numbers of the users who have set themselves to be reachable on this VoIP account (where available, can be an empty array).
  • destination.target.name: The name of the person being called. This is usually null.
  • redirector: The data of the caller who is performing the call forwarding.
  • redirector.account_number: The internal number of the VoIP account, where available.
  • redirector.number: The number on which the redirector was called (if it was a called) or the number with which the redirector called (if it was a caller).
  • redirector.user_numbers: The internal numbers of the users who have set themselves as reachable on this VoIP account (where available, may be an empty array).
  • redirector.name: The name of the person being called. This can be null.

icon

cold-transfer

cold-transfer notification is sent when a call is transferred "cold", meaning that the transferrer calls the new participant and transfers the call without waiting or knowing who will answer the call.

There are two main differences between a cold-transfer and a warm-transfer:

  • In a warm transfer, only one person is called, while in a cold transfer, there can be multiple recipients (for example, if the call is transferred to a ring group).
  • For a warm transfer, both ringing and in-progress notifications are generated. In a cold transfer, only a ringing notification is given, and the in-progress notification is only sent if the third party accepts the call.

The conversation from the forwarder to the third party also generates a "ringing" notification with its own "call_id". During a transfer, these two conversations are merged into a single conversation. The call_id of one of the two conversations is then used for the conversation after the transfer. The other call_id is passed along in the transfer as the merged_id and then expires.

{
  "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": "+31508009000",
    "user_numbers": ["678"],
    "name": "Jane Doe"
  }
}
  • call_id: A unique string to identify the call, taken from one of the previous calls.
  • merged_id The call_id of the other previous call, which will no longer be used.
  • timestamp: A date and time of when the webhook is generated in ISO 8601 format.
  • status: The status of a call. For this notification type it is transfer.
  • version: A version attribute that can be used in the future to migrate to a different version of the webhooks. At this time, it is always v2.
  • direction: Whether a call is incoming or outgoing. At this time, only incoming calls are supported, and this value is always inbound.
  • caller: The details about the participant of the old call being transferred.
  • caller.account_number: The internal number of the VoIP account (where available, for incoming calls this is usually null).
  • caller.number: The phone number that the transferred call is dialing out to.
  • caller.user_numbers: The internal numbers of the users who have set themselves as reachable on this VoIP account (where available).
  • caller.name: The name of the transferred call participant.
  • destination: The details about the person to whom the call is being transferred.
  • destination.number: The phone number entered by the redirector.
  • destination.targets: The data of the phone(s) that ring for this redirection.
  • destination.targets.account_number: The internal number of the VoIP account, where available.
  • destination.targets.number: The number to which the phone call is forwarded. Usually, this is the same as destination.number, but the number may change, for example when a call is being forwarded.
  • destination.targets.user_numbers: The internal numbers of the users who have set that they can be reached on this VoIP account (where available, can be an empty array).
  • destination.targets.name: The name of the person being called. This is usually null.
  • redirector: The data of the caller who performs the redirection.
  • redirector.account_number: The internal number of the VoIP account, where available.
  • redirector.number: The number that was called (if it was a callee) or the number with which the redirector called (if it was a caller).
  • redirector.user_numbers: The internal numbers of the users who have set that they can be reached on this VoIP account (where available, can be an empty array).
  • redirector.name: The name of the person being called. This can be null.

Order of notifications

Multiple notifications are sent for each conversation. The notifications that are sent depend on how the conversation is conducted. Below, the order of notifications for the most common types of conversations is discussed.

Simple conversation

A successful conversation with two participants:

  • ringing - A calls B
  • in-progress - A calls B
  • ended - A calls B (reason: completed)

The phone is not being answered

The phone of the person being called is ringing, but not being answered.

  • ringing - A calls B
  • ended - A calls B (reason: busy or no-answer depending on the device)

The person being called is unavailable

The person being called is unavailable (for example, because their phone is on Do Not Disturb), so their phone is not ringing and they are not answering.

  • ended - A calls B (reason: busy)

Attended transfer

During an attended transfer, A first calls B, after which one of the participants transfers the call to Participant C. The participant first calls C, and only after they have spoken, the call is transferred. After the transfer, only the other participants A and C are in the call.

  • ringing - A calls B
  • in-progress - A calls B
  • ringing - B calls C
  • in-progress - B calls C
  • warm-transfer - B connects A and C
  • ended - A and C hang up (reason: 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

During a semi-attended transfer, A first calls B, after which one of the participants forwards the call to participant C. The participant tries to call C first, but transfers the call before C answers.

  • ringing - A calls B
  • in-progress - A calls B
  • ringing - B calls C
  • cold-transfer - B connects A and C
  • in-progress - A calls C
  • ended - A does not call C anymore (reason: completed)

Call pickup

When two phones are in the same pickup group, it is possible to answer a call that is intended for the other phone from one of the phones.

  • Ringing - A calls B
  • In progress - A talks with C
  • Ended - A ends the call with C (reason: completed)

Call forwarding

When a user sets up their phone to automatically forward incoming calls to another number:

  • ringing - A calls B
  • ringing - A calls B & C
  • in progress or ended, depending on whether someone answers.

Example integrations

Below are some examples of integrations in combination with Zapier: