https://api.movidesk.com/public/v1
Telefonia - Sem controle da fila
Ao decorrer desta documentação, estão descritos os procedimentos para utilização da API que integra centrais telefônicas com o Movidesk. É importante que antes de utilizar a API, leia-se a documentação do módulo de telefonia (que você encontrará clicando aqui). Para toda chamada transferida, deverá haver uma chamada API finalizando a chamada. Caso isso não se cumpra, os registros na base de dados referentes às chamadas telefônicas ficarão incompletos.
Layout
Chamada transferida
URL: /asterisk_startTransferedCall Métodos: GET
Propriedade | Tipo | Tamanho | Obrigatório | Descrição |
---|---|---|---|---|
token | Guid | ✓ | Chave API do Movidesk. | |
queueId | int | 10 | ✓ | ID da fila, deve ser o mesmo informado no cadastro de grupo de telefonia no Movidesk. |
clientNumber | string | 128 | ✓ | Número do telefone que está efetuando a chamada. |
id | string | 256 | ✓ | Identificador único da chamada efetuada. Obs.: Somente será possível relacionar um id único de chamada para um ticket. De tal forma que, não será possível associar um id repetido para um ticket. |
branchLine | string | 128 | ✓ | Ramal do agente para qual a chamada foi transferida. |
callDate | datetime UTC | * | Data do recebimento da chamada. A data informada deve estar no formato yyyy-MM-ddThh:mm e em UTC*. *Se a data não for informada, será considerada a data atual. | |
transferDate | datetime UTC | * | Data em que a chamada foi transferida para o agente. A data informada deve estar no formato yyyy-MM-ddThh:mm e em UTC*. *Se a data não for informada, será considerada a data atual. |
Chamada finalizada
URL: /asterisk_completedCall Métodos: GET
Propriedade | Tipo | Tamanho | Obrigatório | Descrição |
---|---|---|---|---|
token | Guid | ✓ | Chave API do Movidesk. | |
id | string | 256 | ✓ | Identificador único da chamada efetuada. Deve ser o mesmo que foi informado no método de chamada transferida. Obs.: Somente será possível relacionar um id único de chamada para um ticket. De tal forma que, não será possível associar um id repetido para um ticket. |
link | string | max | OBSERVAÇÃO: Mesmo vazio, este parâmetro deve ser informado. | Link com a gravação da chamada. O mesmo sera incluído na descrição da ação do ticket respectivo a ligação. |
completedDate | datetime UTC | * | Data de finalização da chamada. A data informada deve estar no formato yyyy-MM-ddThh:mm e em UTC*. *Se a data não for informada, será considerada a data atual. |
Chamada cancelada/abandonada
URL: /asterisk_startCanceledCall Métodos: GET
Propriedade | Tipo | Tamanho | Obrigatório | Descrição |
---|---|---|---|---|
token | Guid | ✓ | Chave API do Movidesk. | |
queueId | int | 10 | ✓ | ID da fila, deve ser o mesmo informado no cadastro de grupo de telefonia no Movidesk. |
clientNumber | string | 128 | ✓ | Número do telefone que cancelou/abandonou a chamada. |
id | string | 256 | ✓ | Identificador único da chamada cancelada/abandonada. Obs.: Somente será possível relacionar um id único de chamada para um ticket. De tal forma que, não será possível associar um id repetido para um ticket. |
callDate | datetime UTC | * | Data do recebimento da chamada. A data informada deve estar no formato yyyy-MM-ddThh:mm e em UTC*. *Se a data não for informada, será considerada a data atual. | |
canceledDate | datetime UTC | ✓ | Data de cancelamento/abandono da chamada. A data informada deve estar no formato yyyy-MM-ddThh:mm e em UTC*. *Se a data não for informada, será considerada a data atual. |
Atualizar link da gravação da chamada
URL: /setMadeCallLink Métodos: POST
Propriedade | Tipo | Tamanho | Obrigatório | Descrição |
---|---|---|---|---|
token | Guid | ✓ | Chave API do Movidesk. | |
id | string | 256 | ✓ | Identificador único da chamada efetuada. Deve ser o mesmo que foi informado no método de chamada recebida. Obs.: Somente será possível relacionar um id único de chamada para um ticket. De tal forma que, não será possível associar um id repetido para um ticket. |
Link | string | 256 | Link com a gravação da chamada. O mesmo será incluído na descrição da ação do ticket respectivo à ligação. |
*UTC: O Tempo Universal Coordenado (do inglês Universal Time Coordinated) é o fuso horário de referência a partir do qual se calculam todas as outras zonas horárias do mundo. Ex: Se o seu fuso horário for o de Brasília (UTC-03:00) e o horário atual for 15h30, o horário UTC será 18h30.
Trabalhando com os dados
Para ter acesso aos dados é necessário que previamente seja gerada uma chave para a API
Para gerar uma chave para a API (token), acesse ao Movidesk, vá em Configurações / Conta / Parâmetros e na guia ambiente clique no botão "Gerar nova chave" caso ainda não tenha uma criada.
Você poderá repetir essa operação sempre que quiser gerar uma nova chave de acesso, mas lembre-se que ao gerar uma nova chave, todos os programas que utilizarem a chave antiga irão parar de funcionar.
Fluxos que devem ser seguidos
Cenário feliz
Central recebe chamada telefônica -> Central realiza transfere a ligação para o ramal do agente e realiza chamada API para o método asterisk_startTransferedCall -> Movidesk abre automaticamente tela para controle da chamada telefônica para o agente para qual a chamada foi transferida -> Central identifica que a chamada foi finalizada e realizada chamada API para o método asterisk_completedCall -> Movidesk fecha automaticamente tela que estava aberta para o agente e realiza os trâmites necessários no ticket gerado/associado à ligação.
Chamada transferida
GET: https://api.movidesk.com/public/v1/asterisk_startTransferedCall?token=155cac97-f203-4bb8-86e1-aa4cb8781f3e&queueId=1&clientNumber=4733990777&id=3&branchLine=5252&callDate=2018-5-1T17:00:00&transferDate=2018-5-1T17:02:00
Retorno: Status 200. Nesse momento a chamada aparecerá no Movidesk na fila de chamadas em andamento e a tela para controle de chamada aparecerá automaticamente para o agente com o ramal informado (no exemplo, 5252).
Chamada finalizada
GET: https://api.movidesk.com/public/v1/asterisk_completedCall?token=155cac97-f203-4bb8-86e1-aa4cb8781f3e&id=3&link=https://www.linkdagravacaodachamada.com.br&completedDate=2018-5-1T17:20:00
Retorno: Status 200. Nesse momento a chamada sairá das filas do Movidesk e a tela para controle de chamada será fechada automaticamente. Será adicionada a ação com a gravação da chamada no ticket referente a ligação.
Cenário alternativo
- Central recebe chamada telefônica -> Central considera como chamada cancelada/abandonada e realiza chamada API para o método asterisk_startCanceledCall -> Movidesk gera ticket automaticamente com origem de chamada cancelada e gera ação no ticket com descrição da chamada.
Chamada cancelada/abandonada
GET: https://api.movidesk.com/public/v1/asterisk_startCanceledCall?token=155cac97-f203-4bb8-86e1-aa4cb8781f3e&queueId=1&clientNumber=4733990777&id=3&callDate=2018-5-1T17:00:00&canceledDate=2018-5-1T17:20:00
Retorno: Status 200. Esse método deve ser chamado quando o cliente cancelar/abandonar a chamada antes de ela ser de fato transferida para o agente. Nesse caso será gerado automaticamente um ticket com origem chamada cancelada e com uma ação contendo as respectivas informações.
Exemplo de código fonte na linguagem C# da chamada da API
Método GET
try
{
var response = await SendAsync("https://api.movidesk.com/public/v1/asterisk_startTransferedCall?
token=SEUTOKEN&queueId=1&clientNumber=4733990777&id=3&branchLine=5252&callDate=2018-5-1T17:00:00&transferDate=2018-5-1T17:02:00",
NULL, "GET", "application/json");
}
catch (WebException ex)
{
var response = new StreamReader(ex.Response.GetResponseStream()).ReadToEnd();
}
public static async Task<string> SendAsync(string uri, string content, string method, string contentType)
{
var req = WebRequest.Create(uri);
req.ContentType = contentType;
req.Method = method;
using (var stream = await req.GetRequestStreamAsync())
using (var streamWriter = new StreamWriter(stream))
{
await streamWriter.WriteAsync(content);
}
var httpResponse = (HttpWebResponse)await req.GetResponseAsync();
using (var stream = httpResponse.GetResponseStream())
{
if (stream == null)
return null;
using (var streamReader = new StreamReader(stream))
{
return await streamReader.ReadToEndAsync();
}
}
}
Os retornos são detalhados na variável response e devem ser tratados seguindo essa documentação.