Call notifications

During a call, information is sent to the specified URL at six different moments for incoming, internal, and outgoing calls: Created, Ringing, Answered, Warm transfer, Cold transfer, and Hang-up. Notifications are sent to the specified URL at various important events during a call. The notifications are sent as a POST request with the data in a JSON document. Beneath, you can read what information is being sent exactly.

Created

A created event is triggered when an incoming call is initiated.

• call_id: A unique string to identify the call.
• timestamp: The date and time when the webhook is generated, in ISO 8601 format.
• status: The status of the call. 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. Currently, it is always v2.
• direction: Whether a call is incoming (inbound) or outgoing (outbound). The created event is only sent for incoming calls.
• caller: Information about the caller.
• number: The phone number the caller is using.
• name: The name of the caller.
• account_number: This information is not sent with the created event.
• user_numbers: This information is not sent with the created event.
• user_emails: This information is not sent with the created event.
• destination: Information about where the call is directed.
• number: The phone number the caller dialed.

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 as new devices begin to ring.

• call_id: A unique string to identify the call.
• timestamp: The date and time when the webhook is generated, in ISO 8601 format.
• status: The status of the call. For this notification type, it is ringing.
• version: A version attribute that can be used in the future to migrate to another version of the webhooks. Currently, it is always v2.
• direction: Whether a call is incoming (inbound) or outgoing (outbound). Calls between colleagues are marked as outbound.
• caller: Information about the caller.
• number: The phone number the caller is using.
• name: The name of the caller.
• account_number: This information is not sent with the ringing event.
• user_numbers: This information is not sent with the ringing event.
• user_emails: This information is not sent with the ringing event.
• destination: Information about where the call is directed.
• number: The phone number the caller dialed.
• targets: The phones that are ringing for this call. Phones that are unreachable are not shown.
• number: The number that is being called. This is usually the same as destination.number, but can change if the call is forwarded.
• name: The name of the person being called. For incoming calls, this is almost always null.
• account_number: The internal numbers of the users who have set up their VoIP account to be reachable (where available, can be an empty array).
• user_numbers: The internal numbers of the users who are reachable (where available, can be an empty array).
• user_emails: The email addresses of the users.

