API do Movidesk - Telefonia - Sem controle da fila
10 min
Criado por Heloisa Kopsch Hendges em 12/11/2018 16:40
Atualizado por Thiago Tamanini em 28/07/2022 11:57
Importante: Nossas API's possuem um limite de 10 requisições por minuto para garantir um comportamento saudável no seu uso. Caso você tenha um cenário específico que precise aumentar o uso, entre em contato com o nosso time de atendimento para análise de viabilidade. Saiba mais sobre horários e limites das API's
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

  1. 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.