Notificações de chamada

O que são Notificações de chamada?

O módulo de Notificações de Chamada permite enviar automaticamente dados de chamadas para um URL à sua escolha. Estas notificações de chamada são enviadas para o URL especificado para todas as chamadas no seu ambiente do portal.

Ao integrar estas notificações de chamada com o seu software CRM, pode ver quem ligou, a que horas e a duração da chamada.

As notificações de chamada são acionadas para chamadas recebidas, internas e efetuadas. Também pode usar as notificações de chamada para outros fins, como medir estatísticas de chamadas.

Não deixe de consultar Webhooks para maximizar as capacidades do seu serviço telefónico.

‣

Configurações das notificações de chamada

‣

Os acionadores das notificações de chamada

Durante uma chamada, a informação é enviada para o URL especificado em seis momentos diferentes para chamadas recebidas, internas e efetuadas: Criada, A tocar, Atendida, Transferência acompanhada, Transferência direta e Desligada. As notificações são enviadas para o URL especificado em vários eventos importantes durante uma chamada. As notificações são enviadas como um pedido POST com os dados num documento JSON. A seguir, pode ler exatamente que informação é enviada.

Criada

Um evento created é acionado quando uma chamada recebida é iniciada.

{
  "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",
    "account_number": null,
    "user_numbers": [],
    "user_emails": []
  },
  "destination": {
    "number": "+31332022074"
  }
}

call_id: Uma string única para identificar a chamada.
timestamp: A data e hora em que o webhook é gerado, no formato ISO 8601.
status: O estado da chamada. Para este tipo de notificação, é created.
version: Um atributo de versão que pode ser usado no futuro para migrar para outra versão dos webhooks. Atualmente, é sempre v2.
direction: Se uma chamada é recebida (inbound) ou efetuada (outbound). O evento criado é enviado apenas para chamadas recebidas.
caller: Informação sobre quem liga.

number: O número de telefone que está a ser usado por quem liga.
name: O nome de quem liga.
account_number: Esta informação não é enviada com o evento created.
user_numbers: Esta informação não é enviada com o evento created.
user_emails: Esta informação não é enviada com o evento created.

destination: Informação sobre o destino da chamada.

number: O número de telefone marcado por quem liga.

A tocar

Uma notificação ringing é enviada quando os telefones começam a tocar devido a uma chamada recebida.

É possível que várias notificações ringing sejam enviadas sucessivamente à medida que novos dispositivos começam a tocar.

{
  "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",
    "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.com"
        ]
      }
    ]
  }
}

call_id: Uma string única para identificar a chamada.
timestamp: A data e hora em que o webhook é gerado, no formato ISO 8601.
status: O estado da chamada. Para este tipo de notificação, é ringing.
version: Um atributo de versão que pode ser usado no futuro para migrar para outra versão dos webhooks. Atualmente, é sempre v2.
direction: Se uma chamada é recebida (inbound) ou efetuada (outbound). Chamadas entre colegas são marcadas como outbound.
caller: Informação sobre quem liga.

number: O número de telefone que está a ser usado por quem liga.
name: O nome de quem liga.
account_number: Esta informação não é enviada com o evento ringing.
user_numbers: Esta informação não é enviada com o evento ringing.
user_emails: Esta informação não é enviada com o evento ringing.

destination: Informação sobre o destino da chamada.

number: O número de telefone marcado por quem liga.
targets: Os telefones que estão a tocar para esta chamada. Telefones que não estão acessíveis não são mostrados.

number: O número que está a ser chamado. Normalmente é o mesmo que destination.number, mas pode mudar se a chamada for desviada.
name: O nome da pessoa que está a ser chamada. Para chamadas recebidas, isto é quase sempre null.
account_number: Os números internos dos utilizadores que configuraram a sua Conta VoIP para estar acessível (quando disponível, pode ser um array vazio).
user_numbers: Os números internos dos utilizadores que estão acessíveis (quando disponível, pode ser um array vazio).
user_emails: Os endereços de email dos utilizadores.

Atendida (em curso)

É enviada uma notificação in-progress quando uma chamada é atendida.

Atenção! O target que atende a chamada nem sempre é um dos dispositivos que inicialmente tocaram. Devido à resposta de chamadas, pode acontecer que a chamada seja atendida noutro dispositivo.

{
  "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",
    "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.com"
      ]
    }
  }
}

call_id: Uma string única para identificar a chamada.
timestamp: A data e hora em que o webhook é gerado, em formato ISO 8601.
status: O estado da chamada. Para este tipo de notificação, é in-progress.
version: Um atributo de versão que pode ser utilizado no futuro para migrar para outra versão dos webhooks. Atualmente, é sempre v2.
direction: Se uma chamada é recebida (inbound) ou efetuada (outbound). Chamadas entre colegas são marcadas como outbound.
caller: Informações sobre quem está a ligar.

number: O número de telefone que o chamador está a utilizar.
name: O nome do chamador.
account_number: O número interno da Conta VoIP (quando disponível, para chamadas recebidas é quase sempre null).
user_numbers: Os números internos dos utilizadores que são contactáveis (quando disponível, pode ser um array vazio).
user_emails: Os endereços de e-mail dos utilizadores.

destination: Informações sobre o destino da chamada.

number: O número de telefone que o chamador marcou.
targets: Os telefones que estão a tocar para esta chamada. Telefones que estão inacessíveis não são mostrados.

number: O número a ser chamado. Normalmente é o mesmo que destination.number, mas pode mudar se a chamada for desviada.
name: O nome da pessoa a ser chamada. Para chamadas recebidas, é quase sempre null.
account_number: Os números internos dos utilizadores que configuraram a sua Conta VoIP para serem contactáveis (quando disponível, pode ser um array vazio).
user_numbers: Os números internos dos utilizadores que são contactáveis (quando disponível, pode ser um array vazio).
user_emails: Os endereços de e-mail dos utilizadores.

Transferência assistida

É enviada uma notificação warm-transfer quando uma chamada é transferida de forma "assistida". Numa transferência assistida, quem transfere primeiro liga para o novo participante, o novo participante atende, fala com quem transfere e, em seguida, a chamada é transferida.

A chamada de quem transfere para o terceiro também gera notificações ringing e in-progress com o seu próprio call_id. Durante uma transferência, estas duas chamadas são essencialmente fundidas numa única chamada. O call_id de uma das duas chamadas é então utilizado para a chamada após a transferência. O outro call_id é incluído na transferência como merged_id e é depois descartado.

{
  "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": [
        "email2@email.com"
      ]
    }
  },
  "redirector": {
    "number": "610",
    "name": "Johan N",
    "account_number": "201",
    "user_numbers": [
      "610"
    ],
    "user_emails": [
      "email@email.com"
    ]
  }
}

call_id: Uma string única para identificar a chamada, mantida de uma das chamadas anteriores.
merged_id: O call_id da outra chamada anterior, que deixará de ser utilizado.
timestamp: A data e hora em que o webhook é gerado, em formato ISO 8601.
status: O estado da chamada. Para este tipo de notificação, é transfer.
version: Um atributo de versão que pode ser utilizado no futuro para migrar para outra versão dos webhooks. Atualmente, é sempre v2.
direction: Se uma chamada é recebida (inbound) ou efetuada (outbound). Chamadas entre colegas são marcadas como outbound.
caller: Informações sobre quem está a ligar.

number: O número de telefone que o chamador está a utilizar.
name: O nome do chamador.
account_number: O número interno da Conta VoIP (quando disponível, para chamadas recebidas é quase sempre null).
user_numbers: Os números internos dos utilizadores que são contactáveis (quando disponível, pode ser um array vazio).
user_emails: Os endereços de e-mail dos utilizadores.

destination: Informações sobre o destino da chamada.

number: O número de telefone que o chamador marcou.
targets: Os telefones que estão a tocar para esta chamada. Telefones que estão inacessíveis não são mostrados.

number: O número a ser chamado. Normalmente é o mesmo que destination.number, mas pode mudar se a chamada for desviada.
name: O nome da pessoa a ser chamada. Para chamadas recebidas, é quase sempre null.
account_number: Os números internos dos utilizadores que configuraram a sua Conta VoIP para serem contactáveis (quando disponível, pode ser um array vazio).
user_numbers: Os números internos dos utilizadores que são contactáveis (quando disponível, pode ser um array vazio).
user_emails: Os endereços de e-mail dos utilizadores.

redirector: Informações sobre o participante que efetuou a transferência.

number: O número de telefone que o redirecionador está a utilizar.
name: O nome do redirecionador.
account_number: O número interno da Conta VoIP (quando disponível, para chamadas recebidas é quase sempre null).
user_numbers: Os números internos dos utilizadores que são contactáveis (quando disponível, pode ser um array vazio).
user_emails: Os endereços de email dos utilizadores.

Transferência fria

Uma notificação cold-transfer é enviada quando uma chamada é transferida a frio. Numa transferência fria, quem transfere liga para o novo participante mas transfere a chamada sem esperar para ver se alguém atende ou quem atende.

Existem duas diferenças principais entre um cold-transfer e um warm-transfer:

Numa transferência quente, existe sempre uma parte chamada, enquanto numa transferência fria pode haver várias (por exemplo, se a chamada for transferida para um grupo de chamadas).
Para uma transferência quente, as notificações ringing e in-progress são geradas primeiro. Numa transferência fria, apenas é enviada uma notificação ringing, e uma notificação in-progress segue-se apenas se a terceira parte atender a chamada.

A chamada de quem transfere para a terceira parte também gera uma notificação ringing com o seu próprio call_id. Durante uma transferência, estas duas chamadas são essencialmente fundidas numa única chamada. O call_id de uma das duas chamadas é então usado para a chamada após a transferência. O outro call_id é incluído na transferência como o merged_id e é então descartado.

{
  "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": [
          "email2@email.com"
        ]
      }
    ]
  },
  "redirector": {
    "number": "+31332022074",
    "name": null,
    "account_number": "201",
    "user_numbers": [
      "610"
    ],
    "user_emails": [
      "email@email.com"
    ]
  }
}

call_id: Uma string única para identificar a chamada, transportada de uma das chamadas anteriores.
merged_id: O call_id da outra chamada anterior, que deixará de ser usado.
timestamp: A data e hora em que o webhook é gerado, em formato ISO 8601.
status: O estado da chamada. Para este tipo de notificação, é transfer.
version: Um atributo de versão que pode ser usado no futuro para migrar para outra versão dos webhooks. Atualmente, é sempre v2.
direction: Se uma chamada é recebida ou efetuada. Atualmente, apenas chamadas recebidas são suportadas, pelo que este valor é sempre inbound.
caller: Informação sobre quem liga.

number: O número de telefone que quem liga está a usar.
name: O nome de quem liga.
account_number: O número interno da Conta VoIP (quando disponível, para chamadas recebidas é quase sempre null).
user_numbers: Os números internos dos utilizadores que estão acessíveis (quando disponível, pode ser um array vazio).
user_emails: Os endereços de email dos utilizadores.

destination: Informação sobre para onde a chamada é direcionada.

number: O número de telefone que quem liga marcou.
targets: Os telefones que estão a tocar para esta chamada. Telefones que não estão acessíveis não são mostrados.

number: O número que está a ser chamado. Normalmente é o mesmo que destination.number, mas pode mudar se a chamada for desviada.
name: O nome da pessoa que está a ser chamada. Para chamadas recebidas, é quase sempre null.
account_number: Os números internos dos utilizadores que configuraram a sua Conta VoIP para estar acessível (quando disponível, pode ser um array vazio).
user_numbers: Os números internos dos utilizadores que estão acessíveis (quando disponível, pode ser um array vazio).
user_emails: Os endereços de email dos utilizadores.

redirector: Informação sobre o participante que realizou a transferência.

number: O número de telefone que quem redireciona está a usar.
name: O nome de quem redireciona.
account_number: O número interno da Conta VoIP (quando disponível, para chamadas recebidas é quase sempre null).
user_numbers: Os números internos dos utilizadores que estão acessíveis (quando disponível, pode ser um array vazio).
user_emails: Os endereços de email dos utilizadores.

Pendurar (terminada)

Uma notificação ended é enviada quando uma chamada é terminada. Existem várias razões pelas quais uma chamada pode terminar.

Uma notificação ended pode ser enviada após uma notificação in-progress se a chamada foi terminada por um dos participantes, após uma notificação ringing se ninguém atendeu, ou como a única notificação se nenhum dispositivo estava acessível.

{
  "call_id": "ua4-ams-prd-1766999450.29340564",
  "timestamp": "2025-12-29T09:11:55.875026+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",
    "target": {
      "number": "+31332022074",
      "name": null,
      "account_number": "101",
      "user_numbers": [],
      "user_emails": []
    }
  }
}

call_id: Uma string única para identificar a chamada.
timestamp: A data e hora em que o webhook é gerado, em formato ISO 8601.
status: O estado da chamada. Para este tipo de notificação, é ended.
reason: A razão pela qual a chamada terminou. A razão pode ser um dos seguintes valores:

completed: A chamada foi concluída com sucesso.
busy: A chamada foi rejeitada, o destinatário estava ocupado.
no-answer: Ninguém atendeu a chamada por várias razões.
failed: Ocorreu um erro que impediu o estabelecimento da chamada.
cancelled: Quem ligou desligou antes de alguém poder atender.
abandon: Quem ligou desligou enquanto aguardava na fila.

version: Um atributo de versão que pode ser usado no futuro para migrar para outra versão dos webhooks. Atualmente, é sempre v2.
direction: Se uma chamada é recebida (inbound) ou efetuada (outbound). Chamadas entre colegas são marcadas como outbound.
caller: Informação sobre quem liga.

number: O número de telefone que quem liga está a usar.
name: O nome de quem liga.
account_number: O número interno da conta VoIP (quando disponível, para chamadas recebidas é quase sempre null).
user_numbers: Os números internos dos utilizadores que estão disponíveis (quando disponível, pode ser um array vazio).
user_emails: Os endereços de email dos utilizadores.

destination: Informação sobre o destino da chamada.

number: O número de telefone que quem liga marcou.

Transcrição criada

Uma notificação call_transcription é enviada quando a transcrição está pronta.

Se o Voys Intelligence estiver ativado. Este é o primeiro evento que se segue a uma notificação ended. Se os resumos de chamadas estiverem ativados, o evento summary seguir-se-á em breve.

{            
  "call_id": "ua0-grq-prd-1780997460.58680",
  "call_transcription": "Speaker 1: Hi how are you.\nSpeaker 2: Hey great that you called.",        
}

Resumo criado

Uma notificação summary é enviada quando o resumo da chamada está pronto.

Se o Voys Intelligence estiver ativado. Este é o último evento para uma chamada específica.

{
  "call_id": "ua0-grq-prd-1780997460.58680", 
  "summary": "This was a great call."
}

‣

Ordem das notificações

ringing - A liga para B
in-progress - A liga para B
ended - A liga para B (motivo: completed)

Chamada simples com Voys Intelligence ativado

Uma chamada bem-sucedida com dois participantes:

ringing - A liga para B
in-progress - A liga para B
ended - A liga para B (motivo: completed)
call_transcription - transcrição da chamada está pronta
summary - resumo da chamada está pronto

Sem resposta

O telefone de quem recebe toca mas não é atendido.

ringing - A liga para B
ended - A liga para B (motivo: busy ou no-answer dependendo do dispositivo)

Destinatário indisponível

O destinatário está indisponível (por exemplo, o telefone está em Não Incomodar), portanto o telefone não toca e a chamada não é atendida.

ended - A liga para B (motivo: busy)

Transferência Assistida

Numa transferência assistida (transferência quente), A liga primeiro para B, depois um dos participantes transfere a chamada para C. O participante liga primeiro para C e, após falarem, a chamada é transferida. Apenas os participantes A e C permanecem na chamada.

ringing - A liga para B
in-progress - A liga para B
ringing - B liga para C
in-progress - B liga para C
warm-transfer - B liga A e C
ended - A e C desligam (motivo: completed)
call_transcription - transcrição da chamada está pronta (uma por segmento de chamada, se ativado)
summary - resumo da chamada está pronto (um por segmento de chamada, se ativado)

Transferência Direta

Numa transferência direta (transferência fria), A liga primeiro para B, depois um dos participantes transfere a chamada para C sem esperar para ver se C está disponível.

ringing - A liga para B
in-progress - A liga para B
ringing - B liga para C
cold-transfer - B liga A e C
in-progress - A liga para C
ended - A deixa de ligar para C (motivo: completed)
call_transcription - a transcrição da chamada está pronta
summary - o resumo da chamada está pronto

Transferência semi-acompanhada

Numa transferência semi-acompanhada (transferência morna), A liga primeiro para B e, em seguida, um dos participantes transfere a chamada para C. O participante tenta ligar para C primeiro, mas transfere a chamada antes de C atender.

ringing - A liga para B
in-progress - A liga para B
ringing - B liga para C
cold-transfer - B conecta A e C
in-progress - A liga para C
ended - A deixa de ligar para C (motivo: completed)
call_transcription - a transcrição da chamada está pronta
summary - o resumo da chamada está pronto

Captura de Chamada

Quando dois telefones estão no mesmo grupo de resposta, é possível atender uma chamada destinada a outro telefone a partir de um telefone.

ringing - A liga para B
in-progress - A liga para C
ended - A deixa de ligar para C (motivo: completed)
call_transcription - a transcrição da chamada está pronta
summary - o resumo da chamada está pronto

Desvio de chamada

Quando um utilizador configura o seu telefone para desviar automaticamente chamadas recebidas para outro número.

ringing - A liga para B
ringing - A liga para B e C
in-progress ou ended, dependendo se alguém atende.
call_transcription - a transcrição da chamada está pronta
summary - o resumo da chamada está pronto

São enviadas várias notificações para cada chamada. As notificações enviadas dependem da forma como a chamada é tratada. Abaixo está a ordem das notificações para os tipos de chamadas mais comuns.