CTI genérico

Introdução

Esta página descreve os escopos e funcionalidades genéricos da API CTI.

WARNING

A autenticação neste endpoint funciona de forma fundamentalmente diferente comparada a o restante da API.
Clientes de API não funcionam com os endpoints CTI, a menos que explicitamente indicado pelo fornecedor do cliente!
Os endpoints CTI são relevantes apenas para sistemas PBX.

Recursos

Aqui está uma pequena lista condensada das possibilidades que essa API CTI oferece.

Entrada

Funções de registro de chamadas para seus agentes.
Bloqueio de IDs de chamador durante a sinalização.

Saída

Funções de registro de chamadas para seus agentes.
Definir IDs de chamador de saída dependendo do destino do ID de chamador.

Endpoint

O endpoint pode ser encontrado na integração CTI genérica e contém um token único que atua como autenticação. Certifique-se de manter essa URL de endpoint segura.

INFO

A configuração CTI genérica e o endpoint correto podem ser encontrados no seu Zammad na interface de administração em System > Integrations > CTI (generic).

Observe também os requisitos e limitações listados ali. Todas as opções que exigem retornos (por exemplo, bloqueio, manipulação de IDs de chamador de saída) dependem de configurações dentro da página de integração CTI do Zammad.

TIP

Há duas opções de como fazer POST dos dados relevantes para o Zammad:

JSON (recomendado)
Form-data

Eventos

Há vários eventos em termos de uma chamada em andamento. Essas ações sempre vêm do seu sistema PBX e podem ser:

evento "newCall" (início de uma chamada)
evento "hangup" (fim da chamada)
evento "answer" (também conhecido como atender o telefone)

Em algumas situações, o Zammad pode fornecer um retorno em suas chamadas do PBX (por exemplo, uma rejeição) se você bloqueou um chamador específico. O Zammad nunca iniciará ações específicas com seu PBX. O Zammad é um componente passivo em todos os casos descritos.

Exemplos usados

Exemplo: As chamadas abaixo foram enviadas com a seguinte configuração. Isso é importante para você entender as respostas que estamos mostrando aqui.

Saída:

ID de chamador de destino 4989* define ID de chamador de saída 498999998145 com nota "All from munich"
ID de chamador de destino 4930* define ID de chamador de saída 493023125877 "All from Berlin"

Outras configurações:

ID de chamador padrão para chamadas de saída 496990009111

Evento de nova chamada

Geral

attributes disponíveis e sample data:

event newCall: informa ao Zammad que há uma nova chamada.
from 4930555716000: número que iniciou a chamada. Também pode ser anonymous.
to 4930555716000: número que está sendo chamado.
direction in: a direção da chamada. Se seu agente iniciar uma chamada, isso será out. Chamadas vindas de fora para você são in.
callId 53ba82e2bd6d12d9fb2d3838f0cfb070: um ID único para a chamada. O Zammad usará esse ID para identificar uma chamada existente com as ações seguintes (por exemplo, atender ou desligar).
user John Doe: o nome real do(s) usuário(s) envolvido(s). Você pode precisar fornecer parâmetros no estilo array ([]), dependendo do método de chamada escolhido. Se a direção for out, este é o nome da(s) pessoa(s) que ligou(aram). Se a direção for in, este é o nome da(s) pessoa(s) chamada(s).
queue support: um nome de fila opcional; essa opção é relevante para o filtro de registro de chamadas. Este valor é opcional.

Saída

Details

Solicitação POST enviada: https://{FQDN-Zammad}/api/v1/cti/{instance specific token}

Payload:

json

{
  "event": "newCall",
  "from": "493023125741",
  "to": "492214710334",
  "direction": "out",
  "callId": "f4ebd2be-7b9a-4d58-94c2-eb06a3c2ce76",
  "user": "Lauren Brooks"
}

Resposta:

json

{
  "action": "dial",
  "caller_id": "496990009111",
  "number": "492214710334"
}

Comando curl de exemplo:

curl --request POST 'https://{FQDN-Zammad}/api/v1/cti/{instance specific token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "event": "newCall",
    "from": "493023125741",
    "to": "492214710334",
    "direction": "out",
    "callId": "f4ebd2be-7b9a-4d58-94c2-eb06a3c2ce76",
    "user": "Lauren Brooks"
  }'

Entrada

Details

Payload:

json

{
  "event": "newCall",
  "from": "493023125741",
  "to": "492214710334",
  "direction": "in",
  "callId": "307fa962-de8d-4ffc-817b-7f6993204159",
  "user": [
    "Lauren Brooks",
    "Ethan Kwan"
  ]
}

Resposta:

json

{}

Comando curl de exemplo:

curl --request POST 'https://{FQDN-Zammad}/api/v1/cti/{instance specific token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
     "event": "newCall",
     "from": "493023125741",
     "to": "492214710334",
     "direction": "in",
     "callId": "307fa962-de8d-4ffc-817b-7f6993204159",
     "user": ["Lauren Brooks", "Ethan Kwan"]
  }'

Respostas específicas por situação

Dependendo da direção da chamada escolhida, o Zammad retornará um ID de chamada (opcionalmente) configurado, ou bloqueará (opcionalmente) um chamador. Se seu Zammad não tiver configurado uma ou ambas as opções, o retorno será vazio.

INFO

Isso precisa ser suportado pelo seu PBX para funcionar.

Rejeitar IDs de chamador bloqueados

Se uma nova chamada recebida corresponder a um número a bloquear, o Zammad retornará o seguinte.

json

{
  "action": "reject",
  "reason": "busy"
}

Se nenhum número a bloquear corresponder, o Zammad retornará o seguinte.

json

{}

WARNING

Seu PBX ainda precisa encerrar a chamada (evento hangup). Caso contrário, a chamada não apenas aparecerá no registro de chamadas do Zammad, mas também aparecerá como uma chamada em andamento.

Definir ID de chamador de saída específico

Caso sua instância tenha um ID de chamador de sobrescrita correspondente configurado, o Zammad retornará o seguinte payload.

json

{
  "action": "dial",
  "callerId": "493055571642",
  "number": "491711234567890"
}

Se nenhuma correspondência de sobrescrita for encontrada, ou você não configurou nada, o Zammad retornará o seguinte.

json

{}

Evento de atendimento de chamada

Geral

attributes disponíveis e sample data:

event answer:: informa ao Zammad que alguém atendeu a chamada.
from 493055571600:: número que iniciou a chamada.
to 493055571600:: número que está sendo chamado.
direction in:: a direção da chamada - se seu agente iniciar uma chamada, isso será out.
callId 53ba82e2bd6d12d9fb2d3838f0cfb070:: um ID único para a chamada. O Zammad usará esse ID para identificar uma chamada existente com as ações seguintes (por exemplo, atender ou desligar).
answeringNumber 493055571600:: o Zammad procurará um usuário com o valor fornecido; os seguintes atributos serão avaliados na ordem dada: - user.phone - user.login - user.if Este valor é opcional.
user John Doe:: o nome real do(s) usuário(s) envolvido(s). Você pode precisar fornecer parâmetros no estilo array ([]), dependendo do método de chamada escolhido. Se a direção for out, este é o nome da(s) pessoa(s) que ligou(aram). Se a direção for in, este é o nome da(s) pessoa(s) chamada(s). Este valor é opcional.

Há duas opções de como fazer POST dos dados relevantes para o Zammad.

Saída

Details

Solicitação POST enviada: https://{FQDN-Zammad}/api/v1/cti/{instance specific token}

Payload:

json

{
  "event": "answer",
  "from": "493023125741",
  "to": "492214710334",
  "direction": "out",
  "callId": "9f1840cb-8be9-4d3a-8200-3da2937085f0",
  "caller": "Lauren Brooks"
}

Resposta:

json

{}

Comando curl de exemplo:

curl --request POST 'https://{FQDN-Zammad}/api/v1/cti/{instance specific token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
     "event": "answer",
     "from": "493023125741",
     "to": "492214710334",
     "direction": "out",
     "callId": "9f1840cb-8be9-4d3a-8200-3da2937085f0",
     "caller": "Lauren Brooks"
  }'

Entrada

Details

Payload:

json

{
  "event": "answer",
  "from": "493023125741",
  "to": "492214710334",
  "direction": "in",
  "callId": "307fa962-de8d-4ffc-817b-7f6993204159",
  "answeringNumber": "emily@fastlane.inc",
  "caller": [
    "Lauren Brooks",
    "Emily Tran"
  ]
}

Resposta:

json

{}

Comando curl de exemplo:

curl --request POST 'https://{FQDN-Zammad}/api/v1/cti/{instance specific token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
     "event": "answer",
     "from": "493023125741",
     "to": "492214710334",
     "direction": "in",
     "callId": "307fa962-de8d-4ffc-817b-7f6993204159",
     "answeringNumber": "emily@fastlane.inc",
     "caller": ["Lauren Brooks", "Emily Tran"]
  }'

Encerramento de chamada

Geral

event hangup:

informa ao Zammad que alguém atendeu a chamada.

from 493055571600:

número que iniciou a chamada.

to 493055571600:

número que está sendo chamado.

direction in:

a direção da chamada - se seu agente iniciar uma chamada, isso será out.

callId 53ba82e2bd6d12d9fb2d3838f0cfb070:

um ID único para a chamada. O Zammad usará esse ID para identificar uma chamada existente com as ações seguintes (por exemplo, atender ou desligar).

cause

isso define o motivo do encerramento. O Zammad avalia a causa e indica, por exemplo, chamadas perdidas de acordo, no registro de chamadas. Os valores possíveis são:

normalClearing (uma das partes desligou após a chamada ser estabelecida)
busy (a parte chamada estava ocupada)
cancel (o chamador desligou antes de a parte chamada atender)
noAnswer (a parte chamada rejeitou a chamada. Por exemplo, através de uma configuração DND)
congestion (a parte chamada não pôde ser alcançada)
notFound (o número chamado não existe ou a parte chamada está offline)
forwarded (a chamada foi encaminhada para outra parte)

answeringNumber 493055571600:

o Zammad procurará um usuário com o valor fornecido; os seguintes atributos serão avaliados na ordem dada:

user.phone
user.login
user.if Este valor é opcional.

Saída

Details

Solicitação POST enviada: https://{FQDN-Zammad}/api/v1/cti/{instance specific token}

Payload:

json

{
  "event": "hangup",
  "from": "493023125741",
  "to": "492214710334",
  "direction": "out",
  "callId": "f4ebd2be-7b9a-4d58-94c2-eb06a3c2ce76",
  "cause": "cancel"
}

Resposta:

json

{}

Comando curl de exemplo:

curl --request POST 'https://{FQDN-Zammad}/api/v1/cti/{instance specific token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
     "event": "hangup",
     "from": "493023125741",
     "to": "492214710334",
     "direction": "out",
     "callId": "f4ebd2be-7b9a-4d58-94c2-eb06a3c2ce76",
     "cause": "cancel"
  }'

Entrada

Details

Payload:

json

{
  "event": "hangup",
  "from": "493023125741",
  "to": "492214710334",
  "direction": "in",
  "callId": "2d77882f-68df-40f0-8c62-b642589c00bc",
  "answeringNumber": "emily@fastlane.inc",
  "cause": "normalClearing"
}

Resposta:

json

{}

Comando curl de exemplo:

curl --request POST 'https://{FQDN-Zammad}/api/v1/cti/{instance specific token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
     "event": "hangup",
     "from": "493023125741",
     "to": "492214710334",
     "direction": "in",
     "callId": "307fa962-de8d-4ffc-817b-7f6993204159",
     "answeringNumber": "emily@fastlane.inc",
     "cause": "normalClearing"
  }'

Fundamentos

Guias

CTI genérico

Introdução

Recursos

Entrada

Saída

Endpoint

Eventos

Exemplos usados

Evento de nova chamada

Geral

Saída

Entrada

Respostas específicas por situação

Rejeitar IDs de chamador bloqueados

Definir ID de chamador de saída específico

Evento de atendimento de chamada

Geral

Saída

Entrada

Encerramento de chamada

Geral

Saída

Entrada

CTI genérico ​

Introdução ​

Recursos ​

Entrada ​

Saída ​

Endpoint ​

Eventos ​

Exemplos usados ​

Evento de nova chamada ​

Geral ​

Saída ​

Entrada ​

Respostas específicas por situação ​

Rejeitar IDs de chamador bloqueados ​

Definir ID de chamador de saída específico ​

Evento de atendimento de chamada ​

Geral ​

Saída ​

Entrada ​

Encerramento de chamada ​

Geral ​

Saída ​

Entrada ​

CTI genérico

Introdução

Recursos

Entrada

Saída

Endpoint

Eventos

Exemplos usados

Evento de nova chamada

Geral

Saída

Entrada

Respostas específicas por situação

Rejeitar IDs de chamador bloqueados

Definir ID de chamador de saída específico

Evento de atendimento de chamada

Geral

Saída

Entrada

Encerramento de chamada

Geral

Saída

Entrada