Technical Specifications

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.

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.

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.

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.

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.

cold-transfer

A 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.