Answered (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: A unique string to identify the call.
• timestamp: The date and time when the webhook is generated, in ISO 8601 format.
• status: The status of the call. For this notification type, it is in-progress.
• version: A version attribute that can be used in the future to migrate to another version of the webhooks. Currently, it is always v2.
• direction: Whether a call is incoming (inbound) or outgoing (outbound). Calls between colleagues are marked as outbound.
• caller: Information about the caller.
• number: The phone number the caller is using.
• name: The name of the caller.
• account_number: The internal number of the VoIP account (where available, for incoming calls this is almost always null).
• user_numbers: The internal numbers of the users who are reachable (where available, can be an empty array).
• user_emails: The email addresses of the users.
• destination: Information about where the call is directed.
• number: The phone number the caller dialed.
• targets: The phones that are ringing for this call. Phones that are unreachable are not shown.
• number: The number being called. This is usually the same as destination.number, but it can change if the call is forwarded.
• name: The name of the person being called. For incoming calls, this is almost always null.
• account_number: The internal numbers of the users who have set up their VoIP account to be reachable (where available, can be an empty array).
• user_numbers: The internal numbers of the users who are reachable (where available, can be an empty array).
• user_emails: The email addresses of the users.

Warm transfer

A warm-transfer notification is sent when a call is "warm" transferred. 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 call from the transferor to the third party also generates ringing and in-progress notifications with their own call_id. During a transfer, these two calls are essentially 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 included in the transfer as the merged_id and is then discarded.

• call_id: A unique string to identify the call, carried over from one of the previous calls.
• merged_id: The call_id of the other previous call, which will no longer be used.
• timestamp: The date and time when the webhook is generated, in ISO 8601 format.
• status: The status of the call. For this notification type, it is transfer.
• version: A version attribute that can be used in the future to migrate to another version of the webhooks. Currently, it is always v2.
• direction: Whether a call is incoming (inbound) or outgoing (outbound). Calls between colleagues are marked as outbound.
• caller: Information about the caller.
• number: The phone number the caller is using.
• name: The name of the caller.
• account_number: The internal number of the VoIP account (where available, for incoming calls this is almost always null).
• user_numbers: The internal numbers of the users who are reachable (where available, can be an empty array).
• user_emails: The email addresses of the users.
• destination: Information about where the call is directed.
• number: The phone number the caller dialed.
• targets: The phones that are ringing for this call. Phones that are unreachable are not shown.
• number: The number being called. This is usually the same as destination.number, but it can change if the call is forwarded.
• name: The name of the person being called. For incoming calls, this is almost always null.
• account_number: The internal numbers of the users who have set up their VoIP account to be reachable (where available, can be an empty array).
• user_numbers: The internal numbers of the users who are reachable (where available, can be an empty array).
• user_emails: The email addresses of the users.
• redirector: Information about the participant who performed the transfer.
• number: The phone number the redirector is using.
• name: The name of the redirector.
• account_number: The internal number of the VoIP account (where available, for incoming calls this is almost always null).
• user_numbers: The internal numbers of the users who are reachable (where available, can be an empty array).
• user_emails: The email addresses of the users.

Cold transfer

A cold-transfer notification is sent when a call is cold transferred. In a cold transfer, the transferor calls the new participant but transfers the call without waiting to see if or who answers.

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

• In a warm transfer, there is always one called party, whereas in a cold transfer there can be multiple (e.g., if the call is transferred to a call group).
• For a warm transfer, ringing and in-progress notifications are generated first. In a cold transfer, only a ringing notification is sent, and an in-progress notification follows only if the third party answers the call.

The call from the transferor to the third party also generates a ringing notification with its own call_id. During a transfer, these two calls are essentially 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 included in the transfer as the merged_id and is then discarded.

• call_id: A unique string to identify the call, carried over from one of the previous calls.
• merged_id: The call_id of the other previous call, which will no longer be used.
• timestamp: The date and time when the webhook is generated, in ISO 8601 format.
• status: The status of the call. For this notification type, it is transfer.
• version: A version attribute that can be used in the future to migrate to another version of the webhooks. Currently, it is always v2.
• direction: Whether a call is incoming or outgoing. Currently, only incoming calls are supported, so this value is always inbound.
• caller: Information about the caller.
• number: The phone number the caller is using.
• name: The name of the caller.
• account_number: The internal number of the VoIP account (where available, for incoming calls this is almost always null).
• user_numbers: The internal numbers of the users who are reachable (where available, can be an empty array).
• user_emails: The email addresses of the users.
• destination: Information about where the call is directed.
• number: The phone number the caller dialed.
• targets: The phones that are ringing for this call. Phones that are unreachable are not shown.
• number: The number being called. This is usually the same as destination.number, but it can change if the call is forwarded.
• name: The name of the person being called. For incoming calls, this is almost always null.
• account_number: The internal numbers of the users who have set up their VoIP account to be reachable (where available, can be an empty array).
• user_numbers: The internal numbers of the users who are reachable (where available, can be an empty array).
• user_emails: The email addresses of the users.
• redirector: Information about the participant who performed the transfer.
• number: The phone number the redirector is using.
• name: The name of the redirector.
• account_number: The internal number of the VoIP account (where available, for incoming calls this is almost always null).
• user_numbers: The internal numbers of the users who are reachable (where available, can be an empty array).
• user_emails: The email addresses of the users.

Hang-up (ended)

A ended notification is sent when a call is terminated. There are several reasons why a call may end.

A ended notification can be sent after an in-progress notification if the call was hung up by one of the participants, after a ringing notification if no one answered, or as the only notification if no devices were reachable.

• call_id: A unique string to identify the call.
• timestamp: The date and time when the webhook is generated, in ISO 8601 format.
• status: The status of the call. For this notification type, it is ended.
• reason: The reason why the call ended. The reason can be one of the following values:
1. completed: The call was successfully completed.
2. busy: The call was rejected, the callee was busy.
3. no-answer: No one answered the call for various reasons.
4. failed: An error occurred preventing the call from being established.
5. cancelled: The caller hung up before anyone could answer.
6. abandon: The caller hung up while waiting in the queue.
• version: A version attribute that can be used in the future to migrate to another version of the webhooks. Currently, it is always v2.
• direction: Whether a call is incoming (inbound) or outgoing (outbound). Calls between colleagues are marked as outbound.
• caller: Information about the caller.
• number: The phone number the caller is using.
• name: The name of the caller.
• account_number: The internal number of the VoIP account (where available, for incoming calls this is almost always null).
• user_numbers: The internal numbers of the users who are reachable (where available, can be an empty array).
• user_emails: The email addresses of the users.
• destination: Information about where the call is directed.
• number: The phone number the caller dialed.

Multiple notifications are sent for each call. The notifications sent depend on how the call is handled. Below is the order of notifications for the most common types of calls.

Simple call

A successful call with two participants:

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

No Answer

The callee's phone rings but is not answered.

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

Callee unavailable

The callee is unavailable (e.g., the phone is set to Do Not Disturb), so the phone does not ring and the call is not answered.

• ended - A calls B (reason: busy)

Attended Transfer

In an attended transfer (warm transfer), A first calls B, then one of the participants transfers the call to C. The participant first calls C, and after they have spoken, the call is transferred. Only participants A and C remain 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

In a blind transfer (cold transfer), A first calls B, then one of the participants transfers the call to C without waiting to see if C is available.

• 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 no longer calls C (reason: completed)

Semi-attended transfer

In a semi-attended transfer (lukewarm transfer), A first calls B, then one of the participants transfers the call to 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 no longer calls C (reason: completed)

Call Pickup

When two phones are in the same pickup group, it is possible to pick up a call intended for another phone from one phone.

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

Call forwarding

When a user sets 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.

• Go to Call Notifications.
• Click on Add.
• Enter a description in the Description field to specify the purpose of the notification.
• Choose 'Custom' from the Package options unless you prefer to use a standard option.
• Fill the URL where the conversation notifications should be sent.
• Fill in the API token if your selected package provides one.

Note: this is only required if your package issues an API token.

• Press Save.

Below are some examples of integrations in combination with Zapier:

• Send a message to Slack for a missed call.
• Send an email for a missed call.
• Robin integration.
• Microsoft Flow integratie
• Zapier integratie

And an example with N8N and our call transcription API

Automatically get call transcriptions using N8N