Documentações

# Service Click-to-call

N|Solid (opens new window)

# Fazendo uma ligação entre um Endpoint/Ramal e um Destino

Você pode integrar nossa API de Click-to-Call usando nossos serviços em Nuvem ou diretamente com seu PBX basedo em Asterisk e com nosso Conector instalado.

  • Integração em Cloud: Esta integração é o melhor caminho quando você tem um Sistema na Nuvem e/ou não tem acesso externo ao IP de seu PBX ou simplismente não quer abrí-lo para a Internet.
Server URL
Primary Server https://ast.opens.com.br (opens new window)
Secondary Server http://ast2.opens.com.br (opens new window)
  • Integração Local: Quando você um rede local e um único sistema, talvez você prefira apontar sua API diretamente para o IP local de seu PBX.
Server URL
Your Local Asterisk/SNEP PBX http://YOUR_LOCAL_IP:3000 (opens new window)
API Ação
/call Fazer chamada

# Autenticação

A Autenticação é através de seu TOKEN. Se você não é usuário do Q-Manager (opens new window) ainda, você pode conseguir o seu com nosso Customer Success Team (opens new window).

Você pode enviar o token na Request de 2 maneiras diferentes: no Body como uma chave do objeto JSON ou no Header.

No Body você vai enviar uma key/value como os outros parâmetros. O nome especial da chave para isso é token:

{
    "token": String,
}
1
2
3

No Header como um cabeçalho Authorization:

Authorization: Bearer YOUR_TOKEN
1

# Request

A Request pode ser POST, como um Objeto JSON no Body, ou GET, com url parameters.

Para uma Request POST você precisa setar o Cabeçalho content-type para application/json.

Os parâmetros são:

POST /call HTTP/1.1
Authorization: Bearer YourTokenComesHere
Accept: application/json
User-Agent: Http/2.2
Host: ast.opens.com.br

{
    "token": String,
    "from": String,
    "to": Number,
    "timeout": Number(seconds)(optional),
    "force_from": (yes|no)(optional),
    "returnurl": String(optional)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Method POST com Token no HEADER:

curl http://ast.opens.com.br/call -H "content-type: application/json" -H "Authorization: Bearer 5d104f0c46bd400cca89818333eff3b3" -d '{"from":"1105","to":"4899991010"}'
1

Method POST com o Token no BODY:

curl http://ast.opens.com.br/call -H "content-type: application/json" -d '{"token":"5d104f0c46bd400cca89818333eff3b3","from":"1105","to":"4899991010"}'
1

Method GET com o Token na URL:

curl 'http://ast.opens.com.br/call?token=5d104f0c46bd400cca89818333eff3b3&from=1105&to=4899991010'
1

Nota sobre versões da API

A API possui mais de uma versão e você pode obter diferentes resultados dependendo da versão que utilizar.

A diferença entre uma versão e outra fica comentada na definição dos parâmetros abaixo.

Para acessar a API de uma versão específica passe em sua request o parâmetro version=VERSION.

Atualmente existem 2 versões:

  • v1 : opção default caso nenhuma versão seja indicada
  • v2 : versão em fase de staging, homologação.

# Onde

Item Type Option Description
to String required Número à ser discado
timeout Int(in seconds) optional Este parâmetro indica o tempo de tentativa para conectar com o número from , por default este tempo é 12 segundos. Caso o chamador não atenda e complete a ligação neste tempo a API retornará um erro de lost-call.
returnurl String optional Callback URL para retorno com o status da ligação realizada. Após o desligamento da chamada o sistema irá retornar seu status em formato JSON no corpo da requisição usando método POST
from String required Código do agente ou do ramal que está solicitando a ligação.
force_from yes OR no optional Por padrão a ligação é realizada e para diferenciar de uma ligação feita manualmente pelo Operador, a API adiciona na frente do número de Origem 0000 , alterando a origem para 0000XXXX, onde XXXX é o número do Operador que solicitou a ligação. Este parâmetro fideliza a origem da request no número exato de quem solicitou a ligação, não acrescentando o 0000 à frente do número.
callerid String optional Caso seu pacote de serviços na Opens tenha incluído o Passthrough de DID, este parâmetro permite que você informe aqui um número que será visualizado por quem atender a chamada, um cliente por exemplo. Você pode passar "4839548000" por exemplo e seu cliente receberá a chamada identificando o número de origem como este parâmetro. IMPORTANTE: este parâmetro só tem garantia de funcionamento se você estiver completando ligações pela Cloud da Opens (não por seu PBX local), e seu pacote de serviço possuir este recurso habilitado.
ast.opens.com.br/call String required Endereço da API. Caso você tenha um Servidor SNEP instalado em sua estrutura, você deve fazer o cadastro na Cloud da Opens habilitando este serviço.
map Formatted String optional Este parâmetro espera uma string no seguinte formato: field1:new_field1_name,field2:new_field2_name , map=field:new_field_name,field2:new_field2_name. Este parâmetro serve para substituir campos padrões no retorno do status chamada. Por exemplo, se você precisar que o campo callid seja enviado como external_id basta passar este parâmetro assim: map=callid:external_id e a API irá retornar este novo campo external_id com o valor contido no campo padrão callid.
version String optional (default=v1) Define a versão da API que você quer utilizar. Por padrão a versão é v1. Você pode utilizar a v2 que é a versão em fase de homologação.

# Request Reply

{
    "status":"OK",
    "callstatus":"Trying",
    "message":"Call in Progress",
    "callid":"201612261540101048991613166"
}
1
2
3
4
5
6

# Call Status Reply

Se você informou o parâmetro returnurl, você vai receber uma resposta da API no final da ligação, como esta:

{
    "event":"hangup",
    "action":"click-to-call",
    "calldate":"2016-07-01T15:01:29.983Z",
    "uniqueid":"1496241417.2867",
    "linkedid":"1496241414.2864",
    "callid":"1444447015_20151010_0016__4839548031",
    "from":"1105",
    "to":"4839548031",
    "mainchannel":"Local/8023@default-0000006f",
    "route":"local",
    "audio_file":"14673852852016070112014891613166",
    "audio_url":"http://192.168.10.252/snep/arquivos/load.php?",
    "billsec":"0",
    "callflow":{
        "1496241417.2867":{
            "event":"Newchannel",
            "privilege":"call,all",
            "channel":"Khomp/B0C0-0.0",
            "channelstate":"1",
            "channelstatedesc":"Rsrvd",
            "calleridnum":"<unknown>",
            "calleridname":"<unknown>",
            "connectedlinenum":"<unknown>",
            "connectedlinename":"<unknown>",
            "language":"en",
            "accountcode":"",
            "context":"default",
            "exten":"4839548031",
            "priority":"1",
            "uniqueid":"1496241417.2867",
            "linkedid":"1496241414.2864"
        }
    },
    "customer":[{
        "phone":"4839548031"
    }],
    "owner":[{
        "endpoint":"1105"
    }],
    "request":{
        "returnurl":"http://demo.opens.com.br/post2/"
    },
    "hangupdate":"2016-07-01T15:01:46.340Z",
    "duration":"16"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

# Resultados

Field Description
action Qual ação de origem da chamada. Neste caso "click-to-call", ou seja, gerada através da integração de algum sistema.
audio_file Nome do arquivo de gravação desta chamada.
audio_url URL para acesso ao arquivo de gravação. Este parâmetro muda de uma versão da API para outra. v1 (opção default): este caminho de acesso deve ser completado com o ID da chamada recebido na request ou o nome do arquivo no parâmetro audio_file sem a extensão do arquivo (caso o parâmetro audio_file seja 20201103081110074839548000.wav ficaria 20201103081110074839548000), por exemplo: audio_url (http://clvendas.sipwan.service.pbx.snep7.com/snep/arquivos/load.php?id=) + CALLID (20201103081110074839548000), exemplo http://clvendas.sipwan.service.pbx.snep7.com/snep/arquivos/load.php?id=20201103081110074839548000. v2: URL completa para o arquivo de audio, sem necessidade de modificação ou composição para acessá-lo.
billsec tempo de conversação da chamada. Na v1 (opção default) está definido em segundos. Na v2 está definido em formato time, HH:MM:SS.
callflow Dados do fluxo que a chamada seguiu dentro do PBX local. Por exemplo, caso ela tenha sido transferida internamente, possivelmente a API irá identificar e registrar aqui.
callid ID único da chamada. Usado para controlar todos os status bilhetagem da chamada.
customer Dados do destino da chamada.
duration duração total da chamada. Na v1 (opção default) está definido em segundos. Na v2 está definido em formato time, HH:MM:SS.
event Evento que está sendo notificado. Neste caso, "hangup", ou seja, desligamento da chamada.
hangupdate Data e horário exatos da finalização da chamada.
linkedid ID interno do canal de audio relacionado com o canal original para esta ligação.
owner Dados do chamador, originador da chamada.
owner.endpoint Ramal do Chamador, originador da chamada.
uniqueid ID interno do canal de audio criado para realizar a chamada